Open auspicacious opened 6 months ago
@auspicacious thanks for this!
Maybe the OAS should be more explicit about this definitional difference, though?
As one of the main people involved in re-aligning OAS and JSON Schema, I'm confident that any difference between OAS 3.1 and JSON Schema draft 2020-12 is unintentional and perhaps an error. If you'd like to file an issue in the OAI/OpenAPI-Specification repo we can maybe clean up that language in 3.1.1 and 3.2.0.
As for your fix here, I think you are correct that "integer" should be included because it is talking about the type
keyword (which allows "integer"
) and not the JSON data model types (which do not make that distinction). But perhaps we could note that distinction here? I'm not sure what wording would be best, but anything that indicates that JSON does not distinguish between integers and other kinds of numbers, but JSON Schema's type
field does ought to do it.
@handrews I let the scope creep up a bit, but I feel like this way of writing it is probably clearer.
I have another question, which you can push over to an issue I'll try to create in the specification repo when I have a little more time, but is relevant here as well.
For context, I was the author of this issue regarding integer formats eight years ago. I'm doing a little brushing up on the possibility I might be getting back into this space and I'm looking at the format registry you mentioned when closing that issue in January.
The format registry seems to be defining two new type
s: one called stringnumber
and one called numberstring
. I'm missing any potential context on planned revisions to the standard, and I can't find any references to the registry or these types in the current standard, but is this intentional? The Schema Validation draft does not allow the creation of additional types, and it seems like doing so would cause unnecessary challenges for validation and code generation systems.
@auspicacious
The format registry seems to be defining two new types: one called
stringnumber
and one callednumberstring
. I'm missing any potential context on planned revisions to the standard, and I can't find any references to the registry or these types in the current standard, but is this intentional?
🤦 Nope. Those should be string, number
(the order is irrelevant) meaning that the format applies to both numbers and strings, but something is apparently formatted wrong for how that gets rendered. The registry is on the gh-pages
branch in the OAI/OpenAPI-Specification repo. Something will need to get fixed there.
While reading, I noticed that
integer
was not included in this list of possible types. Given thatinteger
is used extensively in this chapter, I assume this was a simple oversight.As an aside, though, I understand that the JSON Schema core specification draft draws a semantic difference between
integer
and the other types and that the OpenAPI specification explicitly addsinteger
as a type with a slightly different definition than the JSON Schema validation draft ("a JSON number without a fraction or exponent part" vs. "any number with a zero fractional part"). This is messy, but it doesn't seem worthwhile digging into these differences in this explainer.Maybe the OAS should be more explicit about this definitional difference, though?