Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Schema Objects to JSON Schema Draft 2019-09 #1977

Merged
merged 7 commits into from
Jan 9, 2020

Conversation

philsturgeon
Copy link
Contributor

@philsturgeon philsturgeon commented Jul 18, 2019

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.

  • @handrews "We should probably make sure none of the formats added in the newer draft conflict with the ones OpenAPI defines."
  • @handrews "At most you might want to check if we have any slight incompatibilities for readOnly and writeOnly which were moved/added to the validation spec in [Draft 07]"

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 exlusiveMinimum and exclusiveMaximum can 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 const are 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:

Screen Shot 2019-07-18 at 17 19 32

Screen Shot 2019-07-18 at 17 19 35

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:

  • Provide guidance in the form of blog posts (I got this)
  • Common tooling (Stoplight got this for JS)
  • JSON Schema tools can now be used directly, instead of building OpenAPI-based tooling which is similar then tweaking it... 🤦‍♂

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.

@philsturgeon philsturgeon changed the base branch from master to v3.1.0-dev July 18, 2019 14:53
@philsturgeon philsturgeon force-pushed the json-schema-update branch 2 times, most recently from 3cf26af to dd328b7 Compare July 18, 2019 14:55
@philsturgeon philsturgeon changed the title Updated OpenAPI Schema Objects to JSON Schema Draft 08 Update Schema Objects to JSON Schema Draft "08" Jul 18, 2019
@handrews
Copy link
Member

@philsturgeon did you mean "picking up from where #1766 left off"? You linked back to this PR in your actual description.

versions/3.1.0.md Outdated Show resolved Hide resolved
versions/3.1.0.md Outdated Show resolved Hide resolved
versions/3.1.0.md Outdated Show resolved Hide resolved
versions/3.1.0.md Outdated Show resolved Hide resolved
versions/3.1.0.md Outdated Show resolved Hide resolved
@philsturgeon
Copy link
Contributor Author

@darrelmiller I have addressed you latest round of feedback, please lmk what you think!

versions/3.1.0.md Outdated Show resolved Hide resolved
@fmvilas
Copy link

fmvilas commented Aug 9, 2019

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

@darrelmiller
Copy link
Member

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

@philsturgeon
Copy link
Contributor Author

@fmvilas asked a fantastic question:

One last question: is the OpenAPI schema going to allow extra properties as JSON Schema does? I mean, without counting the extensions. For instance:

type: string
whatever: "whatever value"

Would this be a valid OpenAPI schema?

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.

@handrews
Copy link
Member

@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-x--prefixed extension keywords through patternProperties.

versions/3.1.0.md Outdated Show resolved Hide resolved
@philsturgeon philsturgeon changed the title Update Schema Objects to JSON Schema Draft "08" Update Schema Objects to JSON Schema Draft 2019-09 Sep 19, 2019
philsturgeon pushed a commit to philsturgeon/OpenAPI-Specification that referenced this pull request Feb 3, 2020
approved by @tedepstein just forgot to add it to OAI#1977.
Ocramius added a commit to Ocramius/core that referenced this pull request Feb 20, 2020
…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
teohhanhui pushed a commit to Ocramius/core that referenced this pull request Feb 27, 2020
…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
DanielHabenicht added a commit to CovOpen/CovQuestions that referenced this pull request Apr 26, 2020
(we were using 3.1 draft, or respectivly a more up to date json schema)
 see: OAI/OpenAPI-Specification#1977
soyuka pushed a commit to api-platform/json-schema that referenced this pull request Mar 21, 2023
…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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.