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.