Re: a few more JSON-LD editorial comments

On 04/04/2013 02:33 PM, Markus Lanthaler wrote:
> 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.

True.

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

Yeah, I guess....        My hesitation is that I think abstracts should 
be talking about the spec, not making claims about the world, such as 
how often and how well these transforms simplify things -- claims 
someone could potentially disagree with.

But I'm really nitpicking; it's okay.

And everything else, below, is fine.

So it's just the idlharness thing now?

You might try generating some WDs now, and seeing how they fare on pubrules.

        -- Sandro

>
>>> 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 19:23:33 UTC