Re: Review: JSON-LD syntax

On Sat, Jun 23, 2012 at 12:47 PM, Manu Sporny <msporny@digitalbazaar.com> wrote:
> On 06/19/2012 12:51 PM, Pierre-Antoine Champin wrote:
>> here is my review of the JSON-LD syntax document.
>>
>> I'm favorable to the WG adopting this document and publishing it as a
>> FPWD.
>
> Hi Pierre-Antoine,
>
> I have addressed each of your review comments here:
>
> https://github.com/json-ld/json-ld.org/issues/137#issuecomment-6522278
>
> The full-text is below:
>
>> S1 Introduction: the introduction mentions Linked Data (LD) a lot,
>> but never RDF. While I'm guessing this is a way to not scare away
>> the average web developer, it would feel a bit odd not mention RDF at
>> all in the intro for a recommendation of the RDF-WG?
>
> Currently, it is expected that RDF will be mentioned in the Status of
> the Document section. It is still under debate on whether or not we need
> to explain what RDF is up-front. The spec was carefully designed to not
> need to explain RDF up front. Another way to approach this question is:
> What would explaining what RDF is buy us with the intended audience?
> People that know about RDF will know about JSON-LD... but our target is
> not people that know about RDF. It is people that don't know about RDF
> that care about Linked Data, but not necessarily the greater Semantic
> Web. I'm not making the change until there is consensus that this is the
> correct path forward.
>
>> S3.1: from the discussion last week about the controversial term
>> "property", I understood that it was used as a more reader-friendly
>> replacement for "predicate", which suits me; and most mentions of
>> the term seemed consistent with this interpretation. However,
>> defining a "property" as "an edge of the linked data graph" seems
>> wrong to me. A "property/predicate" is the label of an edge, not the
>> edge itself. In RDF (or LD), edges are not identified.
>
> Fixed in commit 88a758c25c575f3e41dc6a42dd440a85347a7601.
>
>> S1.1, definition of 'null' : the second part of the definition ("If
>> @value, @list...") is very technical for an non-normative
>> introduction. This should be moved somewhere else
>
> Fixed in commit 08cd5d631032e1c8ac70ceb979e535b8b68bfc51.
>
>> S1.2 is part of a non-normative section; however, defining a list of
>> keywords reads quite normative to me?
>
> Fixed in commit 24917b1c0af3a488acc0b5214c585e2ebaf2244e.
>
>> S3.1 "A property SHOULD be labeled with an IRI" : how come it is not
>> a MUST? What else could they be?
>
> In JSON, a property can be a plain literal, and it's perfectly valid.
> Making this a MUST needlessly restricts the language in the event that
> somebody finds a use for plain-literals-as-properties in the future. In
> fact, all of JSON's properties are plain literals, so you could say that
> the use case already exists.
>
>> S3.1 "unlabled" → "unlabeled" S3.1.1 "analogousto" → "analogous to"
>> S3.1.1 "each others data" → "each others' data" (missing ')
>
> Fixed in commit a7eb6035f05cc0818cb92c813ab162bf2df5c3ae.
>
>> S3.1.1 "sets the local context to its initial state" : what is that
>> initial state? empty?
>
> Explained where the initial context is specified in commit
> 1e6d4f0ed0a6b90d0613373b9190d26807bbda31.
>
>> S3.1.1 one-pass parsing sounds good, but how can I know in advance
>> that the JSON-LD I get will respect the good practices that allow me
>> to do so? As those good practices are SHOULDs and not MUSTs, I will
>> never know for sure if I can use a one-pass processor or if it will
>> fail. So I would recommend to add a parameter to the content-type
>> (annex C) to indicate whether the JSON-LD guarantees that @context's
>> and @id's are in first positions, so that I can chose the most
>> appropriate parser.
>
> I don't think we should tell folks that there are two types of JSON-LD
> processors. Maybe the terminology needs to be changed because all
> parsing is one-pass... it just can't happen until the @context is known.
> We could re-name this to "efficient memory footprint processing", as
> that's what it really is. It's a bit heavy-handed to say that input MUST
> be ordered in a certain way. I think we'd rather let this be a social
> contract between Web Services and clients of those services. That is, if
> the Web Service wants to use a "efficient memory footprint" processor,
> it can reject any input that doesn't have @context listed as the first key.

I'm confused how this works with JSON. "An object is an unordered set
of name/value pairs", there isn't really a way to say that @context
comes first is there? I mean in all the examples it does, but those
are produced by hand. Nothing in JSON provides for any ordering of
name/value pairs.

>
> I tried to address your comment with commit
> bfda60dac850ea65e1e156b1666aec05355d6702.
>
>> S3.2 "Expressing IRIs are" → "Expressing IRIs is"
>
> This original text is correct... since the subject 'IRIs' is plural the
> correct follow-on is 'are'. I have re-worded it in commit
> b0afa4d3bdd439e3b8cd2b0166e3d2a59a956e0e to make it read a bit more nicely.
>
>> S3.1.2 "a @id" → "an @id" ? S3.2 "is relative some" → "is relative
>> to some"
>
> Fixed in commit b0afa4d3bdd439e3b8cd2b0166e3d2a59a956e0e.
>
>> S3.2 "is interpreted as an IRI (...) because it contains a colon (:)
>>  delimiting a valid IRI scheme" : what is a valid IRI scheme? does it
>>  have to be syntactically valid? or declared to the IETF? Plus, this
>> seem to contradict how terms and IRIs are expanded as described in
>> S4.2
>
> Attempted to clarify this in 374e09e2bd1779d2f2f416ae69e6a6866fde95a8.
> It shouldn't have said valid... as we try to not understand what makes a
> "valid" IRI. Basically, if you use a colon at any place in the in the
> key-position, and a prefix definition for the part before the colon
> doesn't exist in the context... then the value is interpreted as an IRI.
>
>> S3.3 defines "triple" incidentally at the end of the 3rd paragraph
>> 3; this is not appropriate, all the more that the term "triple" is
>> extensively used in the following; I would rather define it in
>> section 3.1, along with subject, property and object.
>
> I'm leaving this one alone for now... I thought about removing the term
> 'triple' entirely. I also thought about also changing it to Quad, as
> that is what JSON-LD generates. Don't know where the group is going to
> go on this - I'm leaning towards Quad. We'll have to make this an issue
> and discuss.
>
>> S4.1 should mention that the @type of a typed value could can be a
>> compact IRI
>
> Clarified in commit 9923ae6c61440ffd89ea0efe2226fa3d96e2907a.
>
>> S4.1 and S4.2 should be swapped, as compact IRIs have precedence
>> over typed values (see above)
>
> Good idea, done in commit 47a79a22cf84b484d0739b7b98233a913e70d455.
>
>> S4.9 "In this case, embedding doesn't work"; I disagree, one could
>> write that example with embedding. A more compelling example should
>> be used, involving for example two persons knowing a same third
>> person.
>
> How would you accomplish that case with embedding? That is, which person
> is embedded within the other person's object?
>
>> S4.10 why not use "blank node" as the default wording here? I don't
>> see it as significantly harder than "unlabeled node"...
>
> The English definition of blank coupled with node doesn't make any
> sense, in general (from Google Dictionary):
>
> blank - adjective
> (of a surface or background) Unrelieved by decorative or other features;
> bare, empty, or plain
> - the blank skyline
> - a blank wall
> Not written or printed on
> - a blank sheet of paper
> (of a tape) With nothing recorded on it
> - blank cassettes
> Showing incomprehension or no reaction
> - we were met by blank looks
> Having temporarily no knowledge or understanding
> - her mind went blank
>
> It doesn't make sense because a blank node doesn't even come close to
> any of the definitions above. This was the topic of a very long
> conversation at the beginning of the JSON-LD work when attempting to
> settle on the Linked Data definition.
>
>> S4.13 and Annex A mention "framing", which will not be part of the
>> recommendations, so this should probably be removed
>
> We are hoping to re-introduce framing just before Last Call (in the next
> six months), so I'd like to keep the text in there for now.
>
> -- manu
>
> --
> Manu Sporny (skype: msporny, twitter: manusporny)
> Founder/CEO - Digital Bazaar, Inc.
> blog: PaySwarm Website for Developers Launched
> http://digitalbazaar.com/2012/02/22/new-payswarm-alpha/
>

Received on Sunday, 24 June 2012 13:01:43 UTC