Add integer to the list of types supported by the schema object.

[auspicacious]

While reading, I noticed that integer was not included in this list of possible types. Given that integer 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 adds integer 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?

[handrews]

@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.

[auspicacious]

@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 types: 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.

[handrews]

I'm fine with doing some extra cleanup here, but it's very easy to step into murky territory so I'd try to be minimal about the changes.

[handrews]

This should stay "Schema Object" because while I think all fields that directly take a Schema Object are called schema, I'm not 100% sure, and there are other fields that involve references to schema objects (mapping in the Discriminator Object) as well. It's also not true in general that fields with the same name in different Objects have the same value, so it's best to talk about the Schema Object rather than the field.

[auspicacious]

Okay, so there's a few different concepts being conflated here, I think.

As I understand it, this document is titled "Content of Message Bodies" and is providing an overview of how you can use OpenAPI to describe the content of message bodies. If someone is reading these documents in sequence, I think that it is also the first place that they will encounter the use of schema to describe data.

So there are two separate concepts that need to be conveyed: the names of the fields that, together, make up the definition of the content of a message, and, also, the concept of a schema object, which can be used in many places.

I wrote this deliberately to separate the field called schema used at this particular location in a content definition, and the idea of a schema object, which can be used in various different places. In other words, I wrote it this way for the same reason you are asking me not to write it this way, and I'm not clear on your mental model here.

This might be clearer if the "Media Type Object" section above were renamed to "Media Type Field" to help distinguish this more clearly and be more consistent with the "content field" section at the top.

If this is not an appropriate mental model, I think that some more work needs to be done to describe the vocabulary and mental model that is appropriate.

[handrews]

This can just be dropped if we keep "Schema Object" as the section header.

[handrews]

I think it's good to remove the "Depending on the selected type..." language as that's not really how JSON Schema works (you can use all fields at all times, it's just that they don't all apply to every data type, and some combinations are nonsensical- but they are still technically valid).

I'd just leave it as "Schema objects describe the structure of data." The exact relationship between JSON Schema and non-JSON data varies a bit among JSON Schema and OpenAPI versions.

[auspicacious]

Okay, so delete the second sentence, but why not explain that schema objects are nested? That's how they're usually used. I know there's a few fields that only apply to the root, but for this non-normative introduction I think that might be a bit much to start with.

[handrews]

integer is defined by JSON Schema, not OpenAPI (we should ignore any inadvertent discrepancies between the two). Even in OAS 3.0, integer as a type comes from JSON Schema even if the wording suggests otherwise.

I'm also hesitant to get into the exact definition of integer as it changed in subtle ways between certain JSON Schema drafts. It's better to just let folks look at JSON Schema-related docs for that. For example, 1.0 is an integer in the JSON Schema drafts used for 3.1 and (Im 99% sure) 3.0. But (I think?) not in 2.0. I'd just note that JSON Schema adds an integer type to its type keyword for convenience and leave it at that.

[auspicacious]

I was going to save this for an issue, but, although I don't know the context that decision was made in, 1.0 really, really, really should not be considered an integer.

It will cause immediate problems for simple clients in, e.g., Python, if that is allowed:

>>> isinstance(json.loads('1'), int)
True
>>> isinstance(json.loads('1'), float)
False
>>> isinstance(json.loads('1.0'), int)
False
>>> isinstance(json.loads('1.0'), float)
True

and the OpenAPI definition is very clear that 1.0 is not an integer in the OpenAPI schema dialect, which is why I added the definition above.

[handrews]

I realize this isn't phrasing you chose, but all fields are always available. Certain fields apply only to certain types. Putting a maxLength field on an integer is a no-op, but it's not wrong. Also, minimum and maximum work with any number, not just integers. And be careful about type and enum - they always both apply, and it's easy to accidentally create an impossible-to-satisfy schema if you combine them carelessly.

[auspicacious]

I'm pretty sure that a reasonable validator/linter of JSON Schema documents, if one exists, would catch those issues, and my understanding is that this is a non-normative document intended to show how the tools should be used.

Rewriting the first sentence in this way is probably ambiguous enough for this situation:

In addition to type, several more fields can be used to further constrain your data.

[handrews]

@auspicacious

The format registry seems to be defining two new types: 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?

🤦 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.

[auspicacious]

I'm thinking it would be best to go back to the original PR that just adds a single word to the existing document, and maybe revisit the rest of it at a later point after the underlying standards have reached a consensus. Ideally this overview document should be about one good way of doing things, not many almost good ways.

[auspicacious]

Okay, so there's a few different concepts being conflated here, I think.

As I understand it, this document is titled "Content of Message Bodies" and is providing an overview of how you can use OpenAPI to describe the content of message bodies. If someone is reading these documents in sequence, I think that it is also the first place that they will encounter the use of schema to describe data.

So there are two separate concepts that need to be conveyed: the names of the fields that, together, make up the definition of the content of a message, and, also, the concept of a schema object, which can be used in many places.

I wrote this deliberately to separate the field called schema used at this particular location in a content definition, and the idea of a schema object, which can be used in various different places. In other words, I wrote it this way for the same reason you are asking me not to write it this way, and I'm not clear on your mental model here.

This might be clearer if the "Media Type Object" section above were renamed to "Media Type Field" to help distinguish this more clearly and be more consistent with the "content field" section at the top.

If this is not an appropriate mental model, I think that some more work needs to be done to describe the vocabulary and mental model that is appropriate.

[auspicacious]

Okay, so delete the second sentence, but why not explain that schema objects are nested? That's how they're usually used. I know there's a few fields that only apply to the root, but for this non-normative introduction I think that might be a bit much to start with.

[auspicacious]

I was going to save this for an issue, but, although I don't know the context that decision was made in, 1.0 really, really, really should not be considered an integer.

It will cause immediate problems for simple clients in, e.g., Python, if that is allowed:

>>> isinstance(json.loads('1'), int)
True
>>> isinstance(json.loads('1'), float)
False
>>> isinstance(json.loads('1.0'), int)
False
>>> isinstance(json.loads('1.0'), float)
True

and the OpenAPI definition is very clear that 1.0 is not an integer in the OpenAPI schema dialect, which is why I added the definition above.

[auspicacious]

I'm pretty sure that a reasonable validator/linter of JSON Schema documents, if one exists, would catch those issues, and my understanding is that this is a non-normative document intended to show how the tools should be used.

Rewriting the first sentence in this way is probably ambiguous enough for this situation:

In addition to type, several more fields can be used to further constrain your data.

[lornajane]

@auspicacious should we be keeping this pull request open for further updates after the discussion? (I realise it has been a while!)

[auspicacious]

@lornajane Thanks for checking in.

I think that I have been out of the OpenAPI/JSON Schema world for so many years that I would not be able to contribute without investing a lot of time that I don't have available right now. I hope that the concerns I expressed above as I dug deeper into the issue were at least helpful, but it is unlikely that I will be making further updates to this PR.

[handrews]

@auspicacious we ended up adding a small note about type: integer to 3.0.4 (§4.4 Data Types and §4.4.1 Data Type Format) and 3.1.1 (§4.4 Data Types and §4.4.1 Data Type Format).

Regarding 1.0 as an integer, that battle was had by other people years ago, and it's a JSON Schema thing and not an OpenAPI thing. Actually, it's really a JSON thing having to do with what can and cannot be considered interoperable when parsing JSON, so it's quite far out of our control.

Thank you for your efforts here. I do hope that the 3.0.4 and 3.1.1 changes help. Since you won't be able to continue, I'm going to close this.