- From: RDF Working Group Issue Tracker <sysbot+tracker@w3.org>
- Date: Fri, 31 May 2013 11:07:59 +0000
- To: public-rdf-wg@w3.org
RDF-ISSUE-135 (gld-wg-review): GLD WG feedback on JSON-LD and API [JSON-LD Last Call 2] http://www.w3.org/2011/rdf-wg/track/issues/135 Raised by: Markus Lanthaler On product: JSON-LD Last Call 2 Sent by Marios Meimaris on behalf of the Government Linked Data (GLD) Working Group (http://lists.w3.org/Archives/Public/public-rdf-comments/2013May/0194.html): Hello all, On behalf of the Government Linked Data (GLD) Working Group, I am sending out two brief reviews for the JSON-LD and the JSON-LD Processing Algorithms and API specifications. We are sorry for the late feedback. Overall, the documents are well written, concise and well-structured. Included in this email are some minor editorial fixes and suggestions**that should benefit readability. Congratulations to the people that worked on these! * *Note: The structure of these reviews follows the original docs' sections. Suggestions are written in the form "[section number].S[suggestion number]".* --------------------------------------------------------------------------------------------- *JSON-LD 1.0 (http://www.w3.org/TR/2013/WD-json-ld-20130411/*) * * *0. Abstract* * > " It is primarily intended to be a way to use Linked Data in Web-based > programming environments, to build interoperable Web services, and to > store Linked Data in JSON-based storage engines. " 0.S1 One of the first questions that will pop into the heads of RDF-inclined people will be how JSON-LD is related to RDF and when JSON-LD is a better choice for deploying LD. Consider adding "...but is not designed to compete with RDF, rather than complement the shortcomings of RDF syntaxes when it comes to web-based programming, web development and JSON-based data stores." *1. Introduction* > " Linked Data is a technique for creating a network of inter-connected > data across different documents and Web sites. In general, Linked > Data has four properties: 1) it uses IRIs to name things; 2) it uses > HTTP IRIs for those names; 3) the name IRIs, when dereferenced, > provide more information about the thing; and 4) the data expresses > links to data on other Web sites. > These properties allow data published on the Web to work much like Web > pages do today. One can start at one piece of Linked Data, and follow > the links to other pieces of data that are hosted on different sites > across the Web. " 1.S1 Change "technique" to "initiative"/"methodology"/"set of guidelines", as "technique" is not a very broad term in its definition. 1.S2 Merge properties (1) and (2) to one: "...it uses HTTP IRIs to name/identify things..." as they are esentially talking about the same thing. 1.S3 Mention the relationship between the terms IRI and URI at least once in the document, as inexperienced people can get confused, especially if they are inclined to expect the use of "URI" instead of "IRI". Provide a link to the LD Glossary. Something like: "...the terms IRI (https://dvcs.w3.org/hg/gld/raw-file/default/glossary/index.html#internationalized-resource-identifier) and URI (https://dvcs.w3.org/hg/gld/raw-file/default/glossary/index.html#uniform-resource-identifier) are usually used interchangeably among Working Groups and technical communities in general." 1.S4 Add to (3) "For Linked Data to achieve its purpose, IRIs must be dereferenceable." 1.S5 Data does not only express links to other web sites, as they might be in the same domain. Consider changing to "4) the data expresses links to data on other Web sites. " to "Part of the data contains links to external web sites." *2. Design Goals and Rationale* > ...must be 100% compatible with JSON... 2.S1 Might be a bit misleading as it sounds like a JSON-LD document isn't, essentially, a JSON document, but is something that is compatible. Perhaps change to something like "A JSON-LD document is always a valid JSON document...." > "JSON-LD must make the transition to JSON-LD as simple as possible..." 2.S2 Consider the following rephrase: "JSON-LD must ensure a smooth and simple transition from existing JSON document supporting systems..." for better phrasing. *3. Terminology* > "@id > Used to uniquely identify things that are being described in the > document. This keyword is described in section 5.3 Node Identifiers." 3.S1 Perhaps be a little more descriptive, e.g. "Used to uniquely identify things that are being described in the document, with IRIs, blank node identifiers etc...." > "Used to specify the natural (human) language for a particular value...." 3.S2 Change to "Used to specify the language attribute of a particular string value." > "@graph > Used to explicitly label a JSON-LD graph. This keyword is > described in section 6.13 Named Graphs." 3.S3 Perhaps briefly point out the difference between JSON-LD and RDF as far as Named Graphs are concerned? Don't forget that a lot of people reading the document are RDF people and are biased toward identifying similar notions. Add something like "...Note that JSON-LD graphs are not the same as RDF graphs, as they can be identified by blank node IRIs." *5. Basic Concepts* > "...able to use this IRI (by using a web browser, for instance) to go > to the term and get a definition of what the term means..." 5.S1 Add "This process is known as IRI dereferencing." > "In JSON-LD documents contexts may also be specified in-line. This has > the advantage that documents can be processed even in the absence of a > connection to the Web." 5.S2 Add "This is ultimately a modelling decision and different cases may require different handling." > "Values that are interpreted as IRIs, can also be expressed as > relative IRIs. For example, assuming that the following document is > located at http://example.com/about/, the relative IRI ../ would > expand to http://example.com/ (for more information on where relative > IRIs can be used, please refer to appendix B. JSON-LD Grammar)." 5.S3 Consider adding: "However, JSON-LD documents that are meant to be shared or transferred between domains should consider absolute instead of relative IRIs." *A. Data Model* A.S1 > "RDF does not currently allow a blank node to be used as graph name or > property, while JSON-LD does. JSON-LD to RDF converters can work > around this restriction, when converting JSON-LD to RDF, by converting > such blank nodes to IRIs, minting new "Skolem IRIs" as per Replacing > Blank Nodes with IRIs of [RDF11-CONCEPTS]. 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." Has the WG considered adding functionality so that blank node named graphs are removed when flattening, instead of minting IRIs? This would give the modeller some freedom to include graphs that are not meant to be published yet as LD. *C. Relationship to RDF* C.S1 This section should get more visibility. Put it at the start of the document or link to it from the introduction, prompting the RDF-literate reader to consult this section before proceeding. * End of JSON-LD 1.0 Review -------------------------------------------------------------- JSON-LD 1.0 Processing Algorithms and API* (http://www.w3.org/TR/2013/WD-json-ld-api-20130411/) Overall, the document is concise, well structured and thorough. I've taken the liberty to point out some really minor grammar and typo fixes. *0. Abstract* > " Restructuring data according the defined transformations often > dramatically simplifies its usage." 0.S1 Minor grammar fix: "Restructuring data according *to* the defined transformations..." (add "to") *4. General Terminology* > "named graph > A named graph is a pair consisting of an IRI or blank node (the graph > name) and a JSON-LD graph." 1.S1 Perhaps consider pointing out the difference between blank node identifiers for JSON-LD named graphs and RDF named graphs here? > "relative IRI > A relative IRI is an IRI that is relative some other absolute IRI; in > the case of JSON-LD this is the base location of the document." 1.S2 Minor grammar fix: "A relative IRI is an IRI that is relative *to* some other absolute IRI;..." (add "to") > "JSON-LD value > A JSON-LD value is a string, a number, true or false, a typed value, > or a language-tagged string." 1.S3 Consider replacing "...true or false..." with "...a JSON boolean value (i.e. true or false)..." *8.3 IRI Compaction* > "If no term was found that could be used to compact the IRI, an > attempt is made compact the IRI using the active context's vocabulary > mapping, if there is one" 8.3.S1 Minor grammar fix: "...an attemt is made *to* compact the IRI..." (add "to") > "This algorithm takes three required inputs and three optional inputs. > The required inputs an active context, an inverse context, and the iri > to be compacted" 8.3.S2 Minor grammar fix: "...The required inputs *are* an active context..." (add "are") *8.5 Value Compaction* > "For the former case, if the type mapping of active property is set to > @id or @vocab and value consists of only of an @id member and, if if > the container mapping of active property is set to @index," 8.5.S1 Minor grammar fix: "...and value consists only of an @id member and, if the container....." (remove excess "of" and remove excess "if") *9.2 Node Map Generation* > " If a property's value is a node object, it is replace by a node > object consisting of only an @id member." 9.2.S1 Minor typo fix: "...it is replaced by a node..." (change "replace" to "replaced") > "This relabeling of blank node identifiers is also be done for > properties and values of @type." 9.2.S2 Minor grammar fix: "...is also done for properties..." (remove "be") *9.3 Generate Blank Node Identifier* > "This algorithm is used to determine if two generate new blank node > identifiers or to relabel an existing blank node identifier to avoid > collision by the introduction of new ones." 9.3.S1 Minor typo fix: "...determine whether to generate new blank node identifiers or..." (replace "if" with "whether" and "two" with "to") *10.1 Convert to RDF Algorithm* > "Expand element according the Expansion algorithm. > Generate a node map according the Node Map Generation algorithm." 10.1.S1 "Minor grammar fix: "Expand element according to the Expansion algorithm." (add "to") "Generate a node map according to the Node Map Generation algorithm." (add "to") *10.6 Data Round Tripping* > "The numeric or boolean values itself are converted to canonical > lexical form, ..." 10.6.S1 Minor grammar fix: "The numeric or boolean values themselves are converted to..." (replace "itself" with "themselves") *END OF JSON-LD 1.0 Processing Algorithms and API review* *----------------------------------------------------------------------------------* Kind regards, Marios Meimaris
Received on Friday, 31 May 2013 11:08:01 UTC