JSON Schema code generation

[chriskapp]

Hi, Iam currently working on a JSON Schema code generation spec which should help authors to write schemas which can be consumed by code generators. The spec currently restricts some JSON schema keywords and includes new ones from the OAI spec like "discriminator". If you are interested in the topic you can take a look at the first draft at:

https://cdn.rawgit.com/apioo/psx-schema/1192d888/doc/jsonschema-code.html

[handrews]

@k42b3 this is fantastic! We have been trying to find a point person for this vocabulary :-)

Are you looking to bring your work into this project / repo / community, or do you prefer to keep it separate and manage feedback in your own repository?

Also, what level of feedback are you looking for right now? For instance I notice some validation wording repeated from the validation spec- is that just a copy/paste starting point or do you want commentary on such things?

Finally one small request: I doubt it makes any real difference, but when you submit your draft if you could use something like
draft-kappestein-json-schema-strict-00
or
draft-kappestein-json-schema-code-00
instead of
draft-kappestein-json-schema-00

I think that would be substantially less confusing. Drafts named just "json-schema" for that section were used for this project before we split it into three specs. I don't want anyone thinking that the strict vocabulary is a new version of core JSON Schema.

But that's a super-minor nitpick, it's great to see this work!

[chriskapp]

Thanks for the great feedback!

Are you looking to bring your work into this project / repo / community, or do you prefer to keep it separate and manage feedback in your own repository?

So currently the spec is located at (https://github.com/apioo/psx-schema/tree/master/doc) which is also the repo of a library which generates code based on a JsonSchema. But if I think about it, it would be great to separate the spec from this repo. Is there a possibility to put the spec into a repo under the JsonSchema organization? This would be great since it is a more neutral place.

Also, what level of feedback are you looking for right now?

This first draft is basically based on my expierince with JsonSchema and OpenAPI. I have copied parts from the JsonSchema core/validation and OpenAPI spec to have a first starting point. Therefore I will try to improve and streamline the woding of the spec. At this stage I would like to gather feedback from other developers who have build code generators to see whether this spec actually simplifies things. Maybe I will create also an issue at the OAI repo to check whether there are people who might be interested in this.

Finally one small request: I doubt it makes any real difference, but when you submit your draft if you could use something like

Ok, this is no problem I will rename the draft to: draft-kappestein-json-schema-code-00

[handrews]

I think it would make sense to put the draft spec in this repo (that was the plan of the UI schema proposal and for the API doc proposal, which is looking at a different Hyper-Schema-based style of documentation than OpenAPI provides- I expect them to co-exist fairly easily).

I'll double-check with the other project members but having a starting point is better than not having one so I suspect putting it here will be fine :-) There's been some discussion as to which vocabularies really need to be RFCs and which just need to be published more informally, but I'm fine with starting in the RFC draft format. We can always make it less formal if there's consensus on that direction. I should figure out what the repo structure should look like here... I'll get back to you on that, too.

Involving the OpenAPI community in this work would be great. I believe @philsturgeon has also expressed interest in narrowing or closing the gap between JSON Schema and OpenAPI, and I think this vocabulary is the ideal mechanism to do that. There may be changes needed to other specs, but a vocabulary that restricts usage of the validation vocabulary (without actually restricting pure validation usage) will solve a lot of problems. Several other OpenAPI folks drop in here from time to time.

[chriskapp]

Ok, great, then I will wait until you have sorted out the basic structure for this repository and then I can create a pull request to add the spec.

[handrews]

Several team members are on vacation at the moment, so let's do this:

• Fork this repository and make a code-gen (or whatever) branch in your fork.
• create a code-generation directory (spelled out like that), and put your XML file there along with a Makefile to generate the .txt and .html output (let's keep the builds per-vocabulary instead of all at the top level like the main spec repo, which is done that way for historical reasons, really).
• Open a pull request back to this repository. We will manage initial feedback there, until we reach some level of acceptance criteria at which point it will be "official"

This will give folks time to get back and sign off on exactly what the acceptance criteria should be.

I'll add you as a collaborator now, and once we accept the PR we can add you as a team member.

Does that sound reasonable?

[chriskapp]

Sounds great, I will go through the spec again this weekend and prepare a pull request like you described. Then we can talk about further details in the PR.

[Relequestual]

@handrews and I had some discussions about if the spec should be in this repo or keep in a separate repo as per the UI gen spec. After reading this, I feel a little silly... I feel that if each spec keeps to a folder, and does the dev work in their own branch (merging to master when they feel it's reached a release marker), then I'm happy for it to be in this repo!

I dug a little into the projects you're involed in... sure looks interesting and useful! I pinged @philsturgeon to see what he makes of it all, and he may find it interesting also (your API framework work). I may peek at some code to see how you do things like rate limiting. (I used to live in PHP land but now live in Perl land).

I'm personally interested to hear a little about what you do for your day job. I've tried to be a sort of coordinator with JSON Schema work, and so it's sometimes helpful for me to understand backgrounds. Feel free to email me rather than discuss in public =]

[philsturgeon]

Hey! I'd be very interested in reading more about this, but it's a bit tough to do in it's current form.

@k42b3 any luck with that PR you mentioned? Maybe wait until @handrews has finished the upcoming megarewrite?

[handrews]

@philsturgeon, @k42b3 submitted PR #4 for this.

[chriskapp]

@philsturgeon if you like you can also take a look at a rendered version of the current draft:
https://cdn.rawgit.com/apioo/psx-schema/1192d888/doc/jsonschema-code.html

[chriskapp]

Some time has now past and we have continued development of this spec in a dedicated repo. If you are interested you can take a look at: https://typeschema.org/

Therefore I will close this issue. If in the future there is a need to create such a vocabulary we can do this in a separated issue.