JsonSchema definition vocabulary

[chriskapp]

Hi, I use JsonSchema now for some time in a library to generate code based on a json schema. I have recently found this issue on the OAI repo. I think the root of confusion with JsonSchema is that people (like me) try to use the JSONSchema validation spec for a purpose which it is not designed for: To generate code or data structures based on the schema (it is possible but *Of, type array keywords and the design to validate alongside the data make things difficult). I think a solution would be to define a separate vocabulary which is intended to describe data structures and is not designed to validate data. As a first start I have wrote together a simple doc which describes roughly the idea (it uses some parts of the OAI spec):

https://docs.google.com/document/d/1ar7Kb8YYCSBQwX9lQwmZvOE6AAeUZxMXAPjAIa4nvck/edit?usp=sharing

Since the definition vocabulary uses also a subset of the validation keywords it would be possible to write a JsonSchema which is both: validation and definition. This is only a first idea and far from ready but I would like to gather some feedback on this topic.

[Anthropic]

@k42b3 take a look at #252 and #67 a UI Schema would cover what you are referring to wouldn't it?

[chriskapp]

@Anthropic thx for the pointer. Yes UI generation faces similar issues as code generation. With code generation I mean to generate i.e. actual java classes based on a JsonSchema. I think there are some common cases which we need to clarify in general (which are probably also problematic for the UI generation) i.e. handling the *Of keywords or a schema which defines an array containing an array.

But I think UI schema is a different topic then code generation. For code generation I would also like to handle topics like inheritance (and maybe polymorphism) which are probably not needed for the UI.

[Anthropic]

@handrews do you have thoughts on this one, I vaguely remember you discussing inheritance with someone at one point?

@k42b3 yes *Of is a right pain, you can see from my issues I think we should ignore it for object modelling or ui purposes unless a minimum number of conditions are met. I haven't had enough feedback on that yet. Hopefully I can start nagging @handrews now the latest draft is out ;)

[handrews]

I think that it is totally reasonable for a code generating implementation to restrict itself to a subset of JSON Schema. I'm not sure it's necessary to standardize the exact subset, as some languages can easily support more of JSON Schema than others. Likewise, any extension keywords for resolving ambiguities or otherwise making code generation easier would vary per language.

It would be easy to publish a meta-schema for any particular restricted vocabulary (not all vocabularies need to be on the IETF standards track). If one becomes especially popular we might want to consider standardizing it, but I feel that since this would be close to the validation vocab, implementations will be a better way of exploring the right solution than debating a standards document.

As for extends... I'd avoid it, or at least I would avoid making it a required part of anything. It used to be part of the spec but was removed for a variety of reasons. See https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aissue+is%3Aopen+label%3AadditionalProperties for extensive discussions of related concerns.

Fundamentally, schemas are not object-oriented classes. In my experience most re-use is not really trying to express OOP inheritance anyway, although I am sure others have attempted to do that. I recognize the problem in the mismatch but I still have no idea what to do about it (as can be seen in the linked list of issues).

@Anthropic yes let's start trying to move UI schema work along again. I didn't realize how much longer it would take to get this most recent draft out when I asked for a pause, sorry about that :-/

[chriskapp]

@handrews, I came also to the conclusion that a meta schema is probably the best way to go. I have already created a first draft:

https://github.com/apioo/psx-schema/blob/master/JSONSCHEMA.md
https://github.com/apioo/psx-schema/blob/master/jsonschema.json

So a code generator could simply validate a schema before using it to ensure that the schema has a specific form.

[nemesifier]

is there a UI schema repository in this organization yet? How can we help in practice?

[Relequestual]

@nemesisdesign Nope. There loads to do already. We don't have the capacity to expand that right now.

[nemesifier]

I understand. I'd like to give my contribution in that direction when we have some critical mass of people that want to do it.

[handrews]

@nemesisdesign I was just emailing with @Anthropic over the weekend about how to best get the UI schema project moving, will keep you in mind. To be sure to get updates, please follow #67. If there's no other specific action you need for this issue, please close it. Otherwise please comment on what we need to do to resolve things here (other than UI schema, or things covered by that additionalProperties tag link that I put in an earlier comment).

[nemesifier]

@handrews ok I will leave a comment on the specific thread

[handrews]

Since we now have the JSON Schema Vocabularies repository ( https://github.com/json-schema-org/json-schema-vocabularies ) which is tracking both a UI vocabulary and non-UI code generation, I am closing this. If I am missing something and we need to keep this issue open on this repo, please re-open and comment.