Specification format

[justinfagnani]

We probably at least want a JSON Schema file describing the spec, at least to validate tool output and to help generate file readers.

JSON Schema isn't the most human readable format though, do we want another format to develop the spec in and present in the main README?

[bahrus]

I would propose TypeScript

[justinfagnani]

@bahrus in what way?

edit: Sorry, I didn't see the link. We've used that tool too for the Polymer analysis format.

[bahrus]

Yeah, but on second thought, being that existing JSON Schema's are being extended / compared, it might be better to stick with the unwieldly JSON Schema format as the source format.

I was playing around with this editor, which makes it not too bad.

And there are tools to convert JSON Schema to markdown

So I don't really know what the best format to work with would be.

[justinfagnani]

#9 includes both a pretty readable (IMO) TypeScript definition for the format, and a JSON schema file that's included in the repo. This seems like a practical approach.

One downside is having to sync the schema.json file, but if we make the main artifact a published site rather than the repo contents we can not check in the generated schema.json. Will leave that for a separate issue.