Consider using JSON Schema

[bertspaan]

What about using JSON Schema, instead of a custom schema.md? (JSON Schema should work just fine for YAML files.)

From this JSON Schema, it would be easy to automatically generate a Markdown file with schema documentation, if needed.

I could make a first version of this JSON Schema if you think it'll be useful.

[ruphy]

Hi!

I just tried to convert our schema to JSon Schema. I like the approach, my only main concern is that there seems to be no utility (I tried a few) which create a beautiful documentation like the one in schema.md. I believe this is, for now, a blocker issue which, however, could be overcome. Do you think you can help us with creating such a utility?

Thanks!

[ruphy]

...to follow up on my previous message, I just committed a PR with my tentative work to create a JSon schema. As you might notice, it is far from being a great schema, as I am a novice of the specification.

A few things to note:

• While I appreciate the automation introduced by defining a meta-scheme, we really need beautiful documentation (possibly multilingual) to be generated from the schema.
• We really need the possibility to still generate an example yaml out of the schema, to give to people as an example to customize.

Do you think you can help with those issues?
Thanks!

[bertspaan]

@ruphy I can definitely help improving the first version of your JSON Schema, and also with either creating a tool to produce documentation from this Schema, or finding/using/adapting an existing tool. However, I will not have much time to work on this the coming 2 weeks. Is that soon enough?

[bvhme]

@bertspaan there is now a schema.json in the master, can you perhaps take a look at that?

[bertspaan]

@bvhme Ok! I'll have a look!

[ruphy]

Hi,
I fixed all the issues I could find on my side, and I am very happy with the end result. You can consider the current version of the "develop" branch a very likely release candidate :)

[bertspaan]

I've created a new repository with some tools to validate YAML files using the JSON Schema, and to generate documentation like schema.md from this JSON Schema.

This is just a first version, the generated documentation is not yet usable, but it shows that we could try to use a JSON Schema for both validation, documentation, and also to generate web forms to easily create new publiccode.yml files.

[bertspaan]

@ruphy @bvhme : do you think this is useful? If it is, I will continue working on the JSON Schema + Doc generator. And maybe on something like publiccode init which can generate initial version of a publiccode.yml and an online form that does the same -- both generated from the JSON Schema.

[bvhme]

[Sorry for radio silence, was on Holiday]

@bertspaan That seems pretty interesting, however why wouldn't we do that in this repo? Wouldn't this be a valuable part of the core?

[bertspaan]

I think the final JSON Schema should be in this repo. CLI tools + web form + validator + doc generator maybe in a different one/multiple repos? The repo I created is just for testing.

[bvhme]

That sounds about right :) Although I feel that generating the docs has a natural place here.

What were you thinking about, how do we generate docs well?

[bertspaan]

I think the generated docs should be in this repo, but the generator itself in a different one.

About how to generate docs: I found a few JSON Schema-to-Markdown libraries, but I didn't like any of them, too simple or not well maintained. I think for our purposes, a template (e.g. Handlebars, doT, Liquid) that generates Markdown from the JSON Schema will suffice.