editorial

Recent, um, discussions, have forced me to read the JSON-LD ED with a "naive eye", pretending that I know squat about RDF, to see if it makes sense. And that exercise has revealed some oddities. I think most of these can be alleviated by giving a quick outline of the idea of the data model earlier in the document, ideally right at the beginning. 

The most peculiar thing is the way that "graph" terminology seems to creep into the text without explanation.

 In section 3.2 we get "@value: Used to specify the data that is associated with a particular property in the graph." with no warning or preamble. What graph? Why are we talking about graphs? And what is a property? 

Graphs are then not mentioned anywhere in the text until 5.3, when suddenly, again with no introduction or explanation, we are told: "To be able to externally reference nodes in a graph, it is important that nodes have an identifier". Well, OK, but so what? Why are we talking about identifying nodes in a graph at all? 

3.2 also mentions "blank node identifiers", a puzzling concept (what is a node, and why would it be blank?) which does not get explained until 6.14, by which time one's brain has been fried.

( Aside.  What is the distinction between a node and a 'node object'? Example 11 is very puzzling. Surey the IRI http://me.markus-lanthaler.com/ identifies Markus, no? So is Markus a node object? But then how can Markus be "contained" in a piece of JSON text? )

( 6.4 carefully distinguishes value types from node types, but then 6.5 immediately starts talking about data types. Are there three kinds of type? Why did 6.4 not mention data types? )

The examples in 6.4 and 6.5 seem to imply that JSON-LD "data" has the form of a kind of table, maybe an RDB table? Is this correct? If so, what have these tables got to do with graphs? If not, what is the intended pedagogic purpose of these table-like formats for the examples? 

What do the headings "Subject" and "Property" mean? They are not mentioned anywhere in the text previous to this point. 

6.6 refers to "property values" without explanation. Is that the same "property" as that used in the table headers?

6.11 says "Since graphs do not describe ordering for links between nodes, arrays in JSON-LD do not provide an ordering of the contained elements by default."  This is quite mysterious. What have graphs got to do with JSON-LD arrays? There seem to be a whole lot of assumptions behind this remark that have not been stated in the document at this point. 

6.12 says, finally: "JSON-LD serializes directed graphs."  At last, we are told this rather central fact. Surely it should come earlier? How exactly is this serialization done? (We aren't actually told. A simple example, with an actual graph diagram, would be nice.)

"a person and its children"//"a person and their children"

6.13 refers to " a JSON-LD graph itself,", which is a new concept, not previously mentioned or defined. 

6.14 talks about blank nodes, finally. 

All of this is based upon the RDF graph model and is indeed incomprehensible without having something like that model in mind. It even uses much (but, confusingly, not all) of the same terminology. But not only is no reference made to that model, but the document does not even attempt to replace it with a JSON-specific model until after all the introductory material is finished. I realize that there are many internal links from the non-normative material to the later normative sections, but it still seems that at least a summary of the idea of a graph-based data model should be outlined early in the document to give some context for all the graph/node/property terminology which at present has no explanation or motivation, but gradually becomes a dominant theme as the text progresses. 

Pat

------------------------------------------------------------
IHMC                                     (850)434 8903 or (650)494 3973   
40 South Alcaniz St.           (850)202 4416   office
Pensacola                            (850)202 4440   fax
FL 32502                              (850)291 0667   mobile
phayesAT-SIGNihmc.us       http://www.ihmc.us/users/phayes

Received on Wednesday, 12 June 2013 06:26:43 UTC