--- a/spec/latest/json-ld-syntax/index.html Mon May 21 23:59:21 2012 -0400
+++ b/spec/latest/json-ld-syntax/index.html Tue May 22 13:44:30 2012 +0800
@@ -304,13 +304,13 @@
<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 network
-of inter-connected data across different Web documents and Web sites.
+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
+<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>
@@ -329,9 +329,9 @@
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.
+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
+to generate, and only requires a very small memory footprint in order to
operate.
</p>
@@ -380,8 +380,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 (UTF-8) characters,
- wrapped in double quotes, using backslash escapes (if necessary). 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>
@@ -410,7 +410,7 @@
<section>
<h2>Syntax Tokens and Keywords</h2>
- <p>JSON-LD specifies a number of syntax tokens and <tdef title="keyword">keywords</tdef>
+ <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>
@@ -497,7 +497,7 @@
<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
+ 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>
@@ -514,18 +514,18 @@
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 must provide a
+ <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
+ 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 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
+ 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>
@@ -852,12 +852,12 @@
<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,
+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
+ combination, and the prefix matches a <tref>term</tref> defined within the
<tref>active context</tref>:</p>
<pre class="example" data-transform="updateExample">
@@ -920,8 +920,8 @@
-->
</pre>
-<p>In the example above, even though the value
-<code>http://manu.sporny.org/</code> is expressed as a JSON
+<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>
@@ -965,7 +965,7 @@
<p>A <tref>JSON object</tref> used to define property values is called a
<tref>subject definition</tref>. <tref title="subject definition">Subject definitions</tref>
- do not require an <code>@id</code>. A
+ do not require an <code>@id</code>. A
<tref>subject definition</tref>
that does not contain an <code>@id</code> property is called an
<tref>unlabeled node</tref>.</p>
@@ -1095,7 +1095,7 @@
-->
</pre>
-<p class="note">JSON-LD allows one to associate language information with
+<p class="note">JSON-LD allows one to associate language information with
<tref>term</tref>s.
See <a href="#expanded-term-definition">Expanded Term Definition</a> for
more details.</p>
@@ -1107,7 +1107,7 @@
<p>A JSON-LD author can express multiple values in a compact way by using
<tref>array</tref>s. Since graphs do not describe ordering for links
- between nodes, arrays in JSON-LD do not provide an ordering of the
+ between nodes, arrays in JSON-LD do not provide an ordering of the
listed objects by default. This is exactly the opposite from regular JSON
arrays, which are ordered by default. For example, consider the following
simple document:</p>
@@ -1231,7 +1231,7 @@
contains a single value.</p>
<p class="note">The use of <code>@container</code> in the body of a JSON-LD
- document, i.e., outside <code>@context</code> MUST be ignored by
+ document, i.e., outside <code>@context</code> MUST be ignored by
JSON-LD processors.</p>
</section>
@@ -1285,7 +1285,7 @@
</pre>
<p>The <em>modified</em> key's value above is automatically type coerced to a
-datetime value because of the information specified in the
+datetime value because of the information specified in the
<code>@context</code>.</p>
<p>The second example uses the expanded form of setting the type information
@@ -1683,10 +1683,10 @@
within the current active context. This mechanism is mainly used to associate type or language
information with a <tref>compact IRI</tref> or an <tref>absolute IRI</tref>.</p>
-<p class="note">While it is possible to define a
+<p class="note">While it is possible to define a
<tref>compact IRI</tref>, or an absolute IRI to expand to some
- other unrelated IRI (for example, <code>foaf:name</code> expanding to
- <code>http://example.org/unrelated#species</code>),
+ other unrelated IRI (for example, <code>foaf:name</code> expanding to
+ <code>http://example.org/unrelated#species</code>),
such usage is strongly discouraged.</p>
</section>
@@ -1788,7 +1788,7 @@
</pre>
<p>In this case the <code>@id</code> definition is optional, but if it does exist, the <tref>compact IRI</tref>
- or <tref>IRI</tref> is treated as a term (not a <code>prefix:suffix</code> construct)
+ or <tref>IRI</tref> is treated as a term (not a <code>prefix:suffix</code> construct)
so that the actual definition of a <tref>prefix</tref> becomes unnecessary.</p>
<p class="note">Keys in the context are treated as <tref title="term">terms</tref> for the purpose of
@@ -1796,18 +1796,18 @@
For example, one could specify that <code>dog</code> and <code>cat</code> both expanded to <code>http://example.com/vocab#animal</code>.
Doing this could be useful for establishing different type coercion or language specification rules. It also allows a <tref>compact IRI</tref> (or even an
absolute <tref>IRI</tref>) to be defined as something else entirely. For example, one could specify that
- the <tref>term</tref> <code>http://example.org/zoo</code> should expand to
- <code>http://example.org/river</code>, but this usage is discouraged because it would lead to a
+ the <tref>term</tref> <code>http://example.org/zoo</code> should expand to
+ <code>http://example.org/river</code>, but this usage is discouraged because it would lead to a
great deal of confusion among developers attempting to understand the JSON-LD document.</p>
-<p>Type coercion is performed using the unexpanded value of the key,
+<p>Type coercion is performed using the unexpanded value of the key,
which MUST have an exact match for an entry in the <tref>active context</tref>.</p>
</section>
<section>
<h3>IRI Expansion Within a Context</h3>
- <p>In general, normal IRI expansion rules apply
+ <p>In general, normal IRI expansion rules apply
anywhere an IRI is expected (see <a href="#iris">IRIs</a>). Within
a <tref>context</tref> definition, this can mean that terms defined
within the context MAY also be used within that context as long as
@@ -1867,7 +1867,7 @@
</pre>
<p><tref title="compact iri">Compact IRIs</tref>
- and <tref title="iri">IRIs</tref> MAY be used on the left-hand side of a
+ and <tref title="iri">IRIs</tref> MAY be used on the left-hand side of a
<tref>term</tref> definition.</p>
<pre class="example" data-transform="updateExample">
@@ -1900,7 +1900,7 @@
<code>@type</code> associated with the <tref>term</tref>. In the second
approach, only the <code>@type</code> associated with the <tref>term</tref> is
specified. The JSON-LD processor will derive the full <tref>IRI</tref> for
-<code>foaf:homepage</code> by looking up the <code>foaf</code>
+<code>foaf:homepage</code> by looking up the <code>foaf</code>
<tref>prefix</tref> in the
<tref>context</tref>.
</p>
@@ -1996,9 +1996,9 @@
<section>
<h2>Named Graphs</h2>
- <p>The <code>@graph</code> <tref>keyword</tref> is used to express a set of
- JSON-LD <tref>subject definition</tref>s that may not be directly related
- to one another through a property. The mechanism may also be used where
+ <p>The <code>@graph</code> <tref>keyword</tref> is used to express a set of
+ JSON-LD <tref>subject definition</tref>s that may not be directly related
+ to one another through a property. The mechanism may also be used where
<tref>embedding</tref> is not desirable to the application. For example:</p>
<pre class="example" data-transform="updateExample">
@@ -2051,13 +2051,13 @@
-->
</pre>
- <p>JSON-LD allows you to <em>name</em> things on the Web by assigning
+ <p>JSON-LD allows you to <em>name</em> things on the Web by assigning
an <code>@id</code> to them, which is typically an <tref>IRI</tref>.
This notion extends to the ability to identify graphs in the same
- manner. A developer may name data expressed using the <code>@graph</code>
- <tref>keyword</tref> by pairing it with an <code>@id</code>
- <tref>keyword</tref>. This enables the developer to make statements
- about the <tref>linked data graph</tref> itself,
+ manner. A developer may name data expressed using the <code>@graph</code>
+ <tref>keyword</tref> by pairing it with an <code>@id</code>
+ <tref>keyword</tref>. This enables the developer to make statements
+ about the <tref>linked data graph</tref> itself,
rather than just a single JSON-LD object.</p>
<pre class="example" data-transform="updateExample">
@@ -2086,7 +2086,7 @@
-->
</pre>
- <p>The example above expresses a <em>named</em>
+ <p>The example above expresses a <em>named</em>
<tref>linked data graph</tref> that is identified by the <tref>IRI</tref>
<code>http://example.org/graphs/73</code>. That graph is composed of the
statements about Manu and Gregg and a reference to another IRI, which could
@@ -2106,7 +2106,7 @@
<code>@id</code> <tref>keyword</tref>. However, authors may provide identifiers for
unlabeled nodes by using the special <code>_</code> (underscore)
<tref>prefix</tref>. This allows one to reference the node locally within the
-document, but makes it impossible to reference the node from an
+document, but makes it impossible to reference the node from an
external document. The <tref>unlabeled node</tref> identifier is scoped to the
document in which it is used.</p>
@@ -2133,10 +2133,10 @@
<section>
<h2>Aliasing Keywords</h2>
-<p>Each of the JSON-LD <tref title="keyword">keywords</tref>,
+<p>Each of the JSON-LD <tref title="keyword">keywords</tref>,
except for <code>@context</code>, MAY be aliased to application-specific
keywords. This feature allows legacy JSON content to be utilized
-by JSON-LD by re-using JSON keys that already exist in legacy documents.
+by JSON-LD by re-using JSON keys that already exist in legacy documents.
This feature also allows developers to design domain-specific implementations
using only the JSON-LD <tref>context</tref>.</p>
@@ -2165,10 +2165,10 @@
<section>
<h3>Expanded Document Form</h3>
-<p>The JSON-LD API [[JSON-LD-API]] defines an method for <em>expanding</em> a
+<p>The JSON-LD API [[JSON-LD-API]] defines an method for <em>expanding</em> a
JSON-LD document.
Expansion is the process of taking a JSON-LD document and applying a
- <code>@context</code> such that all IRIs, datatypes, and values
+ <code>@context</code> such that all IRIs, datatypes, and values
are expanded so that the <code>@context</code> is no longer necessary.</p>
<p>For example, assume the following JSON-LD input document:</p>
@@ -2211,7 +2211,7 @@
<p>Expanded document form is useful when an application has to process input
data in a deterministic form. It has been optimized to ensure that the code
that developers have to write is minimized compared to the code that would
-have to be written to operate on
+have to be written to operate on
<a href="#compact-document-form">compact document form</a>.</p>
</section>
@@ -2283,9 +2283,9 @@
application-specific compacted form by first <a href="#expanded-document-form">expanding the document</a>.
While the context provided above mapped <code>http://xmlns.com/foaf/0.1/name</code>
to <strong>name</strong>, it could have also mapped it to any arbitrary string
- provided by the developer. This powerful mechanism, along with another
- JSON-LD API technique called <em>framing</em>, allows the developer to
- re-shape the incoming JSON data into a format that is optimized for
+ provided by the developer. This powerful mechanism, along with another
+ JSON-LD API technique called <em>framing</em>, allows the developer to
+ re-shape the incoming JSON data into a format that is optimized for
their application.</p>
</section>
@@ -2300,11 +2300,12 @@
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
+JSON-LD processor will do its best to recover from the error and
deterministically transform the author's markup into valid 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
+discussed (see <a href="https://github.com/json-ld/json-ld.org/issues/114#issuecomment-5820544">ISSUE-114</a>),
+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>
@@ -2358,7 +2359,7 @@
express semantic data marked up in other languages such as 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
+ Further information on transforming JSON-LD into RDF are detailed in the
[[JSON-LD-API]].</p>
<section>
@@ -2368,7 +2369,7 @@
<section>
<h4>Prefix definitions</h4>
-<p>The JSON-LD context has direct equivalents for the Turtle
+<p>The JSON-LD context has direct equivalents for the Turtle
<code>@prefix</code> declaration:</p>
<pre class="example" data-transform="updateExample">
@@ -2397,8 +2398,8 @@
</pre>
<div class="note">
-<p>JSON-LD has no equivalent for the Turtle <code>@base</code> declaration.
- Instead, authors may use a prefix definition to resolve
+<p>JSON-LD has no equivalent for the Turtle <code>@base</code> declaration.
+ Instead, authors may use a prefix definition to resolve
<tref>relative IRI</tref>s:</p>
<pre class="example" data-transform="updateExample">
<!--