Openapi-specification: OAS and data models? Alternate schema languages?

[darrelmiller]

How do we support future versions of JSON-Schema? What if there are breaking changes?
Should we support other Schemas?
Can we define a mapping between OpenAPI Schema and other schemas?
How does this issue fit with the review of the OAI charter?

[handrews]

From the JSON Schema project's perspective, here are some key points. None of this is an attempt to dissuade OAI from supporting other schema systems. JSON Schema will never be everything to everyone (nor will any other system).

_NOTE: I am promising some things that I haven't 100% sold the rest of the JSON Schema project members on, but I'm fairly confident that we will get these things done somehow. Also, OAS putting some weight behind things would make them easier to sell!_

We don't expect to break existing core and validation keywords

• draft-06 _should_ be the last with breaking changes to core or validation
• We can commit to not contradicting well-established OAS keywords such as deprecated
• $schema may change, but OAS doesn't use it so that's fine
• I hope to get us to IETF working group status for core and validation probably after draft-09
• Hyper-Schema will be on an independent timeline as it is significantly less mature
• For newly (draft-08 or later) added keywords, we may change them based on feedback, but hopefully OAI would be part of that feedback cycle

There isn't much contradiction left to resolve

• nullable needs to be addressed, hopefully per #1389 as changing this on the JSON Schema side would be a very major breaking change for us, and the approaches _cannot_ easily co-exist
• We have examples (plural) rather than example (singular), but these _can_ easily co-exist

draft-08 will substantially improve modularity and extensibility

• Easier to indicate what vocabularies are allowed or required
• A more clear framework for defining extension keyword behavior
• Hopefully some guidance on defining and using a restricted subset of a vocabulary

We will fix the "Composition and Inheritance" awkwardness

• We will add a data definition / code generation vocabulary
• This new vocabulary should be part of or immediately following draft-08
• It would disambiguate validation constructs that can't easily be mapped to code (maps vs classes, lists vs sets, etc.)
• It would provide for an inheritance / polymorphism approach that more naturally bridges the gap between validation and object-oriented programming languages
• We hope OAI is a major participant in defining this vocabulary, as it is probably the largest code-generating ecosystem that uses JSON Schema
• The result should be simpler than discriminator (at least for us :-), although the approaches can co-exist
• A solution to the confusion around additionalProperties and allOf _should_ be part of draft-08

We are very interested in addressing concerns from OAS

I know that during the development of OAS 3.0, JSON Schema was still a mostly moribund project. draft-wright-*-01 was published right near the end, but since it was a bug fix we still had not shown that we were really moving forward. We have now published three drafts on a roughly six-month timeline, and are pretty far along in making decisions for a fourth.

Please bring up any concerns that you may have given up on simply because there was no one available to work on them on the JSON Schema side, or because JSON Schema editors who have left the project declined to address them years ago.

The OAS community makes up a substantial percentage of the JSON Schema community, and it is in our best interests to ensure that your use cases are supported as best we can.

[ralfhandl]

Looking forward to the fix for Composition and Inheritance.

[handrews]

The major components of draft-08 have been more or less settled on, and anyone can track progress with the draft-08 milestone

Of particular relevance are:

• json-schema-org/json-schema-spec#561 (basic multi-vocabulary support)
• json-schema-org/json-schema-spec#556 (unevaluatedProperties)

I would particularly encourage feedback from OpenAPI users on 561 as it lays the groundwork for fixing things like composition vs inheritance.

You don't need to follow all of it, but since there's still some debate over how much additional vocabularies would be used, a bunch of thumbsup or similar, or comments about how you would have a use for making additional properties more manageable and interoperable would be a big help.

I hope to publish draft-08 by the end of May, and absolutely no later than the end of June.

[Relequestual]

We're still a little way off on publishing draft-8, but we're continuing to make progress! =]

[tiangolo]

I would love to be able to declare the version of JSON Schema to draft-07 (or draft-08 when available).

There isn't much contradiction left to resolve

There's also the change of exclusiveMinimum and exclusiveMaximum from boolean to number:

Changed "exclusiveMaximum"/"exclusiveMinimum" from boolean modifiers of "maximum"/"minimum" to independent numeric fields.

That's how I found the difference between the current OpenAPI JSON Schema version used and the current "latest": https://github.com/tiangolo/fastapi/issues/240

---

My specific use case is that FastAPI generates OpenAPI schemas from application code. For the JSON Schemas it uses Pydantic, and Pydantic generates JSON Schema with draft-07.

So, I'm already generating OpenAPI with JSON Schema draft-07. I would love to have a way to declare the version of JSON Schema explicitly.

[jugaadi]

JSON Schema v2019-09 has been published