sandro's review of json-ld-api

I reviewed:

    JSON-LD 1.0 Processing Algorithms and API
    https://dvcs.w3.org/hg/json-ld/raw-file/default/spec/WD/json-ld-api/20130404/index.html
    https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html

Summary: it's in very good shape.   There are some editorial changes I'd 
suggest before LC, and I have a couple non-editorial concerns that I 
hope can be addressed easily.   I did *not* review the algorithms 
themselves; that would require either being much smarter than I am or 
creating an implementation, which I don't have time for right now.    I 
expect the intent of the algorithms is clear enough, so hopefully any 
bugs can be treated as bugs (not design changes) and fixed without 
requiring another LC.  I also did not review the API, in part since I 
don't know WebIDL.   Are there WebIDL tools that can be used to help 
check it?

Non-editorial points:

1.  I'm concerned about the restriction on lists of lists.     I don't 
like the idea that some RDF graphs can't be serialized in JSON-LD.      
I could see how compacting them could be hard (nested type 
information...?) but why not at least allow them in expanded form?

Suggested fix: let's at least make this restriction At Risk, add some 
test cases, and see how implementers fare with it.   We don't even need 
to modify the algorithms in the spec; we can just say "In the interest 
of space and simplicity, the steps necessary for handling lists of lists 
have been omitted.    Such lists and their elements must, recursively, 
be handled like other lists.   NOTE this is an AT RISK feature.  The 
Working Group might either require handling of lists-of-lists or forbid 
them in JSON-LD.   Implementers please send reports of whether you are 
able to implement handling for lists-of-lists or would instead request 
such structures be disallowed."

2.  The conformance classes don't seem quite right.   Every "JSON-LD 
Implementation" has to implement conversion to and from RDF?   I don't 
really see a need to force them to do that (and I don't think they 
will).   Every "JSON-LD Processor" has to be written in JavaScript (or 
some other language for which a WebIDL binding currently exists)?   That 
seems like a rather counter-intuitive use of the word "processor"....

Suggested fix:

    A JSON-LD Processor is a system which can perform the Expansion,
    Compaction, and Flattening operations.   JSON-LD Processors
    providing interfaces to languages for which W3C Recommended WebIDL
    bindings exist ?MUST?SHOULD? use the API defined in this
    specification [etc].

    A JSON-LD Processor With RDF Conversion is a JSON-LD Processor that
    can also perform Conversion to RDF and Conversion from RDF.

(Note that WebIDL is still in CR; I've just asked what we're supposed to 
do about that.)

3.  In Conformance it says:

    This specification does not define how JSON-LD Implementations or
    Processors handle non-conforming input documents. This implies that
    JSON-LD Implementations or Processors /MUST NOT/ attempt to correct
    malformed IRIs
    <https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-iri>
    or language tags; however, they /MAY/ issue validation warnings.

But, um, no, I don't think it does imply that.   If you don't say how 
systems are to handle non-conforming input documents, then they are free 
to handle it however they want, including by "repairing" them in various 
ways.    If you're forbidding repairing IRIs or language tags, then 
you're very much saying how systems have to handle non-conforming input 
documents.      Which is it?

4.  (something about round tripping -- but it's down in editorial 
because I thought it was editorial at first, and maybe it is, because I 
don't quite understand it.  It has to do with the rules about RDF->JSON 
conversion, in order to allow round-tripping.)

Editorial points:

title: JSON-LD 1.0 Processing Algorithms and API

    Having read it now, I think I would title it "JSON-LD Operations"
    and have the shortname be "json-ld-ops".  The given algorithms are
    one way of specifying the operations, but the key thing is the
    operations themselves, not the particular algorithms used.   I
    wouldn't mention the API in the title, because it's kind of a
    natural thing to include with the operations, so it doesn't need to
    be in the title.   I don't really expect you to take this advice,
    given how much is invested in the current framing, but I thought I
    should share it.


This document outlines an Application Programming Interface and

    s/outlines/specifies/

    s/an/a WebIDL/

a set of algorithms for programmatically transforming JSON-LD documents 
to make them easier to work with in programming environments like those 
that use JavaScript, Python, and Ruby.

    I couldn't understand the end of this sentence until I came back to
    it later.  How about just:

    "a set of operations for transforming JSON-LD documents into forms
    suitable for different uses. "

