--- a/spec/latest/json-ld-syntax/index.html Thu May 17 15:59:37 2012 -0400
+++ b/spec/latest/json-ld-syntax/index.html Fri May 18 00:06:50 2012 -0400
@@ -303,20 +303,22 @@
<p>
JSON, as specified in [[!RFC4627]], is a simple language for representing
-data on the Web. <tref>Linked Data</tref> is a technique for creating a graph of interlinked data across
-different
-documents or Web sites. Data entities are described using <tref>IRI</tref>s,
-which are typically dereferencable and thus may be used to find more
-information about an entity, creating a "Web of Knowledge". JSON-LD is intended to be a simple
-publishing method for expressing not only Linked Data in JSON, but also for adding
-semantics to existing JSON.
+data on the Web. <tref>Linked Data</tref> is a technique for creating a network
+of inter-connected data across different Web documents and Web sites.
+A <em>thing</em> in this data network is typically identified using an
+<tref>IRI</tref> (Internationalized Resource Identifier), which is typically
+dereference-able, and thus may be used to find more information about the
+<em>thing</em>. The <tref>IRI</tref> allows
+a software program to start at one <em>thing</em> and follow links to other
+<em>things</em> in order to learn more about all of the things described on the
+Web.
</p>
<p>
JSON-LD is designed as a lightweight syntax that can be used to express
<tref>Linked Data</tref>. It is primarily intended to be a way to use Linked Data
in Javascript and other Web-based programming environments. It is also
-useful when building interoperable Web services and when storing Linked
+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.
@@ -326,9 +328,10 @@
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 with
-added semantics. Finally, the format is intended to be easy to parse, efficient
-to generate, and only requires a very small memory footprint in order to operate.
+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 only requires a very small memory footprint in order to
+operate.
</p>
<section>
@@ -355,17 +358,14 @@
<p>
To understand the basics in this specification you must first be familiar with
-JSON, which is detailed in [[!RFC4627]]. To understand the API and how it is
-intended to operate in a programming environment, it is useful to have working
-knowledge of the JavaScript programming language [[ECMA-262]] and
-WebIDL [[!WEBIDL]].</p>
+JSON, which is detailed in [[!RFC4627]].</p>
<p>
JSON [[RFC4627]] defines several terms which are used throughout this document:
<dl>
<dt><tdef>JSON object</tdef></dt><dd>
An object structure is represented as a pair of curly brackets surrounding zero or
- more name/value pairs. A name is a <tref>string</tref>. A single colon comes after
+ more name-value pairs. A name is a <tref>string</tref>. A single colon comes after
each name, separating the name from the value. A single comma separates a value
from a following name. The names within an object SHOULD be unique.
</dd>
@@ -379,7 +379,8 @@
unless specific markup is provided (see <a href="#sets-and-lists">Sets and Lists</a>).
</dd>
<dt><tdef>string</tdef></dt><dd>
- A string is a sequence of zero or more Unicode characters, wrapped in double quotes, using backslash escapes. A
+ A string is a sequence of zero or more Unicode (UTF-8) characters,
+ wrapped in double quotes, using backslash escapes (if necessary). A
character is represented as a single character string.
</dd>
<dt><tdef>number</tdef></dt>
@@ -408,8 +409,8 @@
<section>
<h2>Syntax Tokens and Keywords</h2>
- <p>JSON-LD specifies a number of syntax tokens and <tdef title="keyword">keywords</tdef> that are using
- in all algorithms described in this section:</p>
+ <p>JSON-LD specifies a number of syntax tokens and <tdef title="keyword">keywords</tdef>
+ that are a core part of the language:</p>
<dl>
<dt><code>@context</code></dt>
@@ -420,7 +421,7 @@
<a href="#the-context">The Context</a>.</dd>
<dt><code>@graph</code></dt><dd>Used to explicitly express a <tref>linked data graph</tref>.</dd>
<dt><code>@id</code></dt>
- <dd>Used to uniquely identify things that are being described in the document.
+ <dd>Used to uniquely identify <em>things</em> that are being described in the document.
This keyword is described in the section titled
<a href="#identifying-the-subject">Identifying the Subject</a>.</dd>
<dt><code>@value</code></dt>
@@ -470,7 +471,7 @@
every week on Tuesdays at 1500 UTC.
</li>
-<li>Specification bugs and issues should be reported in the
+<li>Specification bugs and issues should be reported using the
<a href="https://github.com/json-ld/json-ld.org/issues">issue tracker</a>.</li>
<li><a href="https://github.com/json-ld/json-ld.org/tree/master/spec">Source code</a> for the
@@ -487,16 +488,17 @@
<section class="informative">
<h1>Design Goals and Rationale</h1>
-<p>A number of design considerations were explored during the creation of this
+<p>A number of design goals were established before the creation of this
markup language:</p>
<dl>
<dt>Simplicity</dt>
- <dd>Developers need only know JSON and two <tref title="keyword">keywords</tref> (<code>@context</code>
- and <code>@id</code>) to use the basic functionality in JSON-LD. No extra
- processors or software libraries are necessary to use JSON-LD in its most
- basic form. The language attempts to ensure that developers have an easy
- learning curve.</dd>
+ <dd>No extra
+ processors or software libraries should be necessary to use JSON-LD in its most
+ basic form. The language will provide developers with a very easy
+ learning curve. Developers need only know JSON and two
+ <tref title="keyword">keywords</tref> (<code>@context</code>
+ and <code>@id</code>) to use the basic functionality in JSON-LD.</dd>
<dt>Compatibility</dt>
<dd>The JSON-LD markup must be 100% compatible with JSON. This ensures that
all of the standard JSON libraries work seamlessly with JSON-LD documents.</dd>
@@ -511,16 +513,19 @@
linked was an approach that was driven by pragmatism. JSON-LD attempts to be
more practical than theoretical in its approach to Linked Data.</dd>-->
<dt>Zero Edits, most of the time</dt>
- <dd>JSON-LD provides a <a href="#referencing-contexts-from-json-documents">mechanism</a>
- that allows developers to specify <tref>context</tref> in a way that is out-of-band.
+ <dd>JSON-LD must provide a
+ <a href="#referencing-contexts-from-json-documents">mechanism</a>
+ that allows developers to specify <tref>context</tref> in a way that is
+ out-of-band.
This allows organizations that have
already deployed large JSON-based infrastructure to add meaning to their
JSON documents in a way that is not disruptive to their day-to-day operations and is
transparent to their current customers. At times, mapping JSON to
a graph representation can become difficult. In these instances, rather than
- having JSON-LD support esoteric markup, we chose not to support the use case
- and support a simplified syntax instead. So, while Zero Edits is a goal,
- it is not always possible without adding great complexity to the language.
+ having JSON-LD support an esoteric use case, we chose not to support the
+ use case and support a simplified syntax instead. So, while Zero Edits is
+ a goal, it is not always possible without adding great complexity to
+ the language.
</dd>
<dt>One-pass Processing</dt>
<dd>JSON-LD supports one-pass processing, which results in a very small memory
@@ -602,13 +607,13 @@
forward-compatibility issues, <tref>term</tref>s starting with an <code>@</code> character SHOULD NOT be used
as they might be used as <tref title="keyword">keywords</tref> in future versions of JSON-LD. Furthermore,
the use of empty terms (<code>""</code>) is discouraged as not all programming languages are able to handle
- empty property names properly.</p>
+ empty property names.</p>
<p>The Web uses <tref title="IRI">IRIs</tref> for unambiguous identification. The
idea is that these <tref>term</tref>s mean something that may be of use to other developers and that it is useful to
give them an unambiguous identifier. That is, it is useful for <tref>term</tref>s to expand to IRIs so that
developers don't accidentally step on each other's <tdef>vocabulary</tdef> terms. Furthermore, developers, and
machines, are able to use this <tref>IRI</tref> (by plugging it directly into a web browser, for instance) to go to
- the term and get a definition of what the term means. Much like we can use
+ the term and get a definition of what the term means. This mechanism is analogousto the way we can use
<a href="http://wordnet.princeton.edu/">WordNet</a> today to see the definition of words in the English language.
Developers and machines need the same sort of definition of terms. <tref title="IRI">IRIs</tref> provide a way to
ensure that these terms are unambiguous. For example, the term <code>name</code> may
@@ -804,8 +809,8 @@
<p>An <tdef>absolute IRI</tdef> is defined in [[!RFC3987]] containing a <em>scheme</em> along with
<em>path</em> and optional <em>query</em> and <em>fragment</em> segments. A <tdef>relative IRI</tdef> is an IRI
- that is relative some other <tref>absolute IRI</tref>; in the case of JSON-LD this is the base location
- of the document.</p>
+ that is relative some other <tref>absolute IRI</tref>. In JSON-LD all <tref>relative IRI</tref>s are resolved relative to the
+ <tdef>base IRI</tdef> associated with the document (typically, the directory that contains the document or the document itself).</p>
<p>IRIs can be expressed directly in the key position like so:</p>
@@ -835,14 +840,24 @@
...
},
"****name****": "Manu Sporny",
+ "status": "trollin'",
...
}
-->
</pre>
-<p><tref>Prefix</tref>es are expanded when the form of the value <tref>compact IRI</tref>
- represented as is <code>prefix:suffix</code>, and the
- prefix matches a <tref>term</tref> defined within the <tref>active context</tref>:</p>
+<p><tref>Term</tref>s are case sensitive, and MUST be matched using a case-sensitive comparison.</p>
+
+<p>JSON keys that do not expand to an absolute IRI are ignored, or removed
+in some cases, by the [[JSON-LD-API]]. However, JSON keys that do not include
+a mapping in the <tref>context</tref> are still considered valid expressions
+in JSON-LD documents - the keys just don't have any machine-readable,
+semantic meaning.</p>
+
+<p><tref>Prefix</tref>es are expanded when the form of the value is a
+ <tref>compact IRI</tref> represented as a <code>prefix:suffix</code>
+ combination, and the prefix matches a <tref>term</tref> defined within the
+ <tref>active context</tref>:</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -858,15 +873,11 @@
-->
</pre>
-<p><tref>Term</tref>s are case sensitive, and MUST be matched using a case-sensitive comparison.</p>
-
-<p>Keys that do not expand to an absolute IRI are ignored.</p>
-
<p><code>foaf:name</code> above will automatically expand out to the IRI
<code>http://xmlns.com/foaf/0.1/name</code>. See <a href="#compact-iris">Compact IRIs</a> for more details.</p>
-<p>An <tref>IRI</tref> is generated when a value is associated with a key using
-the <code>@id</code> keyword:</p>
+<p>An <tref>IRI</tref> is generated when a JSON object is used in the
+value position that contains an <code>@id</code> keyword:</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -908,7 +919,8 @@
-->
</pre>
-<p>Even though the value <code>http://manu.sporny.org/</code> is a
+<p>In the example above, even though the value
+<code>http://manu.sporny.org/</code> is expressed as a JSON
<tref>string</tref>, the type <tref>coercion</tref> rules will transform
the value into an IRI when processed by a JSON-LD Processor.</p>