Merge branch 'master' of github.com:json-ld/json-ld.org
authorDave Longley <dlongley@digitalbazaar.com>
Fri, 14 Oct 2011 17:34:09 -0400
changeset 213 3f3c47b2816d
parent 206 a15350bae3d2 (current diff)
parent 212 4b5eca1b60d3 (diff)
child 214 a44b97b077a5
Merge branch 'master' of github.com:json-ld/json-ld.org
--- a/index.html	Fri Oct 14 17:33:58 2011 -0400
+++ b/index.html	Fri Oct 14 17:34:09 2011 -0400
@@ -136,6 +136,7 @@
                   <li>Meeting Records: <a href="minutes/">text and audio logs</a>
                   <li>Mailing List: <a href="http://lists.w3.org/Archives/Public/public-linked-json/">public-linked-json@w3.org</a></li>
                   <li>IRC: <a href="http://webchat.freenode.net/?channels=#json-ld">#json-ld</a> on Freenode</li>
+                  <li>W3C: Join the <a href="http://www.w3.org/community/json-ld/">Community Group</a>
                </ul>
             </div>
 
--- a/spec/latest/index.html	Fri Oct 14 17:33:58 2011 -0400
+++ b/spec/latest/index.html	Fri Oct 14 17:34:09 2011 -0400
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!DOCTYPE html>
 <html>
 <head>
 <title>JSON-LD 1.0</title>
@@ -319,8 +319,8 @@
 out-of-band. The syntax is designed to not disturb already deployed systems
 running on JSON, but provide a smooth upgrade path from JSON to JSON with
 added semantics. Finally, the format is intended to be easy to parse, efficient to
-generate, stream-based and document-based processing compatible, and require
-a very small memory footprint in order to operate.
+generate, convertible to RDF in one pass, and require a very small memory footprint
+in order to operate.
 </p>
 
 <section>
@@ -469,8 +469,8 @@
  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>Streaming</dt>
- <dd>The format supports both document-based and stream-based processing.</dd>
+ <dt>One-pass Conversion to RDF</dt>
+ <dd>JSON-LD supports one-pass conversion to RDF with a very small memory footprint.</dd>
 </dl>
 </section>
 
@@ -545,8 +545,8 @@
 <p>In JSON-LD, a context is used to map <tref>term</tref>s, i.e., keys and values
   in an JSON document, to
   <tref>IRI</tref>s. A <tdef>term</tdef> is a short word that MAY be expanded
-to an <tref>IRI</tref>. The Web uses IRIs for unambiguous identification. The 
-idea is that these <tref>term</tref>s mean something that may be of use to 
+to an <tref>IRI</tref>. The Web uses IRIs 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 Web Vocabulary terms.
@@ -658,6 +658,11 @@
 <tref>prefix</tref>es that can be used to expand JSON keys and values into
 <tref>IRI</tref>s.</p>
 
+<p class="note">To ensure the best possible performance, it is a best practice to
+put the context definition at the top of the JSON-LD document. If it isn't listed
+first, processors have to save each key-value pair until the context is processed.
+This creates a memory and complexity burden for one-pass processors.</p>
+
 </section>
 
 <section>
@@ -841,6 +846,12 @@
 <code>http://example.org/people#joebob</code>.
 </p>
 
+<p class="note">To ensure the best possible performance, it is a best practice to
+put the <code>@subject</code> key before other key-value pairs in an object. If
+it isn't listed first, processors have to save each key-value pair until
+<code>@subject</code> is processed before they can create valid triples. This
+creates a memory and complexity burden for one-pass processors.</p>
+
 </section>
 
 <section>
@@ -1356,9 +1367,9 @@
     application contexts. In order to address these issues, the concept of a
     <tref>prefix</tref> mechanism is introduced.</p>
   <p>
-    A <tdef>prefix</tdef> is a compact way of expressing a base 
+    A <tdef>prefix</tdef> is a compact way of expressing a base
     <tref>IRI</tref> to a <tref>Web Vocabulary</tref>.
-    Generally, these prefixes are used by concatenating the <em>prefix</em> and 
+    Generally, these prefixes are used by concatenating the <em>prefix</em> and
     a <em>term</em> separated by a colon (<code>:</code>).
     The prefix is a short string that identifies a particular Web vocabulary.
     For example, the prefix <code>foaf</code> may be used as a short
@@ -1372,10 +1383,10 @@
     their JSON-LD markup.
   </p>
   <p>
-    The ability to use <tref>prefix</tref>es reduces the need for developers 
+    The ability to use <tref>prefix</tref>es reduces the need for developers
     to declare every vocabulary term that they intend to use in
     the JSON-LD context. This reduces document serialization size because
-    every vocabulary term need not be declared in the context. 
+    every vocabulary term need not be declared in the context.
     <tref>Prefix</tref> also
     reduce the cognitive load on the developer. It is far easier to
     remember <code>foaf:name</code> than it is to remember
@@ -1414,7 +1425,7 @@
   </pre>
   <p>
     In this example, two different vocabularies are referred to using
