Openapi-specification: Official 3.0 schema?

[jsdevel]

In the schemas directory, I'm not seeing v3.0. Are there plans to release an official jsonschema document?

[darrelmiller]

There are actually two Schemas that are being worked on. One is here https://github.com/OAI/OpenAPI-Specification/pull/1270 and the other is here https://github.com/OAI/OpenAPI-Specification/pull/1236
As JSON Schema cannot fully validate an OpenAPI document we are still not sure how best to include and describe the role of a JSON Schema. Calling it an "official" JSON Schema has the risk of making false promises.

[jsdevel]

As JSON Schema cannot fully validate an OpenAPI document...

I'm not sure I understand what you mean. That previous v2 schema did a pretty good job.

Calling it an "official" JSON Schema has the risk of making false promises.

Hopefully we get an official schema; otherwise, tooling and frameworks will be more difficult to author.

[webron]

@jsdevel the previous v2 schema did a partial job, as will the one for v3. Relying solely on the schema for validation is not good enough.

We _will_ publish a schema, but it is _not_ the source of truth. JSON Schema simply cannot fully validate the spec.

[jsdevel]

I see. As long as we have something close to what we had for v2 then I think we'll be in good shape. I see what you mean now about not being able to fully validate the schema. I personally was happy with how close v2 came.

I really appreciate the work you guys are doing and look forward to receiving the new 3.0 schema as soon as it's ready!

[webron]

You can try using the ones in the PRs for now, one of them will surely be used. I don't expect anything 'official' to be available for at least two weeks.

[darrelmiller]

Hopefully we get an official schema; otherwise, tooling and frameworks will be more difficult to author.

Yes, writing tooling that fully validates the spec is hard work (so was writing the spec :-) ). But hopefully we will only have to do it once for each language.

My concern is that if tooling vendors take a shortcut by depending on JSON Schema to do all the validation we will end up with partially validated documents and potentially incompatibilities between tooling.

[jsdevel]

My concern is that if tooling vendors take a shortcut by depending on JSON Schema to do all the validation we will end up with partially validated documents and potentially incompatibilities between tooling.

I share your concern. It's kind of a catch 22. If you don't provide any schema, the chances for variance is high. If you do provide a schema, the chance for variance is lower, but reliance on the schema will still cause variance to exist.

[handrews]

@darrelmiller wrote:

My concern is that if tooling vendors take a shortcut by depending on JSON Schema to do all the validation we will end up with partially validated documents and potentially incompatibilities between tooling.

This is something that I want to address in the next draft (draft-08, not draft-07 which is in the feature-frozen pre-publication feedback period).

JSON Schema currently does not support extended or restricted vocabularies well. You can declare your meta-schema with $schema but if the tool does not recognize that meta-schema then it is useless. However, if you limit yourself to standard vocabularies, you find this sort of partial-validation situation.

I am trying to build support for a more modular approach to JSON Schema vocabularies. The standard validation vocabulary would be one, and you could declare that you are using that. Tools that understand it will validate properly based only on that vocabulary (so this is the partial validation).

You would also be able to declare and use your own vocabulary, which would be recognized by any tools in your own ecosystem (including plugins to validators that offer an extensible design, as some do to varying non-standardized degrees right now).

So you could make up keywords that would enforce the missing constraints, and declare that you are using those in such a way that tools that you support/endorse/whatever can perform full validation, while standard tools support a graceful degredation to the standard validation vocabulary.

If this sounds of interest, please let me know (probably by email- my email is on the JSON Schema spec- or in an issue at the json-schema-org/json-schema-spec project rather than further comments here). Or if it sounds like a horrible idea, that would be helpful to know as well.

You could still end up with variance this way, particularly if there is no support for your custom vocabulary in someone's chosen language. But there would be a structured, interoperable mechanism to add support. I assert that this would be useful, but it is a controversial proposal so I am trying to socialize the idea more broadly to gauge support.

OpenAPI is a major use case for JSON Schema (both to validate it, and as a user of JSON Schema within its own format), and I would like to see its use cases fully supported.

[jsdevel]

@handrews I think the features you outlined would be helpful. So long as we get some form of a JSON schema finalized, I think we can at least support more tooling.

To date, has a schema been officially published? I'm still not seeing v3 in the schemas directory.

Also, even having the draft schemas in the repo would be helpful. Iteration is fine.

[webron]

See #1270 and #1348.

[jsdevel]

When will a v3 schema be finalized?

[darrelmiller]

@jsdevel https://github.com/OAI/OpenAPI-Specification/issues/1557#issuecomment-383660855

[ronkorving]

Could anyone share the status of this?

[handrews]

@ronkorving @webron and I discussed the state of things this week and I will be taking a pass at finalizing this in the next couple of weeks.

[jsdevel]

This is really a duplicate of https://github.com/OAI/OpenAPI-Specification/issues/1032. Going to close this out to keep the focus there.