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

On Tue, Oct 30, 2012 at 1:23 PM, Manu Sporny <msporny@digitalbazaar.com> wrote:
> On 10/29/2012 04:56 AM, François Daoust wrote:
[...]
> +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.

That's indeed what we already have to some extent. We may end up
moving the grammar from an "Appendix" to a "non Appendix" just because
it seems a bit weird to have all normative statements in an appendix,
but I don't think that's a real problem.


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

I share the same concern but will try it out. One alternative would be
to have two links in the grammar, one to the term definition, the
other to the grammar section that covers the term, but that doesn't
sound good either. Yet another alternative would be to have the
grammar section first, but that sounds a bit agressive.

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

I am a regular participant of the RDF working group, actually (just
don't usually participate in weekly calls) so all changes I could
bring are covered by the IP policy, no need to song-and-dance here, we
can keep that for when the spec is published as Rec ;)
I'll prepare a spec on the side for review, using Git.

Francois.



>
> -- 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:59:27 UTC