-    prefixes. Those prefixes are then used as type and property values using 
+    prefixes. Those prefixes are then used as type and property values using
     the <code>prefix:term</code> notation.
   </p>
   <p>
@@ -1567,8 +1578,8 @@
 an unlabeled node or a blank node. In JSON-LD, unlabeled node identifiers are
 automatically created if a subject is not specified using the
 <code>@subject</code> keyword. However, authors may provide identifiers for
-unlabeled nodes by using the special <code>_</code> (underscore) 
-<tref>prefix</tref>. This allows to reference the node locally within the 
+unlabeled nodes by using the special <code>_</code> (underscore)
+<tref>prefix</tref>. This allows to reference the node locally within the
 document but not in an external document.</p>
 
 <pre class="example" data-transform="updateExample">
@@ -1713,7 +1724,7 @@
     <a href="#expansion-algorithm">Expansion Algorithm</a>. The
     <code>input</code> MUST be copied, expanded and returned if there are
     no errors. If the expansion fails, an appropriate exception MUST be thrown.
-    
+
     <dl class="parameters">
      <dt>object input</dt>
      <dd>The JSON-LD object to copy and perform the expansion upon.</dd>
@@ -1723,16 +1734,16 @@
 
     <dl class="exception" title="InvalidContext">
      <dt>INVALID_SYNTAX</dt>
-     <dd>A general syntax error was detected in the <code>@context</code>. 
-     For example, if a <code>@coerce</code> key maps to anything other than 
+     <dd>A general syntax error was detected in the <code>@context</code>.
+     For example, if a <code>@coerce</code> key maps to anything other than
      a string or an array of strings, this exception would be raised.</dd>
      <dt>MULTIPLE_DATATYPES</dt>
-     <dd>There is more than one target datatype specified for a single 
+     <dd>There is more than one target datatype specified for a single
      property in the list of coercion rules. This means that the processor
      does not know what the developer intended for the target datatype for a
      property.</dd>
     </dl>
-    
+
   </dd>
 
   <dt>object compact()</dt>
@@ -1751,11 +1762,11 @@
 
     <dl class="exception" title="InvalidContext">
      <dt>INVALID_SYNTAX</dt>
-     <dd>A general syntax error was detected in the <code>@context</code>. 
-     For example, if a <code>@coerce</code> key maps to anything other than 
+     <dd>A general syntax error was detected in the <code>@context</code>.
+     For example, if a <code>@coerce</code> key maps to anything other than
      a string or an array of strings, this exception would be raised.</dd>
      <dt>MULTIPLE_DATATYPES</dt>
-     <dd>There is more than one target datatype specified for a single 
+     <dd>There is more than one target datatype specified for a single
      property in the list of coercion rules. This means that the processor
      does not know what the developer intended for the target datatype for a
      property.</dd>
@@ -1777,8 +1788,8 @@
     using the <code>frame</code> according to the steps in the
     <a href="#framing-algorithm">Framing Algorithm</a>. The
     <code>input</code> is used to build the framed output and is returned if
-    there are no errors. If there are no matches for the frame, 
-    <code>null</code> MUST be returned. Exceptions MUST be thrown if there are 
+    there are no errors. If there are no matches for the frame,
+    <code>null</code> MUST be returned. Exceptions MUST be thrown if there are
     errors.
   <dl class="parameters">
      <dt>object input</dt>
@@ -1813,19 +1824,19 @@
      <dt>object optional? context</dt>
      <dd>An external context to use additionally to the context embedded in <code>input</code> when expanding the <code>input</code>.</dd>
   </dl>
-  
+
     <dl class="exception" title="InvalidContext">
      <dt>INVALID_SYNTAX</dt>
-     <dd>A general syntax error was detected in the <code>@context</code>. 
-     For example, if a <code>@coerce</code> key maps to anything other than 
+     <dd>A general syntax error was detected in the <code>@context</code>.
+     For example, if a <code>@coerce</code> key maps to anything other than
      a string or an array of strings, this exception would be raised.</dd>
      <dt>MULTIPLE_DATATYPES</dt>
-     <dd>There is more than one target datatype specified for a single 
+     <dd>There is more than one target datatype specified for a single
      property in the list of coercion rules. This means that the processor
      does not know what the developer intended for the target datatype for a
      property.</dd>
     </dl>
-  
+
   </dd>
 
   <dt>object triples()</dt>
@@ -1846,11 +1857,11 @@
 
     <dl class="exception" title="InvalidContext">
      <dt>INVALID_SYNTAX</dt>
-     <dd>A general syntax error was detected in the <code>@context</code>. 
-     For example, if a <code>@coerce</code> key maps to anything other than 
+     <dd>A general syntax error was detected in the <code>@context</code>.
+     For example, if a <code>@coerce</code> key maps to anything other than
      a string or an array of strings, this exception would be raised.</dd>
      <dt>MULTIPLE_DATATYPES</dt>
-     <dd>There is more than one target datatype specified for a single 
+     <dd>There is more than one target datatype specified for a single
      property in the list of coercion rules. This means that the processor
      does not know what the developer intended for the target datatype for a
      property.</dd>
