- From: Sandro Hawke <sandro@w3.org>
- Date: Thu, 04 Apr 2013 15:23:21 -0400
- To: Markus Lanthaler <markus.lanthaler@gmx.net>
- CC: 'W3C RDF WG' <public-rdf-wg@w3.org>
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