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

Hi Francois,

+1 – these all sound like good improvements to me.

Best regards,
Niklas


On Mon, Oct 29, 2012 at 9:56 AM, François Daoust <francois@joshfire.com> wrote:
> 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 Tuesday, 30 October 2012 09:38:49 UTC