RE: a few more JSON-LD editorial comments

Thanks for having another look at the spec Sandro. I've fixed everything
except the abstract. More comments inline.


On Thursday, April 04, 2013 7:21 PM, Sandro Hawke wrote:

> 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.

Hmm... I'm not sure this sounds much better. What about

This specification defines an Application Programming Interface
(API) and a set of algorithms for programmatic transformations of
JSON-LD documents. Restructuring data according the defined
transformations often dramatically simplifies its usage.


> > 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".

Fixed


> > 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.

I removed the second sentence. People interested in the API will know where
to look themselves.


> 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.

I added it, I thought that flows better.


> 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.

OK, I changed the issue markers and also included the text in both the API
and the syntax spec.


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

I'm glad to hear that :-)


Here are the diffs of the changes I made:

https://github.com/json-ld/json-ld.org/commit/a3d588223192055653dd5262742688
bea96be38b
https://github.com/json-ld/json-ld.org/commit/55ebd2cddf9fdc4fd39f027e708b44
b111275f4f


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 4 April 2013 18:34:28 UTC