Re: Review: JSON-LD syntax

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 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 Saturday, 23 June 2012 19:47:50 UTC