Add a conformance section

[tidoust]

Reviewing the JSON-LD Syntax spec, I noted a few inconsistencies on the way normative statements are used. My concerns essentially boil down to "there is no conformance section" so that's the main change I suggest in the end. A conformance section is a somewhat boring one, for sure, but it is quite useful to clarify the classes of products that implement the spec. Having a conformance section is also good practice according to QA Framework: Specification Guidelines.

Unless I missed something, there are two classes of products that "implement" the JSON-LD spec: JSON-LD documents and JSON-LD processors. These classes need to be defined somewhere. In particular, there is nothing right now that describes what a JSON-LD processor does with a JSON-LD document. It processes it, sure, but what's the result of that processing?

I suggest to add a Conformance section with the following content:

Conformance

The JSON-LD Syntax specification describes the conformance criteria for JSON-LD documents (relevant to authors and authoring tool implementors) and processors (relevant to Linked Data tools implementors).

A JSON-LD document is a JSON document that expresses Linked Data in JSON. A JSON-LD Document complies with this specification if it follows the normative statements for documents defined in Appendix A. JSON-LD Grammar. For convenience, normative statements for documents are often phrased as statements on the properties of the document.

A JSON-LD processor parses a JSON-LD document and generates the corresponding JSON-LD Graph (mapping terms to IRIs and coercing values). A JSON-LD processor complies with this specification if it follows the normative statements for processors. Statements that are applicable to a JSON-LD Processor are identified in this document by use of the term "JSON-LD processor" in the singular or plural.

The key words must, must not, required, shall, shall not, should, should not, recommended, not recommended, may, and optional in this Recommendation have the meaning defined in [RFC 2119].

Ideally, that section would appear close to the top but after the other terms have been defined. That typically means right after section 3.3, although the conformance section should not be a sub heading of "Basic Concepts".

Related updates and questions:

• There is no normative reference to RFC2119, there should be one
• I explicitly mentioned Appendix A for normative statements that apply to JSON-LD documents. Am I right to assert that this section contains all the normative statements.
• The spec should not contain normative statements that do not apply to any of the classes of products mentioned in the conformance section. In particular, I don't understand the use of normative key words in the JSON-LD data model section because the impact on JSON-LD documents and processors is indirect, at best. I would simply drop the use of normative keywords (they are not needed, the section defines concepts). The should constraints that affect JSON-LD Documents are already addressed by statements in the JSON-LD Grammar, AFAICT.
• Normative statements may benefit from a bit of rewrite to clarify the class of product they apply to. I'd be happy to go through the spec and propose concrete updates (typically in the form of a pull request), but I'd like some feedback on the above first.

[cygri]

+1 to all of the above.

[tidoust]

See annoucement for proposed "bit of rewrite" on the JSON-LD mailing-list http://lists.w3.org/Archives/Public/public-linked-json/2012Nov/0001.html

[gkellogg]

Nice work! A couple of comments:

1. In the third paragraph of Conformance, the text indicates that a processor creates a JSON-LD graph; it's really creating a JSON-LD dataset, which typically just includes a single (default) graph. We need to be sure we're consistent when talking about graphs and/or datasets.

2. Also, in Conformance, you reference normative statements in Basic Concepts and Advanced Concepts, although you indicated in your summary that those sections no longer include normative statements. In fact, there are some MUSTs in those sections (that are for documents, not processors).

7.4) ... an author must specify an IRI to a valid JSON-LD document in an HTTP Link Header
7.4) ... The referenced document must have a top-level node definition
7.4) ... JSON-LD documents served with the application/ld+json media type must have all context information, including references to external contexts, within the body of the document.
7.9) (not really from your edit), a Note contains : ... The use of @container in the body of a JSON-LD document, i.e., outside @context must be ignored by JSON-LD processors. We should remove normative statements from notes.

3. Your comments indicated moving examples out of Appendix A, but there are still some there.

[tidoust]

Thanks Gregg,

Ref. 1) I agree that the definition of a JSON-LD processor needs to be revisited.
I note the term "dataset" is not used anywhere in the JSON-LD syntax document for the time being.
On top of this, I would really mention the JSON-LD API here:

A JSON-LD processor parses and transforms a JSON-LD document according to the algorithms defined in [JSON-LD API] and exposes the results of these transformations using the API defined in that document [JSON-LD API].

If people want to insist on the JSON-LD dataset, this could be tweaked to e.g.:

A JSON-LD processor parses a JSON-LD document to create a JSON-LD dataset according to the expansion algorithm defined in [JSON-LD API]. It exposes the API defined in [JSON-LD API] to transform the JSON-LD dataset following the algorithms defined in that document."

My main point is that there should be a strong tie between the JSON-LD syntax document and the JSON-LD API as the algorithms formalize the principles described in the JSON-LD syntax document. Actually, up until this edit, the JSON-LD API was an "informative" reference. I made it a "normative" reference. That effectively means both documents must progress towards Recommendation at the same pace but I don't see how this could be avoided.

