Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Update Schema Objects to JSON Schema Draft 2019-09 #1977
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
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.
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
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
2 times, most recently
Jul 18, 2019
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.
Summarizing from today's weekly TSC call, here are my suggestions and comments.
||Allows or disallows sending a
Note that there is no default value specified in the above definition. I don't think we need a default value anymore, and the semantics are clearer without it.
nullable : false and
nullable : true as two separate cases:
nullable : falseis an independent assertion that simply disallows null values, regardless of what may be specified in
type. Like all constraining assertions in JSON Schema, it is unconditional.
nullable : trueworks as a modifier or qualifier of the
As discussed on Slack,
nullable : truehas no effect in the absence of a
typeassertion (direct or inherited), since typeless schemas already allow
nullalong with all of the other types.
The effect of
nullable : trueis conditional, subject to other keywords that can disallow
null, effectively overriding
nullable : true. Tools can detect and warn in cases like this.
@philsturgeon , I tried hard to avoid saying that
nullable : true"adds 'null' to the type array". That's really how I'm thinking about it now. Hopefully the way it's worded is clear enough, without implying any superpowers.