UnsignedByte — GraphQL Custom Scalar

Author – ChilliCream

Date – 2025-12-29

License and Copyright

1Overview

The UnsignedByte scalar type represents an unsigned 8-bit integer. It is intended for scenarios where values are constrained to the range 0 to 255, such as representing color channel values (RGB), small counters, or byte-level data.

Unlike the built-in Int scalar which represents signed 32-bit integers, UnsignedByte provides stronger type safety and validation for values that must fit within an unsigned 8-bit range.

2Recommended name

The recommended name for this scalar is UnsignedByte.

3Result spec

An UnsignedByte scalar must serialize to an integer value in the range 0 to 255 (inclusive).

3.1Examples

These are valid result values:

Value	Explanation
`0`	Minimum unsigned byte value.
`255`	Maximum unsigned byte value.
`128`	Mid-range value.

These are invalid result values:

Value	Why is it invalid
`-1`	Negative values are not allowed.
`256`	Exceeds maximum unsigned byte value (255).
`3.14`	Fractional values are not allowed.
`"128"`	Must be a number, not a string.

4Input spec

An UnsignedByte scalar accepts integer values in the range 0 to 255 (inclusive), both as GraphQL literals and as JSON input values.

Implementations should validate:

Value is an integer (no fractional component)
Value is between 0 and 255 (inclusive)
Value is not negative

4.1Examples

Valid input values:

GraphQL Literal:

mutation {
  setColor(red: 255, green: 128, blue: 0) {
    id
  }
}

JSON input:

{
  "red": 255,
  "green": 128,
  "blue": 0
}

Invalid input values:

Value	Why is it invalid
`-1`	Negative values are not allowed.
`256`	Exceeds maximum unsigned byte value (255).
`3.14`	Fractional values are not allowed.
`"128"`	Must be a number, not a string.

5References

GraphQL Specification – Int — Built-in integer scalar type