Heads-up on editorial change proposals to JSON-LD syntax document

Hi all,

I spent a bit of time over the week-end thinking about adding a
Conformance section to the spec and more importantly, on related
updates to normative statements that, I believe, are needed to improve
the overall clarity of the spec. I'm not done yet and most probably
won't have time for that by tomorrow. So this is just a heads-up that
I will be proposing editorial changes to the spec and an actual
updated draft as soon as possible.

Main changes that I plan to propose:
1. Add a conformance section as suggested in issue #166

2. Drop all "MAY" statements in sections "Basic concepts" and
"Advanced concepts", switching to regular non normative prose. The use
of "MAY" does not bring much and is not needed from a conformance
point of view.

3. Move all normative statements on JSON-LD documents from "Basic
concepts" and "Advanced concepts" sections to the JSON-LD grammar
section. Most of these statements are already duplicated there but
some are not. For instance, "language associations MUST only be
applied to plain literal strings" is not in the JSON-LD grammar. In
any case, normative statements should not appear twice in the
document.

4. Merge definitions in "General terminology" with the JSON-LD
grammar, because following links from statements in the grammar takes
one to the definition of the underlying term, which is correct
behavior but means one cannot easily follow grammar constraints. I
think definitions and normative constraints on JSON-LD stuff should
rather be all in one place.

The goal of 2. and 3. is to make "Basic concepts" and "Advanced
concepts" sections descriptive sections for JSON-LD authors that only
contain howtos and best authoring practices, and to end up with one
and only one section that defines the normative constraints that
JSON-LD documents are to follow. I believe that matches the
discussions we have had on the subject.

Then, I would like to open a discussion on JSON-LD processors as I'm
unclear how they should be defined. In particular, it seems to me that
all normative statements that currently apply to JSON-LD processors
are direct consequences of the algorithms specified in the JSON-LD API
and that, as such, a JSON-LD processor should rather be defined as a
product that implements the JSON-LD API, and that all normative
statements that are in the JSON-LD syntax spec that target JSON-LD
processors may simply be dropped in the end as they don't bring
anything on top of the algorithms. In any case, the JSON-LD API must
be a normative reference (it is an informative one for the time being)
as it describes how to parse JSON-LD documents.

Obviously, these changes are all up for discussion. I think it's
easier to discuss whether changes are beneficial with an updated draft
so I'll implement the changes and will create dedicated issues along
the way (which also means "don't jump on this thread, this is really
just a heads-up" ;)). My goal is not to introduce any normative change
but to improve the clarity and testability of the spec so that it can
progress along the Recommendation track as smoothly and quickly as
possible.

Thanks,
Francois.

Received on Monday, 29 October 2012 08:57:01 UTC