Define type: "integer"

[ralfhandl]

Part of

• Explicitly mention type: "integer" in definition of Schema Object #4038

[handrews]

Why are we defining integer instead of leaving it to JSON Schema, which is very precise on this matter?

[ralfhandl]

Why are we defining integer instead of leaving it to JSON Schema, which is very precise on this matter?

This is a good question, although it comes a little too late. OAS 3.0.0 to 3.1.0 all explicitly define "integer" as an allowed value of the type keyword in section Data Types:

Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. Models are defined using the Schema Object, which is a superset of JSON Schema Specification Draft 2020-12.

This PR only tries to make the existing definition more precise and mention this extension in the Schema Objects section in addition to the Data Types section.

We cannot remove this feature in a minor version, let alone a patch version.

[handrews]

What OpenAPI does with "integer" and formats can't change JSON Schema. It doesn't matter if it's been that way in the spec and not been noticed or not.

[handrews]

I think the correct thing to do here is to note that JSON Schema only scopes formats to its data model types (number, string, boolean, null, object, array), and therefore the text of the OAS has been corrected to use "number" rather than "integer". We can add wording to the effect that this has nothing to do with the type keyword if we want.

Since this is a very tricky area, I would be happy to write up a PR that aligns with JSON Schema.

[handrews]

Posted PR #4045

[handrews]

I would prefer to backport the language about mathematical integers from #4045

[handrews]

Scratch the previous comment- I did not realize this was in the Schema Object section (there are way too many PRs and issues on this at once right now). I am strongly against this change. The presence of "integer" as a value for type is standard JSON Schema and should not be repeated. That just adds to confusion by including it in a list of exceptions when it is not an exception.