Document entry format

[tobie]

trafficstars

The entry format is documented using JSON schema.

I would be great to generate doc from the schema. Unfortunately, either the tools to do so are terrible or there small issues with Specref's schemas that make it difficult to use.

• [ ] check that Specref's schemas are JSON-schema-compliant.
• [ ] fix them if not.
• [ ] check that the test suites still run properly after fixing the schemas.
• [ ] find a cool doc tool.
• [ ] generate docs and include them either in the readme or on specref.org.
• [ ] document the code generating process or add a script to do so in the scripts folder.

[tobie]

/cc @tabatkins

[tabatkins]

I've boiled down your schema into an abbreviated form for my own purposes, in case it helps :+1:

<alias>: {
    *aliasOf: <id>,
    *id: <id>
}

<legacyRef>: <string>

<ref>: {
    id: <id>,
    authors: [<string>],
    etAl: <bool>,
    href: <url>,
    *title: <string>,
    date: <date>,
    deliveredBy: [<wg>],
    status: <string>,
    publisher: <string>,
    obsoletes: [<id>],
    obsoletedBy: [<id>],
    versionOf: <id>,
    versions: [<id>],
    edDraft: <url>
}

<date>: /^([1-3]?\d\s)?((?:January|February|March|April|May|June|July|August|September|October|November|December)\s)?\d+$/

<wg>: {*url:<url>, *shortname:<string>}

(This is now stored alongside my SpecRef-parsing function.)

[tobie]

That's neat! Might try to reuse it. Note it's the output format, not the input one.

[tabatkins]

Yeah, that's the format I care about, both as a consumer of SpecRef data, and a producer of SpecRef PRs. You only care about the input format for the purpose of consuming the W3C's data, right?

[tobie]

Well, not really. You need to understand the input format for contributions beyond the simplest of cases.