Reword features intro, move context discussion up to general area.
--- 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