Added an appendix on converting to/from RDF to JSON-LD Syntax.
authorManu Sporny <msporny@digitalbazaar.com>
Wed, 23 May 2012 22:32:46 -0400
changeset 672 4d4b5f8d7cef
parent 671 ffb7796d50ba
child 681 b8fb591aac21
Added an appendix on converting to/from RDF to JSON-LD Syntax.
This change is based on a request from Richard Cyganiak.
spec/latest/json-ld-syntax/index.html
--- a/spec/latest/json-ld-syntax/index.html	Mon May 21 23:59:21 2012 -0400
+++ b/spec/latest/json-ld-syntax/index.html	Wed May 23 22:32:46 2012 -0400
@@ -2292,21 +2292,23 @@
 </section>
 
 <section class="appendix normative">
-<h2>JSON-LD Grammar</h2>
+<h2>JSON-LD Authoring Guidelines</h2>
 
 <p>Since the JSON-LD syntax is a subset of the JSON syntax, it follows that
-all well-formed JSON-LD documents are well-formed JSON documents. It also
-means that a non-well-formed JSON document can never be a well-formed
+all valid JSON-LD documents are valid JSON documents. It also
+means that an invalid JSON document can never be a valid
 JSON-LD document. Furthermore, JSON-LD places a number of restrictions on
-the JSON syntax in order to define a <em>grammar</em> that is used to express
-valid JSON-LD documents. At times, even if this grammar is violated, a
-JSON-LD processor will do its best to recover from the error and 
-deterministically transform the author's markup into valid JSON-LD.</p>
+the JSON syntax in order to define a set of authoring <em>guidelines</em> 
+that is used to express <em>well-formed</em> JSON-LD documents. At times, 
+even if these guidelines are violated, a JSON-LD processor will do its best 
+to recover from the mistake and will deterministically transform the author's 
+markup into well-formed JSON-LD.</p>
 
-<p class="issue">The final nuanced details of the exact grammar are still being
-discussed, as well as the best mechanism to express these restrictions. EBNF
-seems like overkill since it's a subset of JSON. EBNF doesn't quite capture
-some of the more esoteric restrictions in the language.
+<p class="issue">The final details of the guidelines are still being
+discussed, as well as the best mechanism to express these restrictions. 
+EBNF doesn't quite capture what these guidelines are attempting to do - 
+which is strongly express what constitutes a well-formed JSON-LD document.
+For the time being, a simple list of plain english guidelines are provided.
 </p>
 
 <ol>
@@ -2346,7 +2348,7 @@
 </section>
 
 <section class="appendix informative">
-<h2>Markup Examples</h2>
+<h2>Converting To and From JSON-LD</h2>
 
 <p>JSON-LD is a specification for representing <tref>Linked Data</tref> in JSON. A common
   way of working with Linked Data is through <tdef>RDF</tdef>, the Resource Description Framework.
@@ -2355,16 +2357,32 @@
   RDF may be found in the [[RDF-PRIMER]].</p>
 
 <p>The JSON-LD markup examples below demonstrate how JSON-LD can be used to
-  express semantic data marked up in other languages such as Turtle, RDFa, Microformats,
+  express semantic data marked up in other languages and data models
+  such as RDF, Turtle, RDFa, Microformats,
   and Microdata. These sections are merely provided as proof that JSON-LD is
   very flexible in what it can express across different <tref>Linked Data</tref> approaches.
   Further information on transforming JSON-LD into RDF are detailed in the 
   [[JSON-LD-API]].</p>
 
 <section>
+  <h3>RDF</h3>
+  
+  <p>The RDF data model, as outlined in [[RDF-CONCEPTS]], is an abstract 
+  syntax for representing a directed graph of information. JSON-LD is 
+  capable of serializing any RDF graph, and performing full RDF to 
+  JSON-LD to RDF round-tripping. A complete description of how JSON-LD maps
+  to RDF and algorithms detailing how one can convert from RDF to 
+  JSON-LD and from JSON-LD to RDF are included in the JSON-LD API 
+  [[!JSON-LD-API]] specification.
+  </p>
+
+</section>
+
+<section>
   <h3>Turtle</h3>
 
-  <p>The following are examples of representing <tref>RDF</tref> as expressed in [[TURTLE]] into JSON-LD.</p>
+  <p>The following are examples of converting <tref>RDF</tref>
+  expressed in [[TURTLE]] into JSON-LD.</p>
 
 <section>
 <h4>Prefix definitions</h4>