JSON Schema for the OpenAPI 3.0 Specification

[tedepstein]

It looks like we don't yet have a JSON Schema to describe the OpenAPI 3.0 spec. The schemas folder has 1.2 and 2.0 subfolders, but nothing for 3.0 yet.

We'd like to contribute to this. Is anyone working on a JSON Schema for the 3.0 spec yet?

[MikeRalphson]

@timburks and I are working on one over at Google Gnostic, which is generated from the spec itself.

My latest version is here, which incorporates a few manual fixes. Help improving and testing it would be gratefully received.

[tedepstein]

@MikeRalphson , @timburks, great idea to auto-generate a schema from the written spec. I haven't looked at it carefully yet, but at first glance it seems like at least a good starting point.

@earth2marsh, you mentioned in your Google Cloud Next talk that schema development was one of the next items on your agenda. Does the TDC or the Apigee team have an OpenAPI v3 JSON schema in some stage of development...?

[brandur]

I hope this doesn't seem too much like a content-free +1, but I'd also love to see a JSON schema along with the specification.

I don't really trust myself to be able to accurately read the spec in its entirely, so for 2.0 I fell back heavily on using the included schemas to verify that what I'm generating is actually intelligible (and it worked, they caught many problems).

[timburks]

My latest draft is here, semi-automatically generated from the 3.0.md text (v3.0.0-rc2).

[brandur]

@timburks @MikeRalphson That's awesome — thanks for the continued work on it! Just out of curiosity because I don't know the project dynamics very well, is there any chance that your JSON schema can be sent upstream and be officially supported as part of the 3.0 release? I haven't seen or heard much from the project maintainers, but I figure that you may have spoken to them through another channel.

[timburks]

@brandur To keep it regular, I'd like to avoid hand-edits to the schema as much as possible, so I haven't submitted it to the specification repo yet. I expect to do that after we have a final spec.

[timburks]

It seemed good to get this into discussion, so I've posted a PR containing our latest draft.

[mrglavas]

This would be very beneficial for library / tools developers that could use the JSON schema directly for (partial) validation and for generation of an OpenAPI v3.0 model in the language of their choice (not necessarily Java). Could also see this used for generating sample OpenAPI documents from the schema to make it easier to test that libraries and client applications are working correctly.

[sandorfr]

yes this is much needed thanks @timburks for the draft. seems that you have a more recent version here now https://github.com/Mermade/swagger2openapi/blob/master/schemas/openapi-3.0.json ?

[MikeRalphson]

@sandorfr that schema is based on @webron's work in this PR #1270 - my copy you linked to has the object descriptions ported over from @timburks schema.

[MrBlenny]

Looks like I missed the boat here. There are typescript interfaces here: https://github.com/metadevpro/openapi3-ts

These are not fully annotated so they cannot really be considered complete. Going from typescript -> json using something like typescript-json-schema really improves readability.

[mohawk2]

Will this issue manage to be open a full year after the alleged release of OpenAPI 3? :-)

[mohawk2]

To follow up to my comment there: people, without a schema, you do not have a spec, you have an aspiration. Please pick one of the two schemas (probably the generated one from @timburks ) and declare it official. If either the spec or the schema need updating, you can just release minor version-updates.

No apologies for mass-@-ing here: @darrelmiller @earth2marsh @MikeRalphson @webron @whitlockjc - please execute something on this.

Release early, release often! One out of two won't be bad :-)

Cc the Perl module issue: jhthorsen/json-validator#41

[darrelmiller]

@mohawk2 When we do release a final version of JSON Schema, please do not use JSON Schema to guarantee an OpenAPI document is valid. It cannot do that. There are numerous constraints in the written specification that cannot be expressed in JSON Schema.

One of the reasons I initially pushed back on the creation of a JSON Schema for V3 is because I feared that people would try to use it as a document validator. However, I was convinced by other TSC members that there were valid uses of a schema beyond validation.

[handrews]

@mohawk2 as one of the editors of the JSON Schema spec I'll chime in to support @darrelmiller: JSON Schema validation only validates the structure, and if you just need that as a build check or something you can grab one of the proposed schemas and it will likely meet those needs well enough while we decide how to finalize it.

JSON Schema does not provide any way to verify the semantic correctness of an OpenAPI document. And there may be limits on the syntactic validation (e.g. validating format is tricky).

[jberger]

I have several questions then. All in good faith.

Are existing validators bespoke code for openapi v3?
Are there plans for reuinification with json schema or will the split persist?
Are the differences minor enough or contained enough that a validator could mostly use the json schema spec and then code around those differences?

Writing an entirely new validator seems like it would be a major undertaking.

