JSON-LD editorial review (JSON-LD API to follow)

Hello all,

this is an editorial review of the JSON-LD 
(http://www.w3.org/TR/2013/WD-json-ld-20130411/) document. I have 
decided not to include a distinct discussion on my last email's points, 
but to incorporate the most important ones in the editorial comments.

The editorial review of JSON-LD API *is soon to follow*, but feel free 
to briefly go through the following comments and evaluate them.
The structure of this review follows the original doc's sections. 
Suggestions are written in the form "[section id].S[suggestionI id]".

Kind regards,
Marios Meimaris

*0. Abstract*

> " It is primarily intended to be a way to use Linked Data in Web-based 
> programming environments, to build interoperable Web services, and to 
> store Linked Data in JSON-based storage engines. "

0.S1 "...but is not designed to compete with RDF, rather than complement 
the shortcomings of RDF syntaxes when it comes to web-development and 
JSON-based data stores."

*1. Introduction*

> " Linked Data is a technique for creating a network of inter-connected 
> data across different documents and Web sites.  In general, Linked 
> Data has four properties: 1) it uses IRIs to name things; 2) it uses 
> HTTP IRIs for those names; 3) the name IRIs, when dereferenced, 
> provide more information about the thing; and 4) the data expresses 
> links to data on other Web sites.
> These properties allow data published on the Web to work much like Web 
> pages do today.  One can start at one piece of Linked Data, and follow 
> the links to other pieces of data that are hosted on different sites 
> across the Web. "

1.S1 Change
> technique
   to "initiative"/"methodology"/"set of guidelines", because 
"technique" does not give it justice.

1.S2 Merge properties (1) and (2) to one: "...it uses HTTP IRIs to 
name/identify things..."

1.S3 Mention the equivalence of the terms IRI and URI at least once in 
the document,  as people can get confused if they are inclined to expect 
the latter. Provide a link for the LD Glossary.
    Something like:
  "...the terms IRI 
(https://dvcs.w3.org/hg/gld/raw-file/default/glossary/index.html#internationalized-resource-identifier) 
and URI 
(https://dvcs.w3.org/hg/gld/raw-file/default/glossary/index.html#uniform-resource-identifier) 
are usually used interchangeably  among Working Groups and technical 
communities in general."

1.S4 Add to (3) "For Linked Data to achieve its purpose, IRIs must be 
dereferenceable."

1.S5 Data do not necessarily express links to other web sites, as they 
might be in the same domain. Change to "The data contains links to 
external web sites."



*2. Design Goals and Rationale*

2.S1 Change
> JSON-LD satisfies the following design goals:
  to "JSON-LD aims at satisfying the following design goals: ..."

2.S2
> ...must be 100% compatible with JSON...
   sounds like a JSON-LD document isn't, essentially, a JSON document, 
but is something that is compatible.
     Change to something like "A JSON-LD document is always a valid JSON 
document...."

2.S3 Change
> "JSON-LD must make the transition to JSON-LD as simple as possible..."
   to
     "JSON-LD must ensure a smooth and simple transition from existing 
JSON document supporting systems..."  because the phrasing is poor.

2.S4 Change "...using backslash escapes (if necessary)." to "...using 
backslash escapes where appropriate."


*3. Terminology*

3.S1
> "@id
>     Used to uniquely identify things that are being described in the 
> document. This keyword is described in section 5.3 Node Identifiers."

     Perhaps be a little more descriptive?
     e.g. "Used to uniquely identify things that are being described in 
the document, with IRIs, blank node identifiers etc...."

3.S2
> "Used to specify the natural (human) language for a particular value...."

     Change to "Used to specify the language attribute of a particular 
string value."

3.S3
> "@graph
>     Used to explicitly label a JSON-LD graph. This keyword is 
> described in section 6.13 Named Graphs."
     Add something like "...Note that JSON-LD graphs are not the same as 
RDF graphs, as they can be identified by blank node IRIs."
     Don't forget that a lot of people reading the document are RDF 
people and are biased toward identifying similar notions.


*5. Basic Concepts*

5.S1
> "...able to use this IRI (by using a web browser, for instance) to go 
> to the term and get a definition of what the term means..."
     Add "This process is known as IRI dereferencing."

5.S2
> "In JSON-LD documents contexts may also be specified in-line. This has 
> the advantage that documents can be processed even in the absence of a 
> connection to the Web."
     Add "This is ultimately a modelling decision and different cases 
may require different handling."

5.S3
> "Values that are interpreted as IRIs, can also be expressed as 
> relative IRIs. For example, assuming that the following document is 
> located at http://example.com/about/, the relative IRI ../ would 
> expand to http://example.com/ (for more information on where relative 
> IRIs can be used, please refer to appendix B. JSON-LD Grammar)."
     Add "However, JSON-LD documents that are meant to be shared or 
transferred between domains should consider absolute instead of relative 
IRIs."

*6. Advanced Concepts*

6.S1
> "Generally speaking, a node type specifies the type of thing that is 
> being described, like a person, place, event, or web page. A value 
> type specifies the data type of a particular value, such as an 
> integer, a floating point number, or a date."
     Consider adding something that relates this behavior to rdf:type(s) 
and xsd datatypes?
     e.g. "In RDF terms, the node type maps to "rdf:type" and the 
datatype maps to the list of xsd datatypes."

*A. Data Model*

A.S1
> "RDF does not currently allow a blank node to be used as graph name or 
> property, while JSON-LD does. JSON-LD to RDF converters can work 
> around this restriction, when converting JSON-LD to RDF, by converting 
> such blank nodes to IRIs, minting new "Skolem IRIs" as per Replacing 
> Blank Nodes with IRIs of [RDF11-CONCEPTS]. Based on feedback from 
> implementors the Working Group may decide to disallow blank nodes as 
> graph names and properties in JSON-LD. If this change would affect 
> you, be sure to send in a comment."
     Maybe add functionality so that blank node named graphs are removed 
when flattening, instead of minting IRIs? This would
give the modeller some freedom to include graphs that are not meant to 
be published yet as LD.

*C. Relationship to RDF*

C.S1 This section should get more visibility. Put it at the start of the 
document or link to it from the introduction, prompting the RDF-literate 
reader to consult this section before proceding.