regarding action 241 [review JSON-LD 1.0 Processing Algorithms and API]

Hi,

I have scanned through the following document a few times.

http://json-ld.org/spec/latest/json-ld-api/index.html

I feel that it is difficult for me to conduct an effective review of the 
algorithms explained
in this document. It's quite obvious that the authors and editors have 
put in an impressive
amount of work in this document and they have produced quality contents.
One problem is, however, that the algorithm outlines are a bit flat and 
a bit too long in
structure. Take theExpansion algorithm for example, the print out (even 
with a very small
font) spans across three pages.There are many, many lines of bullets in 
this algorithm alone.
Given such a structure,I don't think I have an effective way to validate 
the soundness
or completeness of this algorithm.

It is probably a good idea, in my opinion, to re-organize the algorithms 
in a more modularized
fashion. Each module may take half a page or 3/4 of a page (or less than 
30~40 lines long).
Such a re-organization will likely make reviews easier. More 
importantly, it will be
easier and less error-prone for end-users and vendors to understand and 
implement the algorithms.
A couple of high-level architecture diagrams will also help.

If the authors and editors are willing to re-organize the algorithm 
outlines, I will be happy to review
those algorithms in depth.

I noticed a few issues along the way. Most of them are editorial in nature.

- In Abstract,
   "make them easier to work with"  ==> "make them easy to work with"

- In Section 2,
   "outlines a syntax that may be used to express Linked Data in JSON"

   This sounds a bit too soft. The following might be more precise.
   "defines a syntax to express Linked Data in JSON"

- In 2.1
   "express a property and array to ..."==>
   "express a property and an array to ..."

   "against the examples provided above results in" ==>
   "against the above examples results in" ==>

- Section 3 Conformance states that
   "This specification does not define how JSON-LD Implementations ... 
handle non-conforming input documents.
   This implies that JSON-LD Implementations ... MUST NOT attempt to 
correct ..."

   It is normal that a SPEC does not define behaviors for out-of-scope 
or illegal input.
   I fail to see it implies that a specific implementation must not do 
something extra to handle illegal input.

- In Section 4, I got the feeling that an edge (property) can be labeled 
with a bNode identifier.
   Is this a good idea? If so, for what applications?

- "A compact IRI is has the form" =>
"A compact IRI has the form"

- In Section 6.1,
   "Then we normalize the form the passed local context to an array." =>
   "Then we normalize the form of the passed local context to an array."

- In Section 7.2
   "whose values is the result of ..." =>
   "whose values are the result of ..."

- Section 9.1 describes Flattening Algorithm states "This resulting 
uniform shape
   of the document, may drastically simplify the code required to 
process JSON-LD data..."

   This makes me wonder, out of personal preference, isn't N-TRIPLE the 
ultimate uniform
   (and consistent) shape?

- Section 10.4,
   "... in the form of triples or triples" =>
   "... in the form of triples" =>

- Section 11 talks about API. It may be a good idea to move API before 
all those detailed algorithms.
   I suspect there will be more users who are interested in APIs than in 
those algorithms.

- 11.1,
  "The JSON-LD Processor interface is the high-level ..." =>
  "The JSON-LD Processor interface is a high-level ..." =>

- Section 11 uses crosses and checks for Nullable and Optional settings. 
It is a bit more formal to
   use TRUE/FALSE, YES/NO, or just Y/N.

- 11.2, is it possible to combine multiple callbacks (to save round trips)?

- 11.3,
   "the value of input if it is a IRI"=>
   "the value of input if it is an IRI"

- For JsonLDErrorCode, it may be a good idea to assign numeric error 
codes to be used together with
   descriptive error codes. A developer or a user can then say "hey, I 
got a 500!"

Thanks,

Zhe

Received on Monday, 1 April 2013 04:21:58 UTC