a few more JSON-LD editorial comments

The abstract is a little awkward now.

    This specification defines an Application Programming Interface
    (API) and a set of algorithms for programmatic transformations of
    JSON-LD documents. By expressing the data in a way that is
    specifically tailored to a particular use case, the processing
    typically becomes much simpler.


How about changing the second sentence:

This specification defines an Application Programming Interface (API) 
and a set of algorithms for programmatic transformations of JSON-LD 
documents.   The API provides a standard way for programs to make use of 
other code which implements the transformations, and the transformations 
restructure the data so that it can be easily used in different 
applications written in different styles.


     Developers that want an overview of the JSON-LD API.
     ...etc...

In general, I think it's better (more respectful) to refer to people 
using "who" instead of "that".

     You must also understand the JSON-LD syntax defined in [JSON-LD], 
which is the base syntax used by all of the algorithms in this document.

I agree, but json-ld says you might read them in the other order:

     A companion document, the JSON-LD Processing Algorithms and API 
specification [JSON-LD-API], specifies how to work with JSON-LD at a 
higher level by providing a standard library interface for common 
JSON-LD operations. Although that document is not required for 
understanding and working with JSON-LD, for some readers it will be a 
better starting point.

Frankly, I think it's probably best to read the two side by side, 
reading the introductory material of each first, before proceeding to 
the advanced sections.  That may be hard to explain.

Also:

     There are three classes of products that can claim conformance to 
this specification: JSON-LD Processors and JSON-LD API Implementations.

You left off JSON-LD-RDF Converter, but since the list follows right 
there, I'd just stop after the colon.

    Feature at Risk 3: Allow blank nodes to be used as graph name or
    property
    ...
    RDF does not currently allow a blank node to be used as graph name
    or property. Implementations might convert such blank nodes to IRIs
    by minting new "Skolem IRIs" as per Replacing Blank Nodes with IRIs
    of [RDF11-CONCEPTS].


This seems kind of unclear, and the guidance about Skolemizing isn't 
actually in the spec.  When the At Risk flag is removed, this guidance 
would be removed...!

I think I'd have the spec say (maybe in a Note, if it doesn't flow 
well):  RDF does not allow a blank node to be used as a graph name or 
property, while JSON-LD does.  JSON-LD-RDF Converters can work around 
this restriction, when converting JSON-LD to RDF, by convert such blank 
nodes to IRIs, minting new "Skolem IRIs" as per Replacing Blank Nodes 
with IRIs of [RDF11-CONCEPTS].

Then in the At Risk note, I would say something like:

Based on feedback from implementors the Working Group may decide to 
disallow blank nodes as graph names and properties in JSON-LD.   If this 
change would affect you, be sure to send in a comment.


That's it for now.   The Round Tripping section looks great.

        -- Sandro

Received on Thursday, 4 April 2013 17:21:24 UTC