Move the list of features that JSON-LD adds to JSON to the introduction
authorMarkus Lanthaler <mark_lanthaler@gmx.net>
Fri, 05 Oct 2012 18:47:09 +0200
changeset 905 ba99e5cf4282
parent 904 2d78a631f71d
child 906 28c8a96c7fe9
child 907 8a9c2db7ad44
Move the list of features that JSON-LD adds to JSON to the introduction

and combined the three lists to one.

This closes #155.
spec/latest/json-ld-syntax/index.html
--- a/spec/latest/json-ld-syntax/index.html	Thu Oct 04 12:20:07 2012 +0200
+++ b/spec/latest/json-ld-syntax/index.html	Fri Oct 05 18:47:09 2012 +0200
@@ -327,18 +327,35 @@
 
 <p>JSON-LD is designed as a lightweight syntax to express <tref>Linked Data</tref> in
   JSON [[!RFC4627]]. It is primarily intended to be a way to use Linked Data in
-  Web-based programming environments. It is also useful when building inter-operable
-  Web services and when storing Linked Data in JSON-based document storage engines.
-  It is practical and designed to be as simple as possible, utilizing the large
-  number of JSON parsers and libraries available today.</p>
-
-<p>The syntax does not necessarily require applications to change their JSON, but
-  allows one to easily add meaning by simply adding or referencing a context.
+  Web-based programming environments. It is also useful when building interoperable
+  Web services and when storing Linked Data in JSON-based storage engines. JSON-LD is
+  is 100% compatible with JSON allowing to utilize the large number of JSON parsers
+  and libraries available today. Additionally to all the features JSON provides,
+  it introduces:</p>
+
+<ul>
+  <li>a universal identifier mechanism for <tref>JSON object</tref>s via the
+    use of <tref>IRI</tref>s,</li>
+  <li>a way to disambiguate the keys used between multiple JSON documents
+    by mapping them to <tref>IRI</tref>s via a <tref>context</tref>,</li>
+  <li>a mechanism in which a value in a <tref>JSON object</tref> may refer
+    to a <tref>JSON object</tref> on a different site on the Web,</li>
+  <li>the ability to express the language associated with a <tref>string</tref></li>
+  <li>a way to associate datatypes with values such as dates, times, weights,
+    and distances,</li>
+  <li>and a facility to express one or more directed graphs, such as a social
+    network, in a single document.</li>
+</ul>
+
+<p>Developers that require any of the facilities listed above will find JSON-LD
+  of interest. The syntax does not necessarily require applications to change their
+  JSON, but allows one to easily add meaning by simply adding or referencing a context.
   The syntax is designed to not disturb already deployed systems running on JSON,
   but provide a smooth upgrade path from JSON to JSON-LD. Finally, the format is
   intended to be easy to parse, efficient to generate, and can operate inside of
   devices that contain very little memory.</p>
 
+
 <section>
 <h2>How to Read this Document</h2>
 
@@ -434,82 +451,6 @@
 <section class="normative">
 <h1>Basic Concepts</h1>
 
-<p>JSON-LD is designed to ensure that <tref>Linked Data</tref> concepts can be
-marked up in a way that is simple to understand and create by Web authors.
-In many cases, regular JSON markup can become Linked Data with the
-simple addition of a <tref>context</tref>. As more JSON-LD features are
-used, more semantics are added to the JSON markup.</p>
-
-<section>
-<h2>Benefits of JSON-LD</h2>
-
-<p>
-JSON provides a number of benefits to software developers that need to
-serialize data:
-</p>
-
-<ol>
-<li>It is easy for humans to read and write.</li>
-<li>It is easy for machines to parse and generate.</li>
-<li>It has a syntax that is familiar across a large number of programming
-  languages.</li>
-<li>It is capable of representing many different types of data using two
-universal data structures; a collection of key-value pairs and lists.</li>
-</ol>
-
-<p>
-JSON has become a very popular data-interchange format on the Web, particularly
-for <a href="http://en.wikipedia.org/wiki/REST">REST</a>-based Web Services.
-Unfortunately, it has a number of short-comings that other Web-native data
-formats do not have:
-</p>
-
-<ol>
-<li>There is no standardized, universal identifier mechanism for
-<tref>JSON object</tref>s.</li>
-<li>The meaning of the keys used in a
-<tref>JSON object</tref>s are ambiguous and often conflict with other data
-published on the Web.
-</li>
-<li>There is no standardized way for a value in a <tref>JSON object</tref> to
-refer to a <tref>JSON object</tref> on a different site on the Web.</li>
-<li>A developer cannot express the language associated with a
-<tref>string</tref> value in a standardized manner.</li>
-<li>There is no standard mechanism to associate datatypes with values such as
- dates, times, weights, and distances.</li>
-<li>There is no facility to express a Web of information (directed graph),
-such as a social network, in a standardized manner.</li>
-</ol>
-
-<p>
-JSON-LD is a web-native standard, is 100% compatible with JSON,
-provides all of the facilities that JSON provides, and extends the
-language to provide the following core advantages:
-</p>
-
-<ol>
-<li>A universal identifier mechanism for <tref>JSON object</tref>s via
-the use of <tref>IRI</tref>s.</li>
-<li>A way to dis-ambiguate the keys used between multiple JSON documents
-by mapping them to <tref>IRI</tref>s via a <tref>context</tref>.
-</li>
-<li>A mechanism in which a value in a <tref>JSON object</tref> may
-refer to a <tref>JSON object</tref> on a different site on the Web.</li>
-<li>The ability to express the language associated with a
-<tref>string</tref> value.</li>
-<li>A way to associate datatypes with values such as dates, times,
-  weights, and distances.</li>
-<li>A facility to express one or more directed graphs, such as a social
-network, in a single document.</li>
-</ol>
-
-<p>
-Developers that require any of the facilities listed above will find
-JSON-LD of interest.
-</p>
-
-</section>
-
 <section>
 <h2>JSON-LD Data Model</h2>