Bound integer schema values to the JavaScript safe-integer range (§2.2 Data Definitions)

[hdamker]

Problem description

§2.2 (Data Definitions) requires integer properties to specify format and minimum/maximum, but sets no upper bound on their magnitude. OpenAPI permits the full int64 range, so an API may declare maximum: 9223372036854775807. Values above the JavaScript safe-integer range (9007199254740991, 2^53−1) cannot be represented exactly by the JSON/JavaScript tooling used across the CAMARA API lifecycle and are silently rounded — 9223372036854775807 becomes 9223372036854776000. The published artifact then carries a constraint that differs from the source contract, with nothing flagging the change.

Possible evolution

Add a normative constraint to §2.2: numeric schema values (minimum, maximum, default, example, …) MUST lie within [-9007199254740991, 9007199254740991] (Number.MAX_SAFE_INTEGER). A property that genuinely needs a larger range MUST be modeled as a string with an appropriate pattern, since JSON/JavaScript consumers cannot reliably handle integers beyond 2^53 anyway.

Suggested wording for the §2.2 integer bullet:

If the data type is integer, format (int32 or int64) and range (minimum and maximum) MUST be specified. Numeric schema values MUST lie within the safe-integer range [-9007199254740991, 9007199254740991] (Number.MAX_SAFE_INTEGER); values outside it are silently rounded by JSON/JavaScript tooling and MUST instead be modeled as a string with an appropriate pattern.

This limit will be enforced by a rule in the CAMARA validation tooling, which also keeps the release bundling step producing correct artifacts.

Alternative solution

Non-normative guidance only, without a MUST or a check. Rejected: the mutation is silent and reviewers reasonably treat the bundled snapshot as authoritative, so guidance alone would not prevent corrupted constraints from shipping.

Additional context

Observed in a real release artifact; the precision loss originates in an upstream bundler issue (Redocly/redocly-cli#1389, open since January 2024). int32 values are inherently within range, so the constraint affects only int64; floating-point precision is a separate concern, intentionally out of scope. Tracking: camaraproject/tooling#331

[hdamker]

@camaraproject/commonalities_codeowners Any comments? WDYT which maximum value should be used if there is no natural domain specific maximum?

[PedroDiez]

Hi @hdamker,
Fine with the proposal and the Suggested wording for the §2.2 integer bullet.
From pragmatical point of view it will be quite unprobable to find a scenario where such a range is overpassed and need to model as a string

[tlohmar]

I would assume that not all API provider functions are implemented in JavaScript. For example, python supports a different constant than Number.MAX_SAFE_INTEGER for its max integer range.

Do other (popular) programming languages have similar issues?

[rartych]

OpenAPI Format Registry gives the same recommendation:

Representation as a JSON string is recommended for values outside the 53-bit range (-9007199254740991 through 9007199254740991) as this avoids problems with recipients that parse JSON numbers into binary64 memory representation.

[tlohmar]

aha, and the motivation does not mention JavaScript nor Number.MAX_SAFE_INTEGER (the JavaScript constant).

[cnzj-Gc]

@hdamker We've applied maximum: 9007199254740991 to the four integer fields and fixed S-031 with a description for records.items. A new snapshot has been created in #61. Please let us know if anything else is needed.

[tlohmar]

Just wondering, would it make sense to recommend the usage of data type number with a multipleOf: 10, instead of an integer?

It seems that the data type number is safer from an OWASP perspective, since no range limits needed.

[hdamker]

@tlohmar Using number instead of integer would not avoid the problem: JSON numbers are parsed into double-precision (binary64) representation by many recipients regardless of the declared OpenAPI type — that is exactly the interoperability issue the OpenAPI Format Registry describes for values outside the 53-bit range. It would also lose the integer semantics that code generators and validators rely on, and explicit ranges remain advisable for number properties as well (unbounded numeric input is an API security concern in its own right). So the PR keeps the integer type with the range requirement, with string representation as the escape hatch for genuinely larger domains, as recommended by the registry.

[hdamker]

Created #667 based on the discussion, including the comments in Monday's Commonalities meeting (referring to OpenAPI Format Registry instead to Java/Javascript).