Re: GLD WG feedback on JSON-LD and API

On 05/30/2013 10:55 AM, Marios Meimaris wrote:
> 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.

Marios, thank you for the very detailed review of both the JSON-LD
Syntax and API specifications. This is not an official response to your
issue, but rather a set of comments from the Editors of the
specification. We have tried to apply as many of your suggestions as
possible while striking a balance with other reviewers, people in the
RDF WG, and people in the JSON-LD community. The editors have been
tracking each one of your suggestions here:

https://github.com/json-ld/json-ld.org/issues/254

We've been tracking the official comment from the GLD WG here:

https://www.w3.org/2011/rdf-wg/track/issues/135

Responses to each one of your suggestions below.

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

The relationship between RDF and JSON-LD has been a topic of debate
throughout JSON-LDs development. There are many people that have strong
opinions about it and we've tried to reach consensus between all of the
communities involved. In fact, we have just spent the last two months
almost solely discussing this topic and trying to get agreement between
various communities on how RDF is aligned with JSON-LD. We have taken
your input, along with many others, and re-drafted key portions of the
document that speak to RDF and JSON-LDs relationship. While we didn't
use the text you proposed, we did integrate the point you were making
and think that we have achieved something that has consensus:

http://json-ld.org/spec/latest/json-ld/#introduction
http://json-ld.org/spec/latest/json-ld/#data-model
http://json-ld.org/spec/latest/json-ld/#relationship-to-rdf

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

The editor's prefer the term technique because it's more accurate than
'initiative'. Methodology is also less accessible than 'technique' for
most English speakers.

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

The section has been rewritten because it was too controversial for
some. If the section were not rewritten, there was objection to merging
1 and 2 because a number of group participants felt that they were not
essentially 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 and URI are usually used interchangeably  among Working 
> Groups and technical communities in general."

Fixed:

https://github.com/json-ld/json-ld.org/commit/ab790e828ae00826540c9475fbe481decf184a77

http://json-ld.org/spec/latest/json-ld/#how-to-read-this-document

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

Spelling out what Linked Data is turned out to be too controversial in
the RDF WG. So, we had to re-write the entire section. The Editor's
would have liked to make the changes you proposed, but there was a lack
of consensus to spell out what Linked Data was in the JSON-LD specification.

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

Same as above, see the re-write here:

http://sites.local/json-ld.org/spec/latest/json-ld/#introduction

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

Done:

https://github.com/json-ld/json-ld.org/commit/14715186397f155a44ef8086d9cf626a9dc6f487

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

Done:

https://github.com/json-ld/json-ld.org/commit/9d056ce0528e94055de8842ac35d5af0f96401a3

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

Done:

https://github.com/json-ld/json-ld.org/commit/62697efcb97075218ab1791c06f72bc5941689cc

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

There was an objection to this text by one of the editors, I've
attempted to find a middle ground:

https://github.com/json-ld/json-ld.org/commit/62d67963d1cb661e8e3354c89a17dc07e416cba8

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

The perceived gap between an RDF graph and a JSON-LD graph has been
closed over the last two months. They are the same thing now (a JSON-LD
document is an generalized RDF Dataset). Blank nodes for graph names
were approved for usage in RDF 1.1 a few weeks ago.

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

Done:

https://github.com/json-ld/json-ld.org/commit/468d23a5048c305844594cc87e9b135a660a232d

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

Done:

https://github.com/json-ld/json-ld.org/commit/02b27f2410d84200c94b30a0904f933b4f8d3add

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

The editors agreed that stating that in an introductory section to IRIs
would confuse the reader.

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

The RDF WG has now allowed the use of blank node named graphs. Problem
solved. :)

We have re-written a good chunk of the section to suggest what to do in
the case of blank node properties:

http://json-ld.org/spec/latest/json-ld/#relationship-to-rdf

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

Done, it's not linked to from the introduction:

http://json-ld.org/spec/latest/json-ld/#introduction

> End of JSON-LD 1.0 Review

Thank you for your review Marios. I hope that the changes that we've
made to the JSON-LD Syntax document, based on your feedback, are
acceptable to you. Please let us know if you would like us to make
further changes to the document.

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
Founder/CEO - Digital Bazaar, Inc.
blog: Meritora - Web payments commercial launch
http://blog.meritora.com/launch/

Received on Sunday, 21 July 2013 00:12:43 UTC