Proposed new grammar section (was: Re: Heads-up on editorial change proposals to JSON-LD syntax document)

Hi,

As previously mentioned in this thread, I have been working on updates to
the JSON-LD syntax document to clarify the grammar in particular.

I'm mostly done with the updates on my side, although I haven't had time to
re-read the spec from top to bottom yet, so there may still be some
inconsistencies or errors here and there. The result is visible on Github
for review and discussion:

http://tidoust.github.com/json-ld.org/spec/latest/json-ld-syntax/index.html

(I forked the project. Obviously, the fork is not mean to be kept as a
fork, it's just a way to show changes without ruining the original document)

Main changes:
1. There's a new conformance section (issue #166)
2. The "basic concepts" and "advanced concepts" sections do not have
normative statements that apply to JSON-LD documents anymore (except for
the section about referencing external contexts)
3. I updated the "General Terminology" section to clarify that JSON terms
are defined in the JSON RFC and not re-defined in JSON-LD.
4. I moved definitions of "node definition", "node reference" and "term" to
the grammar so that readers can follow construct definitions.
5. I re-wrote the grammar using a more consistent vocabulary throughout,
using normative keywords and references to other constructs. I introduced
new constructs when needed, in particular "expanded typed value" and
"expanded language-tagged string".

I didn't touch normative statements on JSON-LD processors and think we
should update the definition of a JSON-LD processor in the conformance
section and probably remove the normative statements provided they follow
from implementing the algorithms in the JSON-LD API.

If I introduced normative changes to the grammar, that's unintentional and
probably means I didn't get the initial grammar :). The resulting grammar
is not a pleasant read in the sense that the wording is not great prose,
but it's also much clearer to tell which constructs are possible and which
are no.

I tried to restrict the number of changes I made to the spec but that's
still a fairly substantive set of updates. See Github commits for a full
diff:
 https://github.com/tidoust/json-ld.org/commits/master

Hope you like it.
Francois.

Received on Monday, 5 November 2012 10:41:32 UTC