Update Schema Objects to JSON Schema Draft 2019-09 #1977
Conversation
philsturgeon
force-pushed
the
json-schema-update
branch
2 times, most recently
from
3cf26af
to
dd328b7
Compare
philsturgeon
changed the title
philsturgeon
force-pushed
the
json-schema-update
branch
from
dd328b7
to
f01c260
Compare
|
@philsturgeon did you mean "picking up from where #1766 left off"? You linked back to this PR in your actual description. |
|
@darrelmiller I have addressed you latest round of feedback, please lmk what you think! |
|
💯 to this. At AsyncAPI, we'll adopt a superset of Draft-07 for now. It shouldn't be hard to realign again with OpenAPI once this PR is merged. |
|
I see nothing wrong with this PR. That doesn't mean it doesn't cause problems that I am not aware of, but I think this is a good place to start trying to determine what the impact of this change would be on existing users. //cc @OAI/tsc |
|
@fmvilas asked a fantastic question:
What do you think @OAI/tsc @darrelmiller ? OpenAPI Schema Objects disallow "extra properties" but JSON Schema has a default of allowing any properties in and only working with the ones it knows. This can be useful for backwards compatibility, but it can potentially lead to situations where a typo means a keyword isn't actually doing what an author thinks it does. I would lean towards consistency, but if this restriction needs to remain we can have a single note about it elsewhere and not on a per-keyword basis. Basically part of the vocabulary would be "only keywords from OpenAPI Schema Object Vocabulary, JSON Schema Validation, and JSON Schema Core are allowed" and boom that's it. |
|
@philsturgeon one use case I specifically kept in mind while designing the vocabulary vs meta-schema functionality was the idea that OpenAPI could use a meta-schema to forbid non- |
philsturgeon
changed the title
approved by @tedepstein just forgot to add it to OAI#1977.
…nAPI 3.0
OpenAPI 3.1 is not yet released, but fixes nullability in
the way we had fixed it before (via `{"oneOf": [{"type": "null"}, ...]}`) in
OAI/OpenAPI-Specification#1977.
Until OpenAPI 3.1 is released, things like ``{"type": ["integer", "null"]}` are
not valid definitions (because `"null"` is not yet a recognized type).
We'll stick to OpenAPI 3.0 for now, using:
* `{"nullable": true, ...}` for simple types
* `{"nullable": true, "anyOf": [{"$ref": ...}]}` for type references
…nAPI 3.0
OpenAPI 3.1 is not yet released, but fixes nullability in
the way we had fixed it before (via `{"oneOf": [{"type": "null"}, ...]}`) in
OAI/OpenAPI-Specification#1977.
Until OpenAPI 3.1 is released, things like ``{"type": ["integer", "null"]}` are
not valid definitions (because `"null"` is not yet a recognized type).
We'll stick to OpenAPI 3.0 for now, using:
* `{"nullable": true, ...}` for simple types
* `{"nullable": true, "anyOf": [{"$ref": ...}]}` for type references
(we were using 3.1 draft, or respectivly a more up to date json schema) see: OAI/OpenAPI-Specification#1977
…nAPI 3.0
OpenAPI 3.1 is not yet released, but fixes nullability in
the way we had fixed it before (via `{"oneOf": [{"type": "null"}, ...]}`) in
OAI/OpenAPI-Specification#1977.
Until OpenAPI 3.1 is released, things like ``{"type": ["integer", "null"]}` are
not valid definitions (because `"null"` is not yet a recognized type).
We'll stick to OpenAPI 3.0 for now, using:
* `{"nullable": true, ...}` for simple types
* `{"nullable": true, "anyOf": [{"$ref": ...}]}` for type references
Fixes #333
Fixes #397
Fixes #470
Fixes #1026
Fixes #1238
Fixes #1313
Fixes #1368
Fixes #1389
Fixes #1494
Fixes #1523
Fixes #1666
Fixes #1719
Fixes #1766
Fixes #1869
Fixes #1985
Checklist items from #1766 so we can close.
Picking up from where #1766 left off, this PR is helping OpenAPI v3.1 make a non-breaking change, to catch up with JSON Schema's latest draft.
Instead of OpenAPI continuing to confuse everyone by being a JSON Schema draft 05 sub-set, and a super-set, with some notable differences to watch out for, it will now be a JSON Schema draft 2019-09 superset. More info on that here.
The goal here is to help people write pure JSON Schema for their data model if they want to, or write OpenAPI-flavoured JSON Schema if they want to, but we are closing the gaps on what these two things mean. The list of differences is now tiny, only 4 extra keywords, with 2 notes about how
exlusiveMinimumandexclusiveMaximumcan be used in two ways (in order to maintain BC with OpenAPI v3.0).Alternative Solutions
Alternative Schemas are a big topic which needs more work to be done. We should address the JSON Schema divergence issue to make the v3.x branch a happy place to be, and follow up with Alternative Schemas for v3.2 or v4.0, so our XML using friends can play with XML Schema, and all the other good things.
Risks
There are concerns that tooling vendors who work with static languages will have a hard time adding some of JSON Schemas newer more dynamic features. I understand this in theory, but most of JSON Schema's new features like if/then/else, and the old "type can be an array" issue, are just sugar for allOf/anyOf/oneOf, as can be seen in wework/json-schema-to-openapi-schema.
Seeing as allOf, anyOf, oneOf already exist in OpenAPI v3.0, whatever tooling vendors are doing to support that, should be done to support these keywords. Other new things like
constare just an enum of 1.Nothing should be that scary, yet people seem scared, but I think we can overcome in. We need to. JSON is a dynamic format, a property can contain a string one minute, and an object another, and this is pretty common practice for those using evolution. You might start out with a simple string, then decide you need more information and offer an object, deprecating the old way of doing things, and folks move over to use the object. This was an issue for reading JSON in Go for a while, then better JSON tooling came out and its not an issue.
OpenAPI tooling should be able to deal with this too. For example, ReDoc is an awesome open-source documentation generator, and it has no trouble at all with showing oneOf:
The argument I keep hearing is "tooling vendors are complaining about anyOf, allOf, oneOf, because it's hard, so lets not add any more keywords... Meh? Which is the priority here, making lives slightly easier for the tooling vendors by not adding new features, or making lives substantially less confusing for all the users of all the OpenAPI tools by letting them not have to unpack the differences between OpenAPI and JSON Schema? I lose 10% of every day helping people navigate this mess on APIs You Won't Hate, and I'm a tooling vendor at Stoplight.io. I'd rather have a few more complex keywords to figure out for the tooling, than have all the users of that tooling be constantly confused about which keywords they can use when, and how to convert from one to the other because different tools need OpenAPI or JSON Schema.
Anyhow, the tools that support advanced features will end up being more popular than the tools which do not. 🤷♂️
Life for tooling vendors trying to add these new keywords can be simplified in a few ways:
I'd like to dig into this fear of adopting actual JSON Schema further on the OpenAPI slack, so please swing by and throw examples at me. I have heard vague concerns about
patternProperties, but would love to sink my teeth into concrete examples.