How Large Is Your Integer?

Specification scope: Core only.

Call a field integer and the awkward questions arrive later. How wide is it? Can it be negative? Will a JavaScript consumer round it before generated code ever sees it? JSON Structure puts signedness and widths from 8 through 128 bits in the type declaration, then uses a JSON representation that preserves the declared range.

Ten names, ten ranges

The integer family is regular:

Type	Range
`int8`	−2⁷ through 2⁷−1
`uint8`	0 through 2⁸−1
`int16`	−2¹⁵ through 2¹⁵−1
`uint16`	0 through 2¹⁶−1
`int32`	−2³¹ through 2³¹−1
`uint32`	0 through 2³²−1
`int64`	−2⁶³ through 2⁶³−1
`uint64`	0 through 2⁶⁴−1
`int128`	−2¹²⁷ through 2¹²⁷−1
`uint128`	0 through 2¹²⁸−1

The familiar integer type is an alias for int32. It exists for JSON Schema compatibility, but it still has a concrete 32-bit range in JSON Structure.

A schema for counters and identifiers can therefore state its intended machine model directly:

{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://example.com/schemas/sequence-state",
  "name": "SequenceState",
  "type": "object",
  "properties": {
    "partition": { "type": "uint8" },
    "attempt": { "type": "uint16" },
    "recordCount": { "type": "uint32" },
    "nextSequence": { "type": "uint64" },
    "traceValue": { "type": "uint128" }
  },
  "required": [
    "partition",
    "attempt",
    "recordCount",
    "nextSequence",
    "traceValue"
  ],
  "additionalProperties": false
}

Here is a valid instance:

{
  "partition": 12,
  "attempt": 3,
  "recordCount": 4294967295,
  "nextSequence": "9007199254740993",
  "traceValue": "340282366920938463463374607431768211455"
}

Notice where the quotes begin. They are part of the type contract.

The 53-bit boundary

JSON’s grammar permits numeric literals beyond the exact integer range of IEEE 754 binary64. RFC 8259 states that integers in the inclusive range −(2⁵³−1) through 2⁵³−1 are interoperable in the sense that implementations agree exactly on their numeric values. That statement assumes the limits of binary64 implementations.

That is why int8 through uint32 use unquoted JSON numbers, while int64, uint64, int128, and uint128 use strings. The string syntax follows the JSON integer grammar: no decimal point, no exponent, and no leading decoration. Signed types permit a minus sign; unsigned types do not.

The instance above makes the issue visible. 9007199254740993 is one greater than the largest exactly interoperable integer. Parsing it through binary64 as a JSON number can change it. Parsing the quoted representation as uint64 cannot.

The instance representation therefore changes at 64 bits. That change prevents a parser from delivering a nearby integer with no warning.

Bounds do not name a machine type

JSON Schema’s integer describes a mathematical property of a JSON number: it has no fractional part. Bounds can narrow the accepted set, so a schema author can spell out the limits of an int64 with minimum and maximum.

That still leaves representation and mapping policy to tooling. A code generator must recognize the particular bounds, decide whether they imply a machine type, and account for parsers that already rounded the input. JSON Structure puts the machine-oriented type name in the schema and changes the JSON representation where exact numeric interchange is not dependable.

Avro names two widths

Avro has int, a signed 32-bit integer, and long, a signed 64-bit integer. Those are proper data-definition types and map predictably into generated code. Avro does not provide core unsigned or 128-bit integer types.

In Avro’s binary encoding, long is not exposed to a JSON number parser, so its 64-bit range is preserved. Avro’s JSON encoding writes int and long as JSON numbers, which means a generic JavaScript JSON path can still lose precision. JSON Structure’s quoted int64 and uint64 representation addresses that path explicitly.

XML starts with arbitrary precision

XML Schema starts from a different numeric foundation. xs:integer has arbitrary precision, and derived types include xs:byte, xs:short, xs:int, xs:long, plus unsigned variants. Facets can define further ranges.

That family declares more integer categories than JSON Schema’s single integer type. The practical difference is the carrier: XML text holds the lexical form for every integer, while JSON distinguishes number and string nodes. JSON Structure uses number nodes through uint32 and string nodes for the 64-bit and 128-bit integer types.

For the example above, nextSequence is a uint64 all the way from JSON text to generated code and storage. No consumer has to reconstruct that decision from a pair of bounds, and the parser gets no opportunity to round it first.