[jwalton]

@jberger I think what @handrews and @darrelmiller are getting at, to give a concrete example, is something like operationId in the operation object. JSON Schema can validate that the operationId field is either not present, or if it is present then it is a string (this is the "structural" part). But JSON Schema cannot validate that operationId for a given operation object is unique compared to all other operation objects in the OpenAPI document (this is the "semantic" part). JSON Schema doesn't "understand" a document, it just checks to see if required fields are there and the fields are the right type.

If you look at swagger-editor, it does structural validation using JSON Schema. But then it also has a bunch of code for semantic validation outside of that.

I'm debating writing a bespoke validator for OpenAPI 3.0,, actually, as a minor typo in swagger-editor will often result in four or five errors (usually the JSON Schema validation will work out something is wrong in a given object, but then will also mark the parent object as not conforming, and the parent of that, and you get a lot of "cruft" errors that aren't really related to your actual problem).

[darrelmiller]

@jberger I chose to write a bespoke validator in .NET for V3. Using JSON Schema and some additional validation code is definitely a viable approach. Maybe one day, JSON Schema would be able to express all the constraints in the OpenAPI spec, but I suspect some are going to be really hard.

Writing a validator is a fair amount of work. But hopefully if it is done well it only needs to be done once per platform. There is no need for every tool to re-implement it. I chose to do a custom one because as @jwalton mentioned, the errors that you get from JSON schema can sometimes be very confusing. I wanted to be able to generate errors that could easily be understood to speed up debugging time.

Having said this, the validation part has actually been easier than dealing with V2 to V3 conversion and the hardest part by far has been the $ref resolution for both internal and external references.

One question I have about using JSON Schema for validation: How would you handle YAML documents? Do you do a YAML to JSON conversion and then use a JSON schema validator? That seems like it would be fairly computationally expensive.

[sandorfr]

@darrelmiller my use of the schema would have nothing to do with validation but generating typescript definition and having more accurate code editor completion/suggestions.

[brandur]

I want to come in with a counterpoint here because based on emoji reactions on comments alone, I have a feeling that I'm part of a not-very-vocal majority. Most of us who are interested in a JSON schema for OpenAPI 3 are aware that it doesn't guarantee perfect validity, but we're interested in a formally maintained JSON schema nonetheless.

As an example, we're generating API descriptions like OpenAPI 3 using a generator that consumes an internal DSL. Given that all this code has one user (us) and is extremely custom, it's easy to make mistakes during implementation, and also easy to introduce regressions as things change. Internalizing a JSON schema and validating against it gets us 99% of the way to a valid spec, and we run it as part of every build in our CI suite.

Writing a special validator in every possible language would get you better errors, but it strikes me as quite impractical — writing new software is time consuming, and maintaining software is even more time consuming. It's also by no means guaranteed — you can easily find dozens (if not hundreds) of Swagger or OpenAPI-related packages on GitHub that have fallen into disrepair since the original good intentions of their authors. These JSON schemas are already most of the way there, and provide a language-agnostic solution since pretty much all mainstream languages can be expected to have a JSON schema validator written (and maintained) for them.

I'd really implore the maintainers here to adopt one of these JSON schemas. It might not be perfect, but it'll be a good enough solution for the vast majority of us, and infinitely better than the situation on the ground today.

One question I have about using JSON Schema for validation: How would you handle YAML documents? Do you do a YAML to JSON conversion and then use a JSON schema validator? That seems like it would be fairly computationally expensive.

Many validators don't just operate directly on JSON and have an option to validate a generic (language-specific) hash structure (e.g. Hash in Ruby or map[string]interface{} in Go). As one data point, we generate an in-memory structure and dump to both JSON and YAML. Even if that wasn't the case though, moving between JSON and YAML is practically speaking, a fast operation.

[mohawk2]

Jeepers kitty-hugging Cripes. Nobody expects the v3 schema to be more of a perfect guarantee than the v2 schema (as said above, consider operationId). Just release a schema and let the dice fall where they may.

[mohawk2]

Otherwise, what is the actual point of OpenAPI? Just declare failure and get on with the rest of your lives.

[sandorfr]

@mohawk2 what did you do ! It is important to remain respectful even when through disagreement in the open source community.

That said, I hate when one developer don't want to implement a wanted and useful feature because some other developer might "use it wrong" according to their own "dogma". But it does not apply here, according to Darrel previous answers.

[mohawk2]

@sandorfr Not trying to create conflict. Instead trying to break a year-long (and counting) logjam.

What are you trying to do? I fear trying to create the appearance of spurious unity?

[handrews]

@mikhailian