@@ -1918,8 +1929,8 @@
   <dt><code>@language</code></dt><dd>Used to specify the language for a literal.</dd>
   <dt><code>@datatype</code></dt><dd>Used to specify the datatype for a literal.</dd>
   <dt><code>:</code></dt><dd>The separator for JSON keys and values that use the <tref>prefix</tref> mechanism.</dd>
-  <dt><code>@subject</code></dt><dd>Sets the active subjects.</dd>
-  <dt><code>@type</code></dt><dd>Used to set the type of the active subjects.</dd>
+  <dt><code>@subject</code></dt><dd>Sets the active subject.</dd>
+  <dt><code>@type</code></dt><dd>Used to set the type of the active subject.</dd>
   </dl>
 </section>
 
@@ -2034,7 +2045,7 @@
       <tref>active context</tref>'s <code>@coerce</code> mapping as described <a href="#coerce">below</a>.
     </li>
     <li>
-      Merge all entries other than the <code>@coerce</code> mapping from the <tref>local context</tref>to the
+      Merge all entries other than the <code>@coerce</code> mapping from the <tref>local context</tref> to the
       <tref>active context</tref> overwriting any duplicate values.
     </li>
   </ol>
@@ -2046,13 +2057,13 @@
       <code>@coerce</code> mapping into the <tref>active context</tref>'s
       <code>@coerce</code> mapping, overwriting any duplicate values in
       the <tref>active context</tref>'s <code>@coerce</code> mapping.
-      The <code>@coerce</code> mapping has either a single 
+      The <code>@coerce</code> mapping has either a single
       <code>prefix:term</code> value, a single <tref>term</tref> value or an
-      <tref>array</tref> of <code>prefix:term</code> or <tref>term</tref> values. 
+      <tref>array</tref> of <code>prefix:term</code> or <tref>term</tref> values.
       When merging with an existing mapping in the <tref>active context</tref>,
-      map all <tref>prefix</tref> and <tref>term</tref> values to 
+      map all <tref>prefix</tref> and <tref>term</tref> values to
       <tref>array</tref> form and replace with the union of the value from
-      the <tref>local context</tref> and the value of the 
+      the <tref>local context</tref> and the value of the
       <tref>active context</tref>. If the result is an <tref>array</tref>
       with a single value, the processor MAY represent this as a string value.
     </p>
@@ -2073,7 +2084,7 @@
     <!--
     {
         "@base": ****document-location****,
-        "@context": {
+        "@coerce": {
           "@iri": "@type"
         }
     }
@@ -2472,7 +2483,8 @@
 
 <p>In time, there may be more than one normalization algorithm that will need
 to be identified. For identification purposes, this algorithm is named
-<abbr title="Universal Graph Normalization Algorithm 2011">UGNA2011</abbr>.
+"Universal Graph Normalization Algorithm 2011"
+(<abbr title="Universal Graph Normalization Algorithm 2011">UGNA2011</abbr>).
 </p>
 
 <section>
@@ -3458,12 +3470,12 @@
 
 <p class="note">Some JSON serializers, such as PHP's native implementation,
 backslash-escapes the forward slash character. For example, the value
-<code>http://example.com/</code> would be serialized as 
+<code>http://example.com/</code> would be serialized as
 <code>http:\/\/example.com\/</code> in some
 versions of PHP. This is problematic when generating a byte
-stream for processes such as normalization. There is no need to 
+stream for processes such as normalization. There is no need to
 backslash-escape forward-slashes in JSON-LD. To aid interoperability between
-JSON-LD processors, a JSON-LD serializer MUST NOT backslash-escape 
+JSON-LD processors, a JSON-LD serializer MUST NOT backslash-escape
 forward slashes.</p>
 
 <p class="issue">Round-tripping data can be problematic if we mix and
@@ -3525,8 +3537,7 @@
   <p>
     JSON-LD is intended to have an easy to parse grammar that closely models existing
     practice in using JSON for describing object representations. This allows the use
-    of existing libraries for parsing JSON in a document-oriented fashion, or can allow
-    for stream-based parsing similar to SAX.
+    of existing libraries for parsing JSON.
   </p>
   <p>
     As with other grammars used for describing <tref>Linked Data</tref>, a key concept is that of
@@ -4167,7 +4178,7 @@
 
 <p>Developers would also benefit by allowing other vocabularies to be used
 automatically with their JSON API. There are over 200
-<tref>Web Vocabulary</tref> Documents that are available for use on the Web 
+<tref>Web Vocabulary</tref> Documents that are available for use on the Web
 today. Some of these vocabularies are:
 </p>
 
@@ -4224,7 +4235,7 @@
 is detected. In the example above, "<code>myvocab:personality</code>" would
 expand to "<code>http://example.org/myvocab#personality</code>".</p>
 
-<p>This mechanism is a short-hand, called a <tref>Web Vocabulary</tref> <tref>prefix</tref>, 
+<p>This mechanism is a short-hand, called a <tref>Web Vocabulary</tref> <tref>prefix</tref>,
 and provides developers an unambiguous way to map any JSON value to RDF.<p>
 
 </section>