RE: review of json-ld-syntax

Some more updates based on Sandro's feedback and the discussions in today's
JSON-LD telecon.


>  > JSON keys that do not expand to an absolute IRI are ignored, or
> removed in some cases, by the [JSON-LD-API]. However, JSON keys that do
> not include a mapping in the context are still considered valid
> expressions in JSON-LD documents-the keys just don't expand to
> unambiguous identifiers.
> 
> This is kind of weird. It doesn't tell me what I'm supposed to do; it
> just confuses me.
> 
> I guess it means they're like comments, and to be ignored?

This was changed to [1]

"JSON keys that do not expand to an IRI, such as status in the example
above, are not Linked Data and thus ignored when processed."


>  > 6.1 Compact IRIs
> 
>  > Prefixes are expanded when the form of the value is a compact IRI
> represented as a prefix:suffix combination, and the prefix matches a
> term defined within the active context
> 
>  > Terms are interpreted as compact IRIs if they contain at least one
> colon and the first colon is not followed by two slashes (//, as in
> http://example.com)
> 
> These sentences contradict each other. Do slashes prevent recognizing
> things as compact IRIs or not? I'd suggest not -- that's just extra
> code that wont be helpful, IMHO. (TEST CASE?)

I've clarified the section and added two test cases in [2].

Values of the form prefix://suffix are not considered as compact IRIs to
prevent developers from accidentally overwriting all their http URLs for
example. RDFa had to introduce a similar safety-mechanism.


>  > It is a best practice to put the context definition at the top of
> the
> JSON-LD document.
> 
> MEDIUM
> 
> I don't agree. You're telling me I'm going against best practice to
> build and object in memory and let my JSON serializer turn it into
> JSON.

I changed it to the following suggestion [3]:

"When possible, the context definition should be put at the top of a JSON-LD
document. This makes the document easier to read and might make streaming
parsers more efficient. Documents that do not have the context at the top
are still conformant JSON-LD."


>  > To avoid forward-compatibility issues, a term should not start with
> an @ character
> 
> MEDIUM
> 
> Why only SHOULD NOT? Why not MUST NOT? The damage if they do is
> considerable.
> 
> Also, you kind of need to say what processors MUST do if they see a
> keyword term they don't know -- ie one from the future. The options
> are: ignore (if you can figure out what/how much to ignore); or halt;
> or issue a warning to the user.

I've clarified that note [4]. Just as any other term that isn't mapped to an
IRI, terms starting with an "@" that are not keywords are being ignored.


>  > EXAMPLE 5
> 
> after this example I was expecting the next example to use a Link
> header
> (what turns out to be EXAMPLE 29). Maybe mention it here?

The majority of the group felt that this is too early in the document. I've
added the following statement instead [5]:

"JSON documents can be transformed to JSON-LD without having to be modified
by referencing a context via an HTTP Link Header as described in section 6.8
Interpreting JSON as JSON-LD. It is also possible to apply a custom context
using the JSON-LD API [JSON-LD-API]."


>  > EXAMPLE 6 -- In the example above, the key http://schema.org/name is
> interpreted as an absolute IRI because it contains a colon (:) and the
> "http" prefix does not exist in the context.
> 
> Now would be a perfect place to have a relative IRI example. You've
> just talked about there being absolute and relative IRIs, and given an
> example only of absolute ones.

I've added an example in [6].


[1]
https://github.com/json-ld/json-ld.org/commit/aa43ac1f788bc2b69460319696edab
6c6cb217cf
[2]
https://github.com/json-ld/json-ld.org/commit/1d20718c328e932a90b0445eae7f3a
61df8a4840
[3]
https://github.com/json-ld/json-ld.org/commit/18a5cad721c778b3c222f141e694bd
7a33472560
[4]
https://github.com/json-ld/json-ld.org/commit/ab62ca52d0e5d2a3fe307495f2a82b
72cdb921ee
[5]
https://github.com/json-ld/json-ld.org/commit/617b7d97ddb81a1a509fb6abd7b868
ad4f03fd9d
[6]
https://github.com/json-ld/json-ld.org/commit/b565c54464313f5ec09ed4fb58efd0
258a4c0eb2



--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 12 March 2013 18:16:04 UTC