Added an appendix on converting to/from RDF to JSON-LD Syntax.
This change is based on a request from Richard Cyganiak.
--- 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>