Review: JSON-LD Syntax

Purpose of review:
1/ Check on moving from the community group to the RDF-WG and REC track
2/ Suitability for FPWD

tl;dr

1/ Yes - it is in a state to move from CG to WG.
2/ Yes - ready to publish as FPWD


Comments:

Major:

1/ Definitions

I agree with the intention of of making it accessible to the typical 
JSON application developer, but a narrative without clearly identified 
definitions means that it is difficult to look into the document to 
check specific details.  It is also easily inconsistent as it is not 
clear when differentiating text is being descriptive or definitional. 
Example below.

I suggest keeping the syntax doc as-is and a separate formal-only 
document (or a separate top level section) for the times when arguing 
over details matters.  Maybe this is a a proper appendix A but I think 
this is more EBNF; it would not be an appendix.

Example: the text in 4.5 and A.2 about @id are different.

[[ 4.5
The value of the @id key must be either a term, a compact IRI, or an 
absolute IRI.
]]

[[ A.2:
"The value of @id must be null, a term, a compact IRI, or an IRI."
]]

which differs several ways.

Example: Is this a legal JSON-LD doc:

{ "@id" : "http://example/thing" }

where do I look?

As the document stands, sorting this out is, for me, a block on LC - too 
much risk of having to make a substantive and having to restart the LC 
cycle.

2/ The split between basic concepts and advanced concepts did not work 
for me.

2a/ Integers as an advanced concept but sets and lists as basic.

2b/ Using HTTP header Link header seems very important.


Other comments

Apologies that the comments are not in document order nor in priority 
order. In checking them I found myself having to jump about the doc to 
try to find definitions (see major comment). As different, and seeming 
identical pieces of text were different in the details, it got messy.

I'm sure I've got some of these comments wrong because of the difficulty 
in being able to find reference material and so running out of time.


3/ Is the test suite also transferring?  It cover both material that is 
to be migrated and material that is not.

compact: 20
expand: 29
frame: 23
from-RDF: 8
to-RDf: 31
normalization: 57

168 tests; 50% (~80) of which are framing and normalization.

4/ Status of bNodes.

Where are BNode labels allowed?  BNodes labels don't get discussed much 
(fine) but for some of the text that lists possible syntax forms at a 
given point, don't include them.

[[ 4.5
The value of the @id key must be either a term, a compact IRI, or an 
absolute IRI.
]]
does not include a bNode label (unless "_:a" is an absolute IRI, which 
it isn't).
and
[[
A subject definition that does not contain an @id property is called an 
unlabeled node.
]]
is confusing as there is another way to be an unlabeled node.

5/ Sec 3.1 Linking Data

We as a group need to review this section

e.g. ""A property should be labeled with an IRI.""

Are there any examples of a Linked Data document that are not RDF or 
which can't be viewed as RDF?

6/ sec 3.1.1

[[
The Web uses IRIs for unambiguous identification. The idea is that these 
terms mean something that may be of use to other developers and that it 
is useful to give them an unambiguous identifier. That is, it is useful 
for terms to expand to IRIs so that developers don't accidentally step 
on each other's vocabulary terms.
]]

"vocabulary term" is confusing - I read that as properties and classes, 
not all things.  Unambiguity of things matters.

7/ "Linked Data document" isn't a defined term

"""An IRI that is a label in a linked data graph should be 
dereferencable to a Linked Data document describing the labeled subject, 
object or property."""

and datatype?

8/ It's big.

The Syntax doc is as big as RDF/XML by page count currently.  I know 
this has been said before but the concept of "JSON API" leads me to 
expect something shorter.

The change in ReSpec means it prints badly.  It grew 6 pages for me just 
on the ReSpec change.  I know that isn't in the CG control but it does 
not help the impression that it's a big spec.  It is very bad in the 
JSON-API doc - the method descriptions are forced into cols of about 10 
chars.

9/ Compact IRIs

[[
Terms are interpreted as compact IRIs if they contain at least one colon 
and the first colon is not followed by two slashes (//, as in 
http://example.com).
]]

Why are http URIs handled diferently to URNs?

    "urn:isbn:978-0-521-87625-4"
    "urn:uuid:7962241c-2a01-11b2-8057-b443860cde7a"
    "og:video:type"
    "_:a"


But BNode labels are IRIs: In "Compact IRIs" it says:

[[
If the prefix is an underscore (_), the IRI remains unchanged.
]]

10/ Sec 3.3: example:

This looks exactly like the situation in the previous section around 
"homepage".
A complete example would be better.

12/
"""
The value of a @graph property must be null, an IRI, or a JSON object.
"""
Was a compact IRI also intended?  I assume so but it does not say that. 
  Another way to put it, when is the spec language about syntax and when 
is it about concepts?

Ditto @context - can a @context take a compact IRI (layering of 
@contexts)?  Maybe it's a odd case but why make it asymmetric - an 
implementation wants a "convert this" function, not "convert1", 
"convert2", etc.

13/ Sec 4.9: Named Graphs

The definition is for "graph" not "named graph".
The first example isn't a named graph.

14/ The longer example in 4.9:

What is the subject of the asOf?
(If it's the graph URI, we have the problem with naming of g-snaps and 
g-boxes).

15/ I found the use of "@type" for datatypes confusing.  I prefer @dtype.

16/ Appendix B: To and From JSON-LD

 From and To what?

s/proof/evidence/


17/ Correction:

s/@subject/@id/

Received on Sunday, 17 June 2012 16:12:02 UTC