Ref. 2), Yes, I forgot to update the conformance section after all updates.
I noted in my email that the "Referencing Contexts from JSON Documents" was the only one still containing normative statements on JSON-LD documents. I don't think this would fit in the grammar, but we could perhaps move the section to its own high-level section in the document.
Also note I left most normative statements that apply to JSON-LD processors pending discussion on 1)

Ref 3) I mention moving examples out of Appendix A as "not done yet". I believe the group agreed to move them away and I think that's a good idea. I just didn't want to make too many updates at once.

[tidoust]

HTML diff between the original version and the new version:
http://goo.gl/bUZPM
(that loses ReSpec a bit, but is still readable)

[lanthaler]

Great work François!

I started to comment directly on your commits but figured that wouldn't be the best idea to give feedback. You made quite a few changes and I’m OK with most of them. One of the few that I don’t like is for example the fact that you completely removed the sentence discouraging the use of empty terms or term that begin with an @ from the context section and move that into the grammar section. I’m also not sure if lowercasing all RFC2119 keywords is a really a good idea? @gkellogg @msporny thoughts?

What would be the best way to proceed? Should I start merging in the uncontroversial changes.

[gkellogg]

BTW, regarding document diffs. I think the newest versions of ReSpec fix the issue, however, we have to have a previousDiffURI pointing to someplace that will actually come up; probably in the json-ld.org/spec/ED space. Using the keyboard shortcut to bring this up is really useful.

[tidoust]

@lanthaler, I updated my local copy of the spec to incorporate your feedback. I created a proper issue for the definition of a JSON-LD processor, referenced from the Conformance section:
tidoust@0cabdac

It's certainly not a good idea to use RFC2119 keywords without meaning to use RFC2119, but it's also relatively benign for "may" so I sticked to that in the interest of time and of reducing the number of changes I proposed to the spec. Feel free to use other words...

Ref. integration, if you're fine with most of these edits, a pull request followed by a few fixes on your side might be the easiest way forward. I'm also happy to integrate further feedback before sending in the pull request. If you prefer to incorporate the changes one by one yourself, well, that sounds like more work but, hey, that's your call ;) Just let me know.

[lanthaler]

PROPOSAL 1: Remove all statements concerning a JSON-LD processor from @tidoust's conformance section and merge the rest into the JSON-LD syntax spec.

[gkellogg]

I think we probably still need a conformance section, just one that relates to JSON-LD documents.

[msporny]

PROPOSAL 1: -1

PROPOSAL 2: Move all statements concerning a "conforming JSON-LD Processor" to the JSON-LD API document, normatively define a "conforming JSON-LD Document" in the Conformance section.

[lanthaler]

OK, maybe that wasn't clear enough because I still had the proposals I wrote for issue #184 in my mind and was consequently just talking about the syntax spec in this issue. The proposal is effectively the same as what @msporny wrote just split between this and issue #184.

[lanthaler]

Thanks François! Could you please also re-add the statement that terms starting with an @ should not be used in the context section?

Btw., do you know that you can add commits to a PR until it is closed? So please file the pull request so that we can discuss it directly.

[tidoust]

I re-added the statement, but note the wording is a bit awkward as it really needs to say "should not" without saying "should not"...

I actually didn't know one could add commits to a pull request after it was created. Nice. I just filed it.

[cygri]

Throwing this bit from #188 in here, stated a bit clearer:

I have the impression that “JSON-LD Syntax” could be treated as a more Primer/Tutorial-style document, and all the normative “meat” (data model, grammar/well-formedness definitions, algorithms, APIs, conformance) moved to the “Processing” spec. That would free the Primer spec from having to spell out everything in complete detail, and allows a focus on accuracy, clarity, completeness and correctness in the Processing spec. It would also resolve the problem with potential circular normative references, and readers of the Processing spec don't have to jump back and forth between documents to figure out all the details.

[lanthaler]

I re-added the statement, but note the wording is a bit awkward as it really needs to say "should not" without saying "should not"...

Thanks! I don't know how that's handled but isn't "should not" != "SHOULD NOT"?

[lanthaler]

I think François pull request (PR194) is now ready to be merged. You can find the diff here.

PROPOSAL 3: Merge PR194 without further changes (this will not automatically close this issue).

[gkellogg]

+1 looks good.

[cygri]

The proposed Conformance section says:

A JSON-LD document is a JSON document that expresses Linked Data in JSON.

This should be removed, as Linked Data is not normatively defined, and it's not relevant to conformance. It should simply say that a JSON-LD document is a JSON document that complies with the various conformance statements.

Otherwise, no objections to merging the patch.

[tidoust]

Good point. I'll make the change.

[tidoust]

I just dropped that part from the definition, see:
tidoust@32794ee

[lanthaler]

RESOLVED: Add a conformance section to the JSON-LD Syntax specification by merging pull request 194.

[lanthaler]

As agreed on today's telecon I merged PR 194 and will send an e-mail to the mailing list announcing the intent to close this issue in a few minutes.

[lanthaler]

Done: http://lists.w3.org/Archives/Public/public-linked-json/2012Nov/0014.html

Unleass I hear objections, I will close this issue in 24h.