Re: editorial

On Jun 12, 2013, at 11:11, Pat Hayes <phayes@ihmc.us> wrote:

> 
> On Jun 12, 2013, at 5:59 AM, David Wood wrote:
> 
>> Hi Pat,
>> 
>> Thanks for your careful review.  Do you think these concerns could be addressed in a minimal way by a reference to the RDF Primer in the introduction?  
> 
> Yes for me, but I recognize that the extreme RDF-phobia which Manu describes might mean they would not want to force readers to actually read any RDF documents. So a brief intuitive account of the "JSON-DL data model" would also do. It could just be a couple of sentences saying that the data model assumes that data is in the form of a graph of nodes using IRIs and some other stuff. 
> 
>> That would seem to help introduce the terms and, after all, JSON-LD is a product of the RDF WG.  That approach might also serve to quiet the other discussions you mentioned.
> 
> Well, lets just let that die quietly. I think the JSON editors have leaned over backwards to accommodate our RDF bristles, so I dont want to press that point any more.

That's fine with me.  Over to you, Manu, Markus and Greg.  You seem to be on the right track, IMO.

Regards,
Dave
--
http://about.me/david_wood


P.S. I fell over laughing at the very notion of a "JSON-DL" :-)


> Pat
> 
>> 
>> Regards,
>> Dave
>> --
>> http://about.me/david_wood
>> 
>> 
>> On Jun 12, 2013, at 2:25, Pat Hayes <phayes@ihmc.us> wrote:
>> 
>>> 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
>>> 
>>> 
>>> 
>>> 
>>> 
>>> 
>> 
>> 
> 
> ------------------------------------------------------------
> 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
> 
> 
> 
> 
> 
>