Item 1:
I've created a document to track what is to be done, and what is left to do, and notes about what I'm doing, including some of the details in this email. It is in the same Google Drive folder as the specification itself. Email me if you want a link, and cannot find it.
Item 2:
Changing the document so that most of the content is non-normative. I'm changing it so that the normative content is highlighted with normative statements (such as "the value of the ____ property MUST ....") that use RFC 2119 keywords.
Item 3:
One issue relates to statements like this one about the "title" of the document: "This string SHOULD be a definitive canonical name for the document, providing enough descriptive content to differentiate from other similar documents, ideally providing a unique
âhandleâ.
While this statement uses the RFC 2119 keyword "SHOULD", it cannot, in fact, be a normative statement. A normative statement could be something like: elements of "product_ids" array must refer to a product identifiers defined under the "product_tree" element. This constraint cannot be enforced by JSON schema..., and so needs to be called out in the specification as a normative constraint.
However, the statement about the title is still an expectation for the author of contents that go into the document. As such, it is really guidance text for a tool that is prompting for input into material being provided for a document. As I started working on this, it occurred to me to flag and capture these statements as constraints on the author.
Net result: the document will have a section for normative constraints, and a section on author guidance.
Does that work for people?
Eric.