- From: Markus Lanthaler <markus.lanthaler@gmx.net>
- Date: Thu, 4 Apr 2013 20:33:48 +0200
- To: "'W3C RDF WG'" <public-rdf-wg@w3.org>
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