Is integer to number a breaking change for format int64?

[sensiblewood-ozone]

I've noticed that the base type for the format value int64 has gone from integer to number: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md?plain=1#L203

I would assume that 3.0.4 is therefore not a patch release? For me this constitutes a breaking change.

Please can you clarify how this is classified as a patch rather than breaking change. Thank you.

[handrews]

@sensiblewood-ozone the original was an error, and there was an incredibly long discussion about it which I can dig up if you want. format applicability is based on JSON data types, and integer is not a JSON data type. It's a JSON Schema constraint that is shorthand for the JSON number data type plus a "multipleOf": 1 constraint. So it's not a breaking change because JSON Schema does not allow defining formats specific to integer.

If JSON Schema did allow that, then applying the schema {"format": "int64"} to the instance value 1.2 would pass validation, because the format would not apply to 1.2 (it's not an integer), and JSON Schema keywords that do not apply always pass validation.

Which is clearly not what you want. In practice, most people also include "type": "integer" which prevents the problem, but really the way it was written before was completely wrong and could cause the exact opposite behavior from the behavior that was desired.

The current way is correct and will work as it was always intended to whether you use type or not.

[sensiblewood-ozone]

@handrews just for the record. In the wild, I am seeing tools adopt 3.0.4 and fail validation of a given API description where they passed at 3.0.3 due to this change. Regardless of the correctness or incorrectness of JSON Schema and the original specification, this is a change in behaviour that for me constitutes a breaking change.

The horse has already bolted on this, as 3.0.4 is out in wild, so happy to close the ticket.

[handrews]

@sensiblewood-ozone I don't understand the failure mode here. What is failing?

[handrews]

To be a bit more clear, how is it possible for this to impact the validation of an OAD? The applicable type is not something you can validate. It has nothing to do with the type keyword, it just has to do with the underlying data. I cannot come up with any way that changing 3.0.3 to 3.0.4 could result in a detectable problem. It has always been valid to pair any type value (or none at all) with any format value. Some such combinations make sense, and some don't.

The presence, absence, and value of the type JSON Schema keyword is completely irrelevant to format. Any tool that considers an OAD to be invalid because of the value of format plus the value or absence of type is in violation of both the JSON Schema and OpenAPI Specifciations, and a bug should be filed. That is true for every version of JSON Schema and OpenAPI. There has never been a restriction on format based on the type keyword. Never. In either spec.

[handrews]

If tools want to flag nonsensical type/format combinations, then there's no reason to object to combining either type: number, format: int64 or type: integer, format: int64. If format is actually validated (a big if), then these have the same effect. If format is not validated, then validation depends on type.

So in fact you do not want to change the value of type from integer to number as that will cause problems when a validator ignores format.

[handrews]

I just thought to check the spec and this is explicitly addressed (although it's buried a bit so it's understandable to miss it):

As noted under Data Type, both type: number and type: integer are considered to be numbers in the data model.

The column showing formats and types is labeled "JSON Data Type" to try to make it clear that it's not a schema type.

Perhaps a blog post and a page on the learn site are in order?

[karenetheridge]

In the wild, I am seeing tools adopt 3.0.4 and fail validation of a given API description where they passed at 3.0.3 due to this change.

What tool is doing this? Do you know what underlying JSON Schema evaluator it is using? We should report a ticket there as this behaviour sounds non-compliant. In addition, we can have this implementation add itself to the automated test suite in the json-schema organization, so we can see a report of which ways it is non-compliant (and also allow openapi tooling to select a better alternative).

[sensiblewood-ozone]

@handrews @karenetheridge thanks for all the clarifications. I agree based on the above that this does indeed constitute a patch not a breaking change.

Looking at the specification this should be deterministic enough as a directive on format usage, with the focus on "non-validating" i.e. use format as a hint, not a means to throw a wobbly:

As described in that specification, format is treated as a non-validating annotation by default; the ability to validate format varies across implementations.

However, this gives wriggle room to error rather than ignore, due to MAY - if it was SHALL, it would be golden:

Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified

The Engineering team where I work have reported this being an issue in Postman. This is the error message they received on an existing integer property that previously validated.

Schema is valid | Error: unknown format "int64" is used in schema at path "#/properties/Data/properties/Customer/properties/BackgroundInformation/allOf/0/properties/NumberOfDependents"

I need to dig into this in more detail by replicating the test teams set-up and provide significantly more information. Please bear with me on this. I'll report back here with the goods.

[handrews]

@sensiblewood-ozone

However, this gives wriggle room to error rather than ignore, due to MAY - if it was SHALL, it would be golden:

Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified

Hmm... yeah that clause is actually redundant, which makes it misleading. JSON Schema guarantees that type applies whether format does or not, so it's a natural consequence that this fall-back happens. There's no MAY or SHALL or anytihng else needed about it- it's just the result of other MUST/SHALL requirements that already exist, which would be true even if that sentence wasn't there.

[sensiblewood-ozone]

@handrews @karenetheridge turns out this was a false alarm. It was configuration of the tools themselves (and the tool wasn't Postman...) that cause the failure. Apologies for causing confusion and uncertainty on this.

Hmm... yeah that clause is actually redundant, which makes it misleading

Removing the second sentence in the guidance would be great in a future version.

Closing this puppy down. Thanks again for all the guidance above.

[handrews]

@sensiblewood-ozone glad to hear it was a configuration problem- and thanks for filing, it's a very confusing area and always better safe than sorry.