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

On 10/29/2012 04:56 AM, François Daoust wrote:
> Main changes that I plan to propose: 1. Add a conformance section as
> suggested in issue #166

+1

> 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.

+0.5 - I agree in principle, would need to see the spec text to
understand if we lose anything by doing that. I don't expect that we would.

> 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.

+0 - I think it would be very strange to have almost the entire document
be non-normative and have two normative appendices that define the
entire language. That said, it might be nice to see the spec text in
order to understand what the change would look like.

I don't know of many other W3C specs that do this, do you? This would
also have the down-side that I couldn't just go to the section on "IRIs"
to get a high-level understanding of the normative requirements of IRIs.
That said, there isn't much normative text in there, so maybe this
change would be fine.

> 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.

-0.3 I think it would be strange to not introduce the terminology early
in the document. If I understand your proposed change, the reader would
effectively start reading about terminology that they've never seen before.

> 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.

+1 in principle, need to see the spec text.

> 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.

+1

> 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.

One minor thing we need to discuss: The proper protocol of merging your
changes in with the document. From what I remember, you're not an RDF WG
member? Since that's the case, you're probably going to have to do some
W3C song-and-dance (sending something to RDF Comments, maybe as a patch
request)? We just need to make sure you're covered by the IP policy for
the RDF WG. It shouldn't stop you from doing a pull request via github,
just know that the request may be parked until we figure out the best
way to get the IP Policy to apply to you.

Do you have a preference to how we should handle this? Statement by you
on RDF Comments? Patch request to RDF Comments? Invited Expert application?

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny)
Founder/CEO - Digital Bazaar, Inc.
blog: The Problem with RDF and Nuclear Power
http://manu.sporny.org/2012/nuclear-rdf/

Received on Tuesday, 30 October 2012 12:24:07 UTC