GLD WG feedback on JSON-LD and API

[lanthaler]

_Feedback by Marios Meimaris on behalf of the Government Linked Data (GLD) Working Group_

This is a duplicate of RDF-ISSUE-135. The reason why I also created a GitHub issue is to keep track of related commits and be able to create a checkboxes for each raised point.

---

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

• [x] 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. "

• [x] 1.S1 Change "technique" to "initiative"/"methodology"/"set of guidelines", as "technique" is not a very broad term in its definition.
• [x] 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.
• [x] 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."
• [x] 1.S4 Add to (3) "For Linked Data to achieve its purpose, IRIs must be dereferenceable."
• [x] 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...

• [x] 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..."

• [x] 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."

• [x] 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...."

• [x] 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."

• [x] 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..."

• [x] 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."

• [x] 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)."

• [x] 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_

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

• [x] A.S1 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_

• [x] 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."

• [x] 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."

• [x] 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."

• [x] 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."

• [x] 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"

• [x] 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"

• [x] 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,"

• [x] 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."

• [x] 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."

• [x] 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."

• [x] 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."

• [x] 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, ..."

• [x] 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

[lanthaler]

_Response by John Erickson:_

Minor detail: Marios wrote:

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

I respectfully disagree. Having both of these properties in a Linked Data definition makes the pedagogical point that having URIs is not good enough; they need to be HTTP-resolvable URIs. I think JSON-LD was merely following/echoing TBL's LD definition here.

John S. Erickson, Ph.D. Director, Web Science Operations Tetherless World Constellation (RPI) http://tw.rpi.edu olyerickson@gmail.com Twitter & Skype: olyerickson

[lanthaler]

Suggestion 9.3.S1 has already been fixed in another commit.

[lanthaler]

@gkellogg @msporny @dlongley @niklasl I think I've addressed all uncontroversial concerns. The remaining suggestions in the list above need further discussion IMO. Maybe we can do it directly here in the issue tracker. Here is my opinion on the remaining items:

Syntax:

0.S0: Do nothing. We discussed this often enough already 1.S1: don't really care. Find "technique" most accurate 1.S2: -1, see also John Erickson comment 1.S3: would make sense, but IRI currently links to the Data model 1.S4: see 1.S2 1.S5: maybe just change sth like "expresses links to related data" 2.S1 & 2.S2: the whole section reads a bit weird at the moment. All "must" should be replaced with "is" IMO 3.S2: readers don't know yet that strings can have a "language attribute" at that point 3.S3: I think we should discuss this. "@graph: Used to explicitly label a JSON-LD graph is misleading" 5.S3: Just confuses readers A.S1: Data shouldn't be lost. It will be output by the toRDF algo and can then be further filtered C.S1: -1, we discussed this several times

API:

1.S1: API spec is not the right place to do so 1.S3: this is done to reflect the language of the JSON RFC

[msporny]

I have taken @lanthaler's thoughts on the JSON-LD Syntax document, added mine into the mix, and tried to accurately represent the consensus over the last few weeks. I think all changes that need to be made have been made to the JSON-LD Syntax document:

http://lists.w3.org/Archives/Public/public-rdf-comments/2013Jul/0038.html

@lanthaler, if you could make the rest of the appropriate edits to the JSON-LD API document we can close this issue and do an official response to Marios.

[msporny]

My thoughts on the remaining API issues are aligned with @lanthaler - so +1 to what he said:

1.S1: API spec is not the right place to do so 1.S3: this is done to reflect the language of the JSON RFC

[lanthaler]

@lanthaler, if you could make the rest of the appropriate edits to the JSON-LD API document we can close this issue and do an official response to Marios.

I think there's nothing left, or is there?

[msporny]

We just all need to agree on 1.S1 and 1.S3. I think we do. The boxes aren't checked. I didn't feel that I should do so since you, Dave, and Gregg know more about the API spec than I do at this point. Bottom line: If there is no disagreement on 1.S1 and 1.S3, we're done.

One of us needs to respond to Marios, point-by-point, about the API spec like I did here (for the Syntax spec): http://lists.w3.org/Archives/Public/public-rdf-comments/2013Jul/0038.html

Once we do that, we'll do an official response referencing both e-mails about Syntax and API and we can close the issue (in both issue trackers) if there are no objections from him.

[lanthaler]

I’ve just responded point-by-point to the comments about the API spec:

http://lists.w3.org/Archives/Public/public-rdf-comments/2013Jul/0045.html

@msporny, will you send out the official response?

[gkellogg]

Agree with @msporny's comments on API 1.S1 and 1.S3, but I think we're done anyway.

[lanthaler]

Closing the issue here on GitHub. We have a duplicate in the RDF issue tracker which will be used to send the official response.