<end of abstract>

    How about another sentence like, "This document is a companion to
    [JSON-LD] which should be read first."

The way JSON-LD allows Linked Data to be expressed in a way that is 
specifically tailored to a particular person or application is by 
providing context 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-context>.

    Awkward sentence.  How about:   JSON-LD uses "contexts" to allows
    Linked Data to be expressed in a way that is specifically tailored
    to a particular person or application.

Similarly, another algorithm can be specified to subsequently apply any 
context 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-context>.

    This is a very confusing sentence.   I wonder if it wouldn't be
    helpful to introduce a term like context-free.  I dunno....

localizing all information

    This was utterly baffling until after I'd finished reading this
    section.   I suggest just dropping this phrase

Note that all IRIs 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-iri> 
have been compacted to terms 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-term> 
as specified in the context 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-context>, 
which has been injected into the output.

    Of course, sometimes one wouldn't want that.   I guess one can just
    take it out again.   Oh well, never mind.

above mapped |http://xmlns.com/foaf/0.1/nam| to |name

|

    ||missing an "e"

Please note that the flattened and compacted result always explicitly 
designates the default graph by the |@graph| member in the top-level 
JSON object 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-json-object>.

    Difficult sentence.   Took me about four tries to parse it.   How about:

    Please note that the result of flattening and compaction is always a
    JSON object which contains an @graph key whose value is the default
    graph.

This specification does not define how JSON-LD Implementations or 
Processors handle non-conforming input documents. This implies that 
JSON-LD Implementations or Processors /MUST NOT/ attempt to correct 
malformed IRIs 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-iri> 
or language tags; however, they /MAY/ issue validation warnings.

    Um, no, I don't think it does imply that.   If you don't say how
    systems are to handle non-conforming input documents, then they are
    free to handle it however they want, including by "repairing" them
    in various ways.    If you're forbidding repairing IRIs or language
    tags, then you're very much saying how systems have to handle
    non-conforming input documents.

