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

On Oct 30, 2012, at 5:23 AM, Manu Sporny <msporny@digitalbazaar.com> wrote:

> 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

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

+1

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

Not to sure about this either.

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

+ 0.5, I think this can work; we don't actually have to remove the "definitions" from the beginning of the document, only have the terms, themselves, be defined in the grammar.

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

+1

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

+1

Gregg

>> 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:30:02 UTC