JSON Schema alternative

[chriskapp]

Hi, so the OpenAPI spec is used in many cases to generate code and the JsonSchema spec is primarily used for validation and not for code generation. It is not suited for code generation since the schema can only be interpreted alongside the actual data and not on its own, also they have many validation keywords like if / then / else which from my point of view dont make sense for the OpenAPI spec.

I have discovered today https://tools.ietf.org/html/draft-json-schema-language-02 and for some time I have also wrote a "strict" JSON Schema version https://github.com/chriskapp/type-json-schema for code generation. Since Iam not involved in the OpenAPI process I would like to know whether people in general are thinking about switching to a different schema spec, which does not have such problems?

[handrews]

The next draft of JSON Schema (which will be out during August) will have features to enable building a code generation system on it.

Note that while JSON Schema Language looks kind of like it has been adopted by the IETF working group, that is not the case. The person who submitted it did not follow the IETF guidelines and as far as the IETF is concerned, that is not a "draft-<working group>-<subject>-NN" draft where the working group is "json", it is a "draft-<author name>-<subject>-NN" draft where the supposed author name is "json" as noted in the IETF JSON list.

Anyway, the Alternate Schema feature #1913 is what you are looking for, if JSL is ever actually implemented. In which case it would be s simpler codegen system (although limited, as is usually the tradeoff with such things). Although AFAICT even the author does not have a github repo implementing this system.

[handrews]

@chriskapp I just took at look at your "strict" JSON Schema. I'm fairly certain that in the forthcoming draft you could express that in the form of a custom meta-schema on top of the standard vocabularies. Don't worry if that doesn't make sense right now, I just want to note that part of the point of the next draft is to enable exactly the sort of thing you are doing.

[handrews]

@mkistler relevant to your interests 😃

[chriskapp]

@handrews thanks for the reply. I just saw the PR #1977 and I respect the effort but honestly I think merging this would be a bad direction for the OAI spec since we would introduce all kinds of keywords to tool developers which are not relevant, which in the end would produce more tools with different behaviours. I think the only right way would be either that the OpenAPI spec stays with its own version of JSON Schema (and decouples it completely from JSON Schema) or uses a strict defined subset for code-generation, which is maybe possible to build with a meta-schema like you described.

I would guess that some OAI people think the same way, which is probably also the reason why they initially created a custom JSON Schema version for OAI. In theory it sounds great to simply merge these two specs but if you have ever build actual tools you know that this does not make sense, since one spec is for validation and the other for code generation.

[handrews]

if you have ever build actual tools

BWAHAHAHAHAHAHAHAHAHAHAH! LOL assumptions.

(I have built a tool or two in my career for JSON Schema and OpenAPI and various combinations)

[chriskapp]

ok, sorry this was badly phrased by me, but I meant more if "someone" builds tools not related specifically to you.

[mkistler]

@handrews Thanks for bringing this to my attention.

@chriskapp I am sympathetic to your concerns as my main focus is SDK generation tooling from OpenAPI docs. I have expressed some of these concerns in the OpenAPI Slack channels and they generated lots of discussion.

I think we've reached the point were we need a good mechanism to describe "a subset" of the OpenAPI spec that a tool will handle, and acknowledge that many tools will choose to do so.

Within the scope of schema definitions, I think this is what @handrews is aiming at with the "vocabularies" feature of the latest JSON Schema draft.

I am optimistic that some small set of common subsets will emerge that can help us avoid descending into chaos, though it will likely take some effort within the community to work out compromises to achieve this.

[handrews]

@chriskapp JSON Schema 2019-09 has now been published. You will likely find the following to be of particular interest:

• JSON Schema Core, Appendix D.2: Example vocabulary including defining new keywords and restricting the use of existing keywords (in this case, the new unevaluatedProperties and unevaluatedItems keywords). This shows how, if OAS 3.1's Schema Object supports the $schema keyword (which I think it should, for meta-schemas that don't contradict Schema Object semantics), you could restrict the set of JSON Schema keywords that your tooling will accept. This is the "describe a subset" mechanism to which @mkistler is referring.
• JSON Schema Core, Appendix E: Hypothetical example of using keywords defined in a (hypothetical) new vocabulary for code generation in order to disambiguate various situations.

[chriskapp]

@handrews thanks for the pointer, I will check it out to see how to build a fitting meta schema. @mkistler yes I think also this would be the best way to proceed, this could be also for version 3.1 or even 4 but using a strict schema for its use case would greatly increase the usability and tooling support.

[chriskapp]

@handrews I have just started to continue my work on a new strict JSON Schema called TypeSchema which is specifically designed for the code generation use case. If you like you can take a look at it here: https://chriskapp.github.io/typeschema/

I will close this issue and come up with a more formal proposal either directly to the OpenAPI community or to the JSON Schema community as vocabulary (if this is possible) once the work is more complete. If others from the OpenAPI community are interested @mkistler @darrelmiller @tedepstein @philsturgeon please let me know.

[handrews]

Hi @chriskapp - it's great to hear this!

Our current plan is to collaborate with the OAS TSC and hopefully also tooling folks like @mkistler on an annotation-based approach to code generation. This would use additional keywords to disambiguate code generation challenges.

A restriction in the form of a custom meta-schema may also be appropriate (either as an integral part or as a separate piece that can be used either with or without the annotation vocabulary). I'd be very interested in seeing if we can align our approaches here.

I took a very quick glance at the page you link to, and the generic/template thing is interesting. It has been requested from JSON Schema but largely deemed out of scope (not entirely- the issue is still open I'm pretty sure). I would recommend against using a $ prefix as that is intended for use by the JSON Schema Core vocabulary alone. We might formally reserve that namespace in the future, although we decided to stick with a RECOMMENDED rather than a MUST for this draft.

[mkistler]

@chriskapp I am so happy to see this and will be very happy to help / support however I can.