Describe integer fields with JSON types and bound the descriptor size

[BobDu]

#1249 made the I-JSON limitations of RFC 7493 a MUST for all JSON content in this specification, and RFC 7493 section 2.2 states that a sender cannot expect a receiver to treat an integer outside [-(2^53)+1, (2^53)-1] as an exact value. For the specification to be self-consistent the range permitted for size therefore has to be a subset of that interval, and today it is not: defs-descriptor.json allows values up to 9223372036854776000.

RFC 7493 attaches no requirement keyword to that interval; it only says that values outside it cannot be expected to be exact. Specifications built on I-JSON generally tighten it into a requirement so that values stay exact across implementations. RFC 8620 section 1.3 defines UnsignedInt as an integer where "the value MUST be in the range 0 <= value <= 2^53-1", and section 6.1 applies it to a directly comparable field: the size in octets of an immutable blob addressed by an id. RFC 9535 section 2.1 requires integers relevant to processing to be "within the range of exact integer values defined in Internet JSON (I-JSON) ..., namely within the interval [-(2^53)+1, (2^53)-1]".

This narrows the upper bound in theory, but it puts no valid existing data at risk: with the hardware available today an image cannot approach petabyte scale, and if that ever changes it will be a v2 concern.

Separately, this specification should be language neutral, and int64 is a Go type name. The specification only needs to state that the value is an integer and give its bounds; which data type an implementation uses is the implementation's choice and outside the scope of the specification. int is not a JSON type either, so schemaVersion in manifest.md and image-index.md is changed to integer for consistency.

Changing the prose does not imply changing the Go types, which would be a breaking change. It only clarifies the specification document so that it is self-consistent and leaves no room for ambiguity, and it describes the current situation more closely, since oci-spec-rs defines the field as u64.

Related: #153, #350, https://github.com/youki-dev/oci-spec-rs/blob/42a237132bcaf7c6a753be0e1d7e309b7298fb5a/src/image/descriptor.rs#L40

[tianon]

Can you please elaborate succinctly on the specific problem you're trying to solve? I have read your description, but I don't really see a specific problem in it.

[BobDu]

The initial issue I found was that both of the following schemas use 9223372036854776000 as the maximum value of an int64, even though the actual maximum is 9223372036854775807:

image-spec/schema/defs-descriptor.json

Line 13 in af26a05

"maximum": 9223372036854776000

image-spec/schema/defs.json

Line 22 in af26a05

"maximum": 9223372036854776000

I initially intended to submit a PR that simply corrected the value to 9223372036854775807.

However, I then realized that this would not address the underlying interoperability issue. RFC 7493 states that a sender cannot expect a receiver to preserve integers greater than 2^53 - 1 exactly (error in the maximum value here is likely due to this reason), because many JSON implementations represent numbers using IEEE 754 binary64 values.

Because size represents an exact byte count, a more fundamental solution is to restrict it to the I-JSON exact-integer range, with a maximum of 2^53 - 1.