Conformance section and grammar updates #194
Conversation
tidoust
commented
Nov 7, 2012
tidoust
commented
- Conformance section added as proposed in Add a conformance section #166.
- Normative statements in Terminology, Basic Concepts and Advanced Concepts sections moved to the grammar (except those in "Referencing an external context from a JSON-LD document") or dropped if they were already there.
- Grammar re-written in a more consistent way. Reader may now follow grammar constructs without being taken back to the terminology section.
- Several typos.
The JSON-LD Data Model is now in a proper section, followed by a terminology section with general terminology and keywords. The Conformance section (that refers to the notion of JSON-LD graph defined in the JSON-LD Data Model section) appears next. No further changes in this commit.
Main changes: - Clarified that JSON terms are directly imported from the JSON spec, and not re-defined in JSON-LD. - Moved the definitions of "node definition", "node reference" and "term" to the grammar. They are JSON-LD constructs. - Introduced new grammar constructs when needed, in particular "expanded typed value" and "expanded lanugage-tagged string" - Re-wrote the grammar in a more consistent way to use the same vocabulary throughout. - Fixed grammar when needed (for instance the value in a language map could be a language-tagged string, which seemed a typo). Not done yet: - All normative statements in "Basic Concepts" and "Advanced Concepts" should be removed (provided they appear in the grammar that is!) - There remains a couple of places where the grammar is not perfect (@graph and apparent contradiction in expanded term definition in particular) - Examples in the grammar should be moved to previous sections. - There may be a few places in "Basic Concepts" and "Advanced Concepts" sections that would benefit from linking to the grammar. - Some definitions may benefit from a bit of wordsmithing. For instance, there could be a note around the definition of an IRI that explains that, whenever the grammar says a value must be an IRI, it is taken to mean "a string with the lexical form of an IRI".
Grammar completed as necessary when the normative statements were not captured yet (e.g. the constraint on circular dependencies for terms definitions in a context). Also: IRI definition modified to say that an IRI may either be represented as an absolute IRI or a relative IRI. "terms" and "compact IRIs" were also in the list previously, but they generate IRIs through expansion, and the grammar makes the distinction when it says that a value can be an IRI, a compact IRI or a term. Normative statements on JSON-LD processors still appear in the doc, but should probably be removed. Also note the "Referencing Contexts from JSON Documents" section retains its normative wording. I also updated plural references to terms to include the "s" to ensure the whole world gets turned into a link.
- Created issue json-ld#184 to discuss the definition of a JSON-LD processor. The doc references that issue in the meantime. - Incorporated Markus feedback to clarify when a JSON object with a null value is ignored - Re-introduced statement that discourages the use of empty terms in "Context" section. I left it in the grammar as well because that also seems the right place to mention it but, technically speaking, it could be removed from there since it's not a normative binding.
The grammar contains a "SHOULD NOT" statement on that. I re-introduced a similar statement using "are to be avoided" not to duplicate the normative statement.
|
Could you please completely remove the parts talking about a JSON-LD processor part from the conformance section. I think all of us would then agree to merge this as is. |
Other sections still mention JSON-LD processors, either to describe how JSON-LD documents are processed or to put constraints on JSON-LD processors through normative statements. Descriptive text would need to link to the proper definition of JSON-LD processor in the API doc. Normative statements that apply to JSON-LD processors need to be dropped. All of this is being covered by issue json-ld#184.
|
I didn't pay attention to the fact that removing the definition of JSON-LD processor actually broke the layout of the document because ReSpec now complains that the document contains references to "JSON-LD processor" which is not defined. That's the good thing about ReSpec, it tells you when your document is not consistent ;) I'm not sure how to proceed here. Should I rather:
|
|
Please go ahead and try to remove all statements that involve "JSON-LD processor. I think most cases that should be rather trivial. Thanks for your help on this François. |
There remains one occurrence in a note on low-memory footprint JSON-LD processors, but it is self-explanatory. Also another one in the Microformat appendix but I'm not clear what the sentence actually means.
|
I removed all mentions of "JSON-LD processor" (save one in a self-describing note and one in the Microformat appendix). I note that the resulting doc tends to use passive voice a bit too much, which effectively hide the need to use the term "JSON-LD processor" but still implies it. That's a common mistake:
Said differently, I find that the doc is still not clear as to how exactly a JSON-LD document maps to a JSON-LD graph (well, dataset when we have that notion in the doc). I'll try to find time to propose something concrete but suggest to stop here for this series of edits (unless you have further comments on the edits proposed, that is). |
|
Thanks, I'll put up a proposal in the issue to merge this. |
"Linked Data" is not normatively defined so shouldn't be referenced from the JSON-LD document definition in the Conformance section. I had put the reference only to have some informative description of what a JSON-LD document is, but that's already expressed in the introduction anyway.
Conformance section and grammar updates
