Reword features intro, move context discussion up to general area.
authorDave Longley <dlongley@digitalbazaar.com>
Mon, 25 Feb 2013 21:24:00 -0500
changeset 1324 b10cc3a93691
parent 1323 e582aaa9ee43
child 1325 0749c2fb3f82
Reword features intro, move context discussion up to general area.
spec/latest/json-ld-api/index.html
--- a/spec/latest/json-ld-api/index.html	Fri Feb 22 17:45:45 2013 +0100
+++ b/spec/latest/json-ld-api/index.html	Mon Feb 25 21:24:00 2013 -0500
@@ -218,24 +218,34 @@
     transform JSON-LD documents so that they may be more easily consumed by
     specific applications.</p>
 
+  <p>The way JSON-LD allows Linked Data to be expressed in a way that is
+    specifically tailored to a particular person or application is by
+    providing <tref>context</tref>. By providing <tref>context</tref>,
+    JSON data can be expressed in a way that is a natural fit for a particular
+    person or application whilst also indicating how the data should be
+    understood at a global scale. In order for people or applications to
+    share data that was created using a <tref>context</tref> that is different
+    from their own, a JSON-LD processor must be able to transform a document
+    from one <tref>context</tref> to another. Instead of requiring JSON-LD
+    processors to write specific code for every imaginable
+    <tref>context</tref> switching scenario, it is much easier to specify a
+    single algorithm that can remove any <tref>context</tref>. Similarly,
+    another algorithm can be specified to subsequently apply any
+    <tref>context</tref>. These two algorithms represent the most basic
+    transformations of JSON-LD documents. They are referred to as
+    <tref>expansion</tref> and <tref>compaction</tref>, respectively.</p>
+
   <p>There are four major types of transformation that are discussed in this
     document: expansion, compaction, flattening, and RDF conversion.</p>
 
   <section class="informative">
     <h2>Expansion</h2>
 
-    <p>JSON-LD allows <tref>context</tref> to be applied to JSON data. Applying
-      <tref>context</tref> to JSON data allows it to be expressed in a way that
-      is specifically tailored to a particular person or application. A common
-      use case occurs when an application or person wants to use data that was
-      created using a different <tref>context</tref> than they would prefer.
-      Therefore, a JSON-LD processor must be able to transform the data from
-      one <tref>context</tref> to another. Instead of requiring JSON-LD processors
-      to write specific code for every imaginable <tref>context</tref> switching
-      scenario, it is much easier to specify a single algorithm that can remove
-      any <tref>context</tref> (and another that can subsequently apply any
-      <tref>context</tref>). The algorithm that removes <tref>context</tref> is
-      called <tdef>expansion</tdef>.</p>
+    <p>The algorithm that removes <tref>context</tref> is
+      called <tdef>expansion</tdef>. Before performing any other
+      transformations on a JSON-LD document, it is easiest to
+      remove any <tref>context</tref> from it, localizing all information,
+      and to make data structures more regular.</p>
 
     <p>To get an idea of how context and data structuring affects the same data,
       here is an example of JSON-LD that uses only <tref title="term">terms</tref>
@@ -286,9 +296,9 @@
       <tref>context</tref> and ensure that the data is more regular by employing
       <tref>expansion</tref>.</p>
 
-    <p><tref>Expansion</tref> has two important goals: ensuring all values
-      are represented in a regular form, and removing any contextual information
-      from the document. These goals are accomplished by expanding all properties
+    <p><tref>Expansion</tref> has two important goals: removing any contextual
+      information from the document, and ensuring all values are represented
+      in a regular form. These goals are accomplished by expanding all properties
       to <tref title="absolute IRI">absolute IRIs</tref> and by expressing all
       values in <tref title="array">arrays</tref> in
       <tref>expanded form</tref>. <tref>Expanded form</tref> is the most verbose