-
Notifications
You must be signed in to change notification settings - Fork 9.1k
Description
Hi,
I started reading the 2.0 specification and immediately encountered a serious cross-language compatibility problem.
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types
The datatype "long" is defined as a JSON Schema integer
with a format keyword of int64
.
JSON Schema integer
s are of course implemented in JSON using the JSON number type. As RFC 7159 points out, although the JSON specification defines numbers as unbounded, the reality is that languages can and do refuse to deserialize numbers outside of certain ranges; most notably in JavaScript, where all JSON numbers are deserialized into the sole JavaScript number type, which is 64-bit floating point and therefore cannot handle integers larger than about 2^53.
https://tools.ietf.org/html/rfc7159#section-6
The Google Discovery Document format, which Swagger drew a lot of inspiration from, recognized this problem and defined an int64
format that is backed by a JSON Schema string
, not an integer
. It seems that Swagger/OpenAPI changed this. If you were to actually use the datatype as defined in OpenAPI, you would be locking out all JavaScript clients from using your API.
A real-world example of this is Twitter's APIs, which initially provided tweet IDs as a JSON number, and then discovered that JavaScript clients weren't going to be able to handle that, so they had to add a second, string-based field containing the same value.
I have two proposals to address this issue.
The first is simpler, but does not address the larger problem of unbounded numbers in JSON: redefine the "long" datatype as a string
.
The second is to drop the int32
and int64
formats entirely. Instead, mandate that all instances of integer
and number
types must provide explicit values for maximum
and minimum
to be considered valid. Additionally, do not allow maximum
and minimum
to exceed (2^31)-1
or be smaller than -(2^31)
. This would ensure that JSON numbers are used in the most cross-language compatible way possible.
Additional formats or perhaps common schemas could be added to support larger values via the string
type.