Review: JSON-LD syntax

Hi,

here is my review of the JSON-LD syntax document.

I'm favorable to the WG adopting this document and publishing it as a FPWD.

It must be noted, though, that some of my remarks below (grouped at the top
of the list) might cause disagreement between the community group and the
working group, so they need to be discussed, IMHO.

Major remarks (that may cause CG/WG disagreement):

* S1 Introduction: the introduction mentions Linked Data (LD) a lot, but
never RDF. While I'm guessing this is a way to not scare away the average
web developer, it would feel a bit odd not mention RDF at all in the intro
for a recommendation of the RDF-WG?

* S3.1: from the discussion last week about the controversial term
"property", I understood that it was used as a more reader-friendly
replacement for "predicate", which suits me; and most mentions of the term
seemed consistent with this interpretation. However, defining a "property"
as "an edge of the linked data graph" seems wrong to me. A
"property/predicate" is the *label* of an edge, not the edge itself. In RDF
(or LD), edges are not identified.


Minor remarks:

* S1.1, definition of 'null' : the second part of the definition ("If
@value, @list...") is very technical for an non-normative introduction.
This should be moved somewhere else

* S1.2 is part of a non-normative section; however, defining a list of
keywords reads quite normative to me?

* S3.1 "A property SHOULD be labeled with an IRI" : how come it is not a
MUST? What else could they be?

* S3.1 "unlabled" → "unlabeled"

* S3.1.1 "analogousto" → "analogous to"

* S3.1.1 "each others data" → "each others' data" (missing ')

* S3.1.1 "sets the local context to its initial state" : what is that
initial state? empty?

* S3.1.1 one-pass parsing sounds good, but how can I know in advance that
the JSON-LD I get will respect the good practices that allow me to do so?
As those good practices are SHOULDs and not MUSTs, I will never know for
sure if I can use a one-pass processor or if it will fail. So I would
recommend to add a parameter to the content-type (annex C) to indicate
whether the JSON-LD guarantees that @context's and @id's are in first
positions, so that I can chose the most appropriate parser.

* S3.1.2 "a @id" → "an @id" ?

* S3.2 "Expressing IRIs are" → "Expressing IRIs is"

* S3.2 "is relative some" → "is relative to some"

* S3.2 "is interpreted as an IRI (...) because it contains a colon (:)
delimiting a valid IRI scheme" : what is a valid IRI scheme? does it have
to be syntactically valid? or declared to the IETF? Plus, this seem to
contradict how terms and IRIs are expanded as described in S4.2

* S3.3 defines "triple" incidentally at the end of the 3rd paragraph 3;
this is not appropriate, all the more that the term "triple" is extensively
used in the following; I would rather define it in section 3.1, along with
subject, property and object.

* S4.1 should mention that the @type of a typed value could can be a
compact IRI

* S4.1 and S4.2 should be swapped, as compact IRIs have precedence over
typed values (see above)

* S4.9 "In this case, embedding doesn't work"; I disagree, one could write
that example with embedding. A more compelling example should be used,
involving for example two persons knowing a same third person.

* S4.10 why not use "blank node" as the default wording here? I don't see
it as significantly harder than "unlabeled node"...

* S4.13 and Annex A mention "framing", which will not be part of the
recommendations, so this should probably be removed


  pa