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

• 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_

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

• 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_

• 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

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