RE: GLD WG feedback on JSON-LD and API (RDF-ISSUE-135)

On Thursday, May 30, 2013 4:56 PM, 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 (and to everyone else in the GLD WG), thank you one more time for the
detailed review. 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.
You will receive an official response referencing this and Manu's mail
shortly.

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 for the JSON-LD 1.0 Processing
Algorithms and API below.


> ---------------------------------------------------------------------
> 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")
     
Fixed:
https://github.com/json-ld/json-ld.org/commit/63a38ab1549f7051f0f59f04a9a717
21a23d446c


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

RDF now supports blank nodes as graph names.


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

Fixed:
https://github.com/json-ld/json-ld.org/commit/46b492c74506f3f1d15e7ee11b218b
25f37fbbd0


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

True and false are used instead of JSON boolean in order to align with the
language of RFC4627, i.e., the RFC defining JSON. Therefore, we decided to
keep true and 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")

Fixed:
https://github.com/json-ld/json-ld.org/commit/63cb91a44c2be6fad0d398e7f0ba35
4f35661090


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

Fixed:
https://github.com/json-ld/json-ld.org/commit/a0a521a1651fe386fa3a5745fa9fb7
5573b2fd8d


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

Fixed:
https://github.com/json-ld/json-ld.org/commit/57bc38347294124eb52035b6ab6aa5
a8b2e529ae


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

Fixed:
https://github.com/json-ld/json-ld.org/commit/876a7aa1303e5396e432bb9c3a0419
3d6af19d0b


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

Fixed:
https://github.com/json-ld/json-ld.org/commit/8f982c6f4f0a94714903cc110e2612
858632cdaf


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

This text has been rewritten before we received your review. See
  
  http://json-ld.org/spec/latest/json-ld-api/#generate-blank-node-identifier

for the latest version.

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

Fixed:
https://github.com/json-ld/json-ld.org/commit/806f6fa006d62b27ad6542d535d922
7b98c8e89b


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

Fixed:
https://github.com/json-ld/json-ld.org/commit/4c06cc1fa61f8ea9b391ee6b26403b
a5331f6e51


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


I hope these changes and comments for the cases where we didn't change the
spec address your concerns. Please let us know if you would like us to make
further changes to the document.


Thanks,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 31 July 2013 20:25:04 UTC