While order is preserved in regular JSON arrays, it is not in regular 
JSON-LD arrays unless specific markup is provided (see ).

    s/markup/guidance/       (I don't think json data is "markup")

    the "see" link is missing.  I expect you mean:
    http://www.w3.org/TR/json-ld-syntax/#sets-and-lists

A a set of rules for interpreting a JSON-LD document as specified in The 
Context 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/json-ld-syntax/#the-context> 
of the

     s/A a/

     s/The Context/the Context/    (maybe?)

blank node
    A node
    <https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-node>
    in a JSON-LD graph
    <https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-json-ld-graph>
    that does not contain a de-referenceable identifier

    s/de-referenceable/global-scope/ or something like that.    Consider
    the case of tag: or urn:uuid: URIs, which are not de-referenceable
    but also would make a node be non-blank.

in the JSON-LD Syntax specification [JSON-LD 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#bib-JSON-LD>]
in The Context 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/json-ld-syntax/#the-context> 
of the [JSON-LD 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#bib-JSON-LD>] 
specification.
    of the JSON-LD syntax specification [JSON-LD
    <https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#bib-JSON-LD>].
to the syntax defined in [RFC3987 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#bib-RFC3987>].
language tag as defined by [BCP47 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#bib-BCP47>]

    It'd be nice to use a consistent style.   Officially, W3C specs are
    supposed to use this style:

        ... in _/JSON-LD 1.0/ [JSON-LD] ...

        _

    http://www.w3.org/2001/06/manual/#citation

    but it's not enforced and personally I think it's okay to just say
    "as defined by [BCP47]" instead of "as defined by /Tags for
    Identifying Languages /[BCP 47]/"/.


    So I'd just say "in [JSON-LD]", I think.

A JSON object 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-json-object> 
is a node object 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-node-object> 
if it exists outside of the JSON-LD context 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-context> 
and:

  * it does not contain the |@value|, |@list|, or |@set| keywords, or
  * it is not the top-most JSON object
    <https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-json-object>
    in the JSON-LD document consisting of no other members than |@graph|
    and |@context|.


    Wow.    That's a serious IQ-test sentence.

    I'm not sure this needs to be defined, but if it does, how about
    breaking it down, like:

    "Every JSON object in JSON-LD is classified as exactly one of: a
    node object, a value object, a list object, a value object, a graph
    object, a context, or ... [whatever else there might be]."

*General Solution*   (many times in the document)

    This term really threw me off, and doesn't seem right. I think you
    mean "Algorithm Overview" or "Algorithm Summary" or "Algorithm
    Sketch".   Since it's always in an Algorithm section it could just
    be "Sketch" or "Informal Summary".


Issue 217 <https://github.com/json-ld/json-ld.org/issues/217>

RDF does not currently allow a blank node identifier 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-blank-node-identifier> 
to be used as a graph name 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-graph-name>.

    This shouldn't be an issue any more should it? How about make it a
    NOTE, and add another line about how JSON-LD Processors can convert
    such blank nodes to IRIs as per
    http://www.w3.org/TR/rdf11-concepts/#section-skolemization if they
    need to produce valid RDF.

    (Personal aside: this restriction in RDF is in my top-10 list of
    mistakes make by Working Groups I've been a part of.   I do my best
    to put them out of my mind, but when I'm reminded of them, .... 
    grrrr.   Oh well.)

In some cases, data exists natively in the form of triples or triples 
<http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple>

    I can't quite figure out what's meant.  Maybe quads?


      10.6 Data Round Tripping

    This whole section was very confusing.    Maybe add a paragraph at
    the start saying what you're talking about.  I could never figure
    out if you meant round tripping (1) from RDF to JSON-LD and back to
    RDF or (2) from JSON-LD to RDF and back to JSON-LD.

    There was also a lot of duplication of XSD -- where you're spelling
    out the canonical forms -- but it's not clear whether you are just
    rephrasing the other spec or mean to be changing something about
    it.  I suggest in generally it's best to not try to rephrase what
    other specs say.

    The bits of javascript are nice, but are they really examples?   Hm.

    Trying to make sense of this.....      The point of this section
    seems to be to say in going JSON->RDF you need to use the canonical
    form.   Why would that matter?  I guess it would matter if when
    going from RDF->JSON you *only* convert to native types when the
    lexical representation is in canonical form.  If that rule were in
    place, then I think datatypes would roundtrip perfectly.  I think.  
    I'm not seeing that rule, though, in either this section or the
    algorithm.

When data such as decimals need to be normalized, JSON-LD authors should 
not use values that are going to undergo automatic conversion. This is 
due to the lossy nature of |xsd:double| values.

    I can't quite make sense of this.

When JSON-native number 
<https://dvcs.w3.org/hg/json-ld/raw-file/c2c0c3727efe/spec/WD/json-ld-api/20130404/index.html#dfn-number>s, 
are type coerced, lossless data round-tripping can not be guaranteed as 
rounding errors might occur.

    You mean in going RDF-JSON-RDF, if you have a literal like
    "1.99999999999999999999999999999999E0"^^xs:double that it's like to
    get messed up while in JSON double form?    That's true. But what
    are you saying to do about it?    How about saying RDF->JSON
    converters *MUST* leave things like that in expanded form?   Then
    we'd have round-tripping RDF-JSON-RDF.       However, it would break
    JSON-RDF-JSON round tripping, if the JSON in question had a number
    like 1.999999999999999999999999999999E0 in it.   (of course, many
    JSON parsers would mess that up right away; that's not really our
    fault that we can't round trip that.)


    11. The Application Programming Interface

This API provides a clean mechanism that enables developers to convert 
JSON-LD data into a a variety of output formats that are often easier to 
work with


    That sentence is a bit odd.    How about:

        This section defines an Application Programming Interface (API)
        using WebIDL, so that software modules in languages for which
        WebIDL bindings exist have a standard way to access a provided
        JSON-LD Processor.   Processors providing APIs for other
        languages SHOULD use an API similar to this one.


Pat Hayes, Sandro Hawke, and Richard Cyganiak or their input on the 
specification.

    s/or their/for their/

.....

That's it.   I hope these comments are helpful.      I'll try to check 
out json-ld next, and to stay attentive if you want to talk about any of 
my points, so maybe this can still be published on the 4th.

       -- Sandro