• JSON Schema for OAS 3.x: Within a few weeks. @webron and I started this up again this week.
• Next draft of JSON Schema itself, a.k.a. draft-08: by the end of the year

I was not around when OAS 3.0 was finalized and release, so I can't comment on the decision there. I'm mainly the JSON Schema draft editor/author, and I help out here mostly on things related to that (so, supporting newer JSON Schema drafts, looking at what features we can add to JSON Schema to better support OAS, and yes, helping the TSC produce JSON Schemas for the spec).

[mikhailian]

@handrews, thanks for the commitment.

I found your unevaluatedProperties proposal while trying to understand what's the problem with JSON Schema for OAS 3.x.

It looks like OAS 3.x would not have used x- properties if it had to produce a JSON Schema at release time. Now, you are trying to fix OAS 3.x idiosyncrasies by pushing a change to JSON Schema in a tail-wagging-the-dog move.

This is fascinating ;-)

[lashchev]

@handrews It is very excited to see JSON Schema and OAS 3.0 Schema efforts collide in such a very constructive way. I look forward to seeing the results of your very appreciated effort!

[handrews]

@mikhailian

It looks like OAS 3.x would not have used x- properties if it had to produce a JSON Schema at release time. Now, you are trying to fix OAS 3.x idiosyncrasies by pushing a change to JSON Schema in a tail-wagging-the-dog move.

It's hardly a tail-wagging-the-dog situation. OpenAPI is one of the largest users of JSON Schema, which became a de-facto standard at draft-04 after the previous editors abandoned the project. As we work through the drafts on the way towards standardization, we take advantage of our user base to see what works and what does not in real-world scenarios.

In the case of OpenAPI and unevaluatedProperties, this new keyword addresses a longstanding frustration of many JSON Schema users. The difficulties of producing an OAS 3.0 spec without it helped validate that the keyword was needed, and not (as some claimed) a solution looking for a problem. The best feedback is always real-world usage.

Similarly, looking at what differences OAS chose to have between their Schema Object and regular JSON Schema is very helpful in identifying gaps (writeOnly, which we shamelessly stole), confusions, or burdensome implementation requirements. In particular, the code generation use case of OAS has highlighted that the validation vocabulary is not really designed for that use case, and can't really be shoved into it without making a mess. That has greatly informed our planned code generation vocabulary project.

[mohawk2]

The best feedback is always real-world usage.

Amen!

[KES777]

The best feedback is always real-world usage.

I agree, but: no schema - no usage.

[mikhailian]

Let's forget business interests and hierarchical relationships for a moment.

What changes should be done to OAS3.x so that the resulting JSON Schema becomes concise and generates a simple error stack in JSON Schema validators?

Would removing x- properties and replacing them with additionalProperties: true be enough?

In case you wonder what the hell this is about, I'll tell you about my real-world use case. I gave one of the alternative schemas to technically savvy non-programmers, and the feedback was that error stacks were not easy to understand and quite verbose. Once an official JSON Schema design for OAS3.x gets published, users won't be immediately happy.

[handrews]

@mikhailian Changing OAS to placate JSON Schema validators is definitely a tail-wagging-the-dog scenario.

The difficulty of reporting errors from JSON Schema validation is a major concern of the JSON Schema project, and we are addressing it here: json-schema-org/json-schema-spec#643

[handrews]

OK, I am really, truly, for real working on this next week. Stay tuned... and feel free to mock me if I don't get anything done 🙃

[handrews]

First PR on the WIP schema: #1744

[handrews]

I have more PRs that will get put up once 1744 is merged into the schema branch, because they depend on it and I don't have the right permissions to push another base branch upstream for further PRs. I'm trying to keep the PRs reasonably sized so they are more accessible for people who would like to give feedback.

[fwouts]

I'd love to use the JSON Schema definition to validate OpenAPI 3 documents. What's the progress on this? How can I help?

[handrews]

@fwouts I've had a series of minor but distracting health problems since late november (shortly after making that comment) that have prevented me from making much progress. I plan to post what I have as a PR (alongside another one that someone else posted) within the next week and then hopefully someone else can finish it. I'm behind in damn near everything in life right now and just don't have the time (I haven't even been able to get the latest draft of the JSON Schema spec out, which has been stalled for the same reasons for the same amount of time).

[tnpradeep]

Any estimation when this will be released ?

[webron]

Soon. Very soon.

[MikeRalphson]

Move to close?

[webron]

Aye.

[Chaz6]

Does this mean that the schema is available now since the bug is closed?

[ahx]

@Chaz6 Yes! https://github.com/OAI/OpenAPI-Specification/tree/master/schemas/v3.0