GLD WG feedback on JSON-LD and API

Hello all,

On behalf of the Government Linked Data (GLD) Working Group, I am 
sending out two brief reviews for the JSON-LD and the JSON-LD Processing 
Algorithms and API specifications. We are sorry for the late feedback.

Overall, the documents are well written, concise and well-structured. 
Included in this email are some minor editorial fixes and 
suggestions**that should benefit readability.

Congratulations to the people that worked on these!
*
*Note: The structure of these reviews follows the original docs' 
sections. Suggestions are written in the form "[section 
number].S[suggestion number]".*

---------------------------------------------------------------------------------------------

*JSON-LD 1.0 (http://www.w3.org/TR/2013/WD-json-ld-20130411/*)
*
*
*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 One of the first questions that will pop into the heads of 
RDF-inclined people will be how JSON-LD is related to RDF and when 
JSON-LD is a better choice for deploying LD.
Consider adding "...but is not designed to compete with RDF, rather than 
complement the shortcomings of RDF syntaxes when it comes to web-based 
programming, 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", as "technique" is not a very broad term in its definition.

1.S2 Merge properties (1) and (2) to one: "...it uses HTTP IRIs to 
name/identify things..." as they are esentially talking about the same 
thing.

1.S3 Mention the relationship between the terms IRI and URI at least 
once in the document,  as inexperienced people can get confused, 
especially if they are inclined to expect the use of "URI" instead of 
"IRI". Provide a link to 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 does not only express links to other web sites, as they might 
be in the same domain. Consider changing to
"4) the data expresses links to data on other Web sites. " to "Part of 
the data contains links to external web sites."


*2. Design Goals and Rationale*

> ...must be 100% compatible with JSON...
2.S1   Might be a bit misleading as it sounds like a JSON-LD document 
isn't, essentially, a JSON document, but is something that is 
compatible. Perhaps change to something like "A JSON-LD document is 
always a valid JSON document...."

> "JSON-LD must make the transition to JSON-LD as simple as possible..."

2.S2 Consider the following rephrase: "JSON-LD must ensure a smooth and 
simple transition from existing JSON document supporting systems..."  
for better phrasing.


*3. Terminology*

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

3.S1  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...."

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

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

> "@graph
>     Used to explicitly label a JSON-LD graph. This keyword is 
> described in section 6.13 Named Graphs."

3.S3     Perhaps briefly point out the difference between JSON-LD and 
RDF as far as Named Graphs are concerned? Don't forget that a lot of 
people reading the document are RDF people and are biased toward 
identifying similar notions.
    Add something like "...Note that JSON-LD graphs are not the same as 
RDF graphs, as they can be identified by blank node IRIs."


*5. Basic Concepts*

> "...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..."

5.S1     Add "This process is known as IRI dereferencing."

> "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."

5.S2     Add "This is ultimately a modelling decision and different 
cases may require different handling."

> "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)."

5.S3 Consider adding: "However, JSON-LD documents that are meant to be 
shared or transferred between domains should consider absolute instead 
of relative IRIs."


*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."
     Has the WG considered adding 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 proceeding.
*
End of JSON-LD 1.0 Review

--------------------------------------------------------------

JSON-LD 1.0 Processing Algorithms and API* 
(http://www.w3.org/TR/2013/WD-json-ld-api-20130411/)

Overall, the document is concise, well structured and thorough. I've 
taken the liberty to point out some really minor grammar and typo fixes.

*0. Abstract*

> " Restructuring data according the defined transformations often 
> dramatically simplifies its usage."

0.S1  Minor grammar fix: "Restructuring data according *to* the defined 
transformations..." (add "to")

*4. General Terminology*

> "named graph
> A named graph is a pair consisting of an IRI or blank node (the graph 
> name) and a JSON-LD graph."

1.S1 Perhaps consider pointing out the difference between blank node 
identifiers for JSON-LD named graphs and RDF named graphs here?

> "relative IRI
> A relative IRI is an IRI that is relative some other absolute IRI; in 
> the case of JSON-LD this is the base location of the document."

1.S2 Minor grammar fix: "A relative IRI is an IRI that is relative *to* 
some other absolute IRI;..." (add "to")

> "JSON-LD value
> A JSON-LD value is a string, a number, true or false, a typed value, 
> or a language-tagged string."

1.S3 Consider replacing "...true or false..." with "...a JSON boolean 
value (i.e. true or false)..."

*8.3 IRI Compaction*

> "If no term was found that could be used to compact the IRI, an 
> attempt is made compact the IRI using the active context's vocabulary 
> mapping, if there is one"

8.3.S1 Minor grammar fix: "...an attemt is made *to* compact the IRI..." 
(add "to")

> "This algorithm takes three required inputs and three optional inputs. 
> The required inputs an active context, an inverse context, and the iri 
> to be compacted"

8.3.S2 Minor grammar fix: "...The required inputs *are* an active 
context..." (add "are")

*8.5 Value Compaction*

> "For the former case, if the type mapping of active property is set to 
> @id or @vocab and value consists of only of an @id member and, if if 
> the container mapping of active property is set to @index,"

8.5.S1 Minor grammar fix: "...and value consists only of an @id member 
and, if the container....." (remove excess "of" and remove excess "if")

*9.2 Node Map Generation*

> " If a property's value is a node object, it is replace by a node 
> object consisting of only an @id member."

9.2.S1 Minor typo fix: "...it is replaced by a node..." (change 
"replace" to "replaced")

> "This relabeling of blank node identifiers is also be done for 
> properties and values of @type."

9.2.S2 Minor grammar fix: "...is also done for properties..." (remove "be")


*9.3 Generate Blank Node Identifier*

> "This algorithm is used to determine if two generate new blank node 
> identifiers or to relabel an existing blank node identifier to avoid 
> collision by the introduction of new ones."

9.3.S1 Minor typo fix: "...determine whether to generate new blank node 
identifiers or..." (replace "if" with "whether" and "two" with "to")


*10.1 Convert to RDF Algorithm*

> "Expand element according the Expansion algorithm.
> Generate a node map according the Node Map Generation algorithm."

10.1.S1 "Minor grammar fix: "Expand element according to the Expansion 
algorithm." (add "to")
                             "Generate a node map according to the Node 
Map Generation algorithm." (add "to")


*10.6 Data Round Tripping*

> "The numeric or boolean values itself are converted to canonical 
> lexical form, ..."

10.6.S1 Minor grammar fix: "The numeric or boolean values themselves are 
converted to..." (replace "itself" with "themselves")


*END OF JSON-LD 1.0 Processing Algorithms and API review*
*----------------------------------------------------------------------------------*


Kind regards,
Marios Meimaris