Added tdef/tref normalization and error checking.
Fixed numerous missing definitions and added issues for those used within algorithms which are either wrong, or need a definition.
--- a/spec/latest/json-ld-api/index.html Sun Oct 23 12:19:00 2011 -0700
+++ b/spec/latest/json-ld-api/index.html Sun Oct 23 16:26:25 2011 -0700
@@ -63,7 +63,6 @@
ref = item.textContent ;
}
if (ref) {
- ref = ref.replace(/\n/g, '_') ;
ref = ref.replace(/\s+/g, '_') ;
}
var sp = document.createElement( 'a' ) ;
@@ -84,7 +83,6 @@
ref = item.textContent ;
}
if (ref) {
- ref = ref.replace(/\n/g, '_') ;
ref = ref.replace(/\s+/g, '_') ;
}
var sp = document.createElement( 'a' ) ;
@@ -95,6 +93,7 @@
}
// now do terms
refs = document.querySelectorAll('tdef') ;
+ var tdefs = [];
for (var i = 0; i < refs.length; i++) {
var item = refs[i];
if (!item) continue ;
@@ -105,10 +104,15 @@
ref = item.textContent ;
}
if (ref) {
- ref = ref.replace(/\n/g, '_') ;
- ref = ref.replace(/\s+/g, '_') ;
+ ref = ref.replace(/\s+/g, '_').toLowerCase() ;
}
+
+ if ( tdefs[ref]) {
+ throw "Duplicate definition of term '" + ref + "'" ;
+ }
+
var sp = document.createElement( 'dfn' ) ;
+ tdefs[ref] = sp ;
sp.title = ref ;
sp.innerHTML = con ;
p.replaceChild(sp, item) ;
@@ -125,10 +129,12 @@
ref = item.textContent ;
}
if (ref) {
- ref = ref.replace(/\n/g, '_') ;
- ref = ref.replace(/\s+/g, '_') ;
+ ref = ref.replace(/\s+/g, '_').toLowerCase() ;
}
+ if ( !tdefs[ref]) {
+ throw "Reference to undefined term '" + ref + "'" ;
+ }
var sp = document.createElement( 'a' ) ;
var id = item.textContent ;
sp.className = 'tref' ;
@@ -377,7 +383,7 @@
<dd>
An array is an ordered collection of values. An array structure is represented as square brackets surrounding zero or more values (or elements). Elements are separated by commas. Within JSON-LD, array order is not preserved by default, unless
specific markup is provided (see <a href="#lists">Lists</a>). This is because the basic data model of JSON-LD
- is a directed <tref>graph</tref>, which is inherently unordered.
+ is a <tref>linked data graph</tref>, which is inherently unordered.
</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
@@ -398,6 +404,36 @@
</section>
<section>
+<h2>Linked Data</h2>
+<p>
+The following definition for <tref>Linked Data</tref> is the one that will
+be used for this specification.
+</p>
+<ol>
+ <li><tdef>Linked Data</tdef> is a set of documents, each containing a representation of a linked data graph.</li>
+ <li>A <tdef>linked data graph</tdef> is an unordered labeled directed graph, where nodes are <tref>subject</tref>s or <tref>object</tref>s, and edges are properties.</li>
+ <li>A <tdef>subject</tdef> is any node in a <tref>linked data graph</tref> with at least one outgoing edge.</li>
+ <li>A <tref>subject</tref> SHOULD be labeled with an <tref>IRI</tref> (an Internationalized Resource Identifier as described in [[!RFC3987]]).</li>
+ <li>An <tdef>object</tdef> is a node in a <tref>linked data graph</tref> with at least one incoming edge.</li>
+ <li>An <tref>object</tref> MAY be labeled with an <tref>IRI</tref>.</li>
+ <li>An object MAY be a <tref>subject</tref> and <tref>object</tref> at the same time.</li>
+ <li>A <tdef>property</tdef> is an edge of the <tref>linked data graph</tref>.</li>
+ <li>A <tref>property</tref> SHOULD be labeled with an <tref>IRI</tref>.</li>
+ <li>An <tref>IRI</tref> that is a label in a <tref>linked data graph</tref> SHOULD be dereferencable to a <tref>Linked Data</tref> document describing the labeled <tref>subject</tref>, <tref>object</tref> or <tref>property</tref>.</li>
+ <li>A <tdef>literal</tdef> is an <tref>object</tref> with a label that is not an <tref>IRI</tref></li>
+</ol>
+
+<p>
+Note that the definition for <tref>Linked Data</tref> above is silent on the
+topic of unlabeled nodes. Unlabeled nodes are not considered
+<tref>Linked Data</tref>. However, this specification allows for the expression
+of unlabled nodes, as most graph-based data sets on the Web contain a number
+of associated nodes that are not named and thus are not directly
+de-referenceable.
+</p>
+</section>
+
+<section>
<h2>Contributing</h2>
<p>There are a number of ways that one may participate in the development of
@@ -679,8 +715,7 @@
</dd>
<dt><tdef>active context</tdef></dt>
<dd>
- a context that is used to resolve <tref>prefix</tref>es and
- <tref>term</tref>s while the processing
+ a context that is used to resolve <tref>term</tref>s while the processing
algorithm is running. The <tref>active context</tref> is the context
contained within the <tref>processor state</tref>.
</dd>
@@ -692,8 +727,8 @@
<dt><tdef>processor state</tdef></dt>
<dd>
the <tref>processor state</tref>, which includes the <tref>active
- context</tref>, <tref>current subject</tref>, and
- <tref>current property</tref>. The <tref>processor state</tref> is managed
+ context</tref>, <tref>active subject</tref>, and
+ <tref>active property</tref>. The <tref>processor state</tref> is managed
as a stack with elements from the previous <tref>processor state</tref>
copied into a new <tref>processor state</tref> when entering a new
<tref>JSON object</tref>.
@@ -706,7 +741,22 @@
<dd>
The JSON-LD data structure that is produced as output by the algorithm.
</dd>
-
+ <dt><tdef>term</tdef></dt><dd>
+ A <tref>term</tref> is a short word defined with a <a href="#context">context</a> that MAY be expanded
+ to an <tref>IRI</tref>
+ </dd>
+ <dt><tdef>prefix</tdef></dt><dd>
+ A <tref>prefix</tref> is a <tref>term</tref> that expands to a Web Vocabulary base IRI. It
+ is typically used along with a <em>suffix</em> to create an IRI within a Web Vocabulary.
+ </dd>
+ <dt><tdef>plain literal</tdef></dt><dd>
+ A <tref>plain literal</tref> is a <tref>literal</tref> without a datatype, possibly including
+ a language.
+ </dd>
+ <dt><tdef>typed literal</tdef></dt><dd>
+ A <tref>typed literal</tref> is a <tref>literal</tref> with an associated <tref>IRI</tref>
+ which indicates the literal's datatype.
+ </dd>
</dl>
</section>
@@ -794,10 +844,10 @@
<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
- <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.
+ <code>prefix:suffix</code> value, a single <tref>term</tref> value or an
+ <tref>array</tref> of <code>prefix:suffix</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>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
<tref>active context</tref>. If the result is an <tref>array</tref>
@@ -833,13 +883,13 @@
<h2>IRI Expansion</h2>
<p>Keys and some values are evaluated to produce an IRI. This section defines an algorithm for
transforming a value representing an IRI into an actual IRI.</p>
- <p>IRIs may be represented as an absolute IRI, a <tref>term</tref>, a <tref>prefix</tref>:<tref>term</tref> construct, or as a value relative to <code>@base</code>
+ <p>IRIs may be represented as an absolute IRI, a <tref>term</tref>, a <tref>prefix</tref>:suffix construct, or as a value relative to <code>@base</code>
or <code>@vocab</code>.</p>
<p>The algorithm for generating an IRI is:
<ol class="algorithm">
<li>Split the value into a <em>prefix</em> and <em>suffix</em> from the first occurrence of ':'.</li>
<li>If the prefix is a '_' (underscore), the IRI is unchanged.</li>
- <li>If the <tref>active context</tref> contains a mapping for <em>prefix</em>, generate an IRI
+ <li>If the <tref>active context</tref> contains a term mapping for <em>prefix</em>, generate an IRI
by prepending the mapped prefix to the (possibly empty) suffix using textual concatenation. Note that an empty
suffix and no suffix (meaning the value contains no ':' string at all) are treated equivalently.</li>
<li>If the IRI being processed is for a property (i.e., a key's value in a <tref>JSON object</tref>, or a
@@ -856,8 +906,7 @@
<h2>IRI Compaction</h2>
<p>Some keys and values are expressed using IRIs. This section defines an
algorithm for transforming an IRI to a compact IRI using the
- <tref>term</tref>s and <tref>prefix</tref>es specified in the
- <tref>local context</tref>.</p>
+ <tref>term</tref>s specified in the <tref>local context</tref>.</p>
<p>The algorithm for generating a compacted IRI is:
<ol class="algorithm">
@@ -868,7 +917,7 @@
<tref>active context</tref>.</li>
<li>If a complete match is not found, search for a partial match from
the beginning of the IRI. For all matches that are found, the resulting
- compacted IRI is the <tref>prefix</tref> associated with the partially
+ compacted IRI is the <tref>term</tref> associated with the partially
matched IRI in the <tref>active context</tref> concatenated with a
colon (:) character and the unmatched part of the string. If there is
more than one compacted IRI produced, the final value is the
@@ -1257,6 +1306,10 @@
a flag specifying that properties that are missing from the
<tref>JSON-LD input</tref> should be omitted from the output.
</dd>
+ <dt><tdef>omit default flag</tdef></dt>
+ <dd class="issue">
+ Referenced from <tref>framing context</tref>, but not defined
+ </dd>
<dt><tdef>match limit</tdef></dt>
<dd>
A value specifying the maximum number of matches to accept when building
@@ -1326,7 +1379,8 @@
<li>The <strong>expanded frame</strong> does not have an
<code>rdf:type</code> property, but every property in the
<strong>expanded frame</strong> exists in the item.</li>
- </ol></li>
+ </ol>
+ <p class="issue"><tdef>matches array</tdef> not defined anywhere.</p></li>
<li>Process each item in the <tref>match array</tref> with its associated
<tdef>match frame</tdef>:
<ol class="algorithm">
@@ -1358,8 +1412,8 @@
<tdef>recursion input list</tdef> using the object or objects
associated with the key. If any object contains an
<code>@iri</code> value that exists in the
- <tref>normalized input</tref>, replace the object in the
- <tref>recusion input list</tref> with a new object containing
+ <strong>normalized input</strong>, replace the object in the
+ <tref>recursion input list</tref> with a new object containing
the <code>@subject</code> key where the value is the value of
the <code>@iri</code>, and all of the other key-value pairs for
that subject. Set the <tdef>recursion match frame</tdef> to the
@@ -1480,7 +1534,7 @@
<p>Notice how all of the <tref>term</tref>s have been expanded and sorted in
alphabetical order. Also, notice how the <tref>subject</tref> has been
-labeled with a <tref>blank node identifier</tref>. Normalization ensures that any arbitrary
+labeled with a <tdef>blank node identifier</tdef>. Normalization ensures that any arbitrary
graph containing exactly the same information would be normalized to exactly
the same form shown above.</p>
@@ -1495,7 +1549,7 @@
<dl>
<dt><tdef>label</tdef></dt>
<dd>
- The subject IRI associated with a graph node. The subject IRI is expressed
+ The subject <tref>IRI</tref> associated with a graph node. The subject IRI is expressed
using a key-value pair in a <tref>JSON object</tref> where the key is
<code>@subject</code> and the value is a string that is an IRI or
a <tref>JSON object</tref> containing the key <code>@iri</code> and
@@ -1634,6 +1688,10 @@
<tref>labeling prefix</tref> to create a node <tref>label</tref>. It is
initialized to <code>1</code>.
</dd>
+ <dt><tdef>deterministic labeling counter</tdef></dt>
+ <dd class="issue">
+ Not defined.
+ </dd>
<dt><tdef>map of flattened nodes</tdef></dt>
<dd>
A map containing a representation of all nodes in the graph where the
@@ -1681,7 +1739,7 @@
entry in the <tref>map of flattened nodes</tref> into the
<tref>expanded node</tref>.</li>
<li>Go through every property associated with an array in the
- <tref>expanded node</tref> and remove any duplicate IRI entries from
+ <tref>expanded node</tref> and remove any duplicate <tref>IRI</tref> entries from
the array. If the resulting array only has one IRI entry, change it
from an array to an object.</li>
<li>Set the entry for the <tref>expanded node</tref>'s <tref>label</tref>
@@ -1729,7 +1787,7 @@
<tref>old label</tref> begins with <code>_:c14n</code> then return as
the node has already been renamed.
</li>
- <li>Generate the <tdef>new label</tdef> by concatenating the
+ <li>Generate the <tref>new label</tref> by concatenating the
<tref>labeling prefix</tref> with the string value of the
<tref>labeling counter</tref>. Increment the <tref>labeling counter</tref>.
</li>
@@ -1757,7 +1815,7 @@
<ol class="algorithm">
<li>Set the <tref>labeling prefix</tref> to <code>_:c14n</code>, the
<tref>labeling counter</tref> to <code>1</code>,
- the <tdef>list of finished nodes</tdef> to an empty array, and create
+ the <tref>list of finished nodes</tref> to an empty array, and create
an empty array, the <tdef>list of unfinished nodes</tdef>.</li>
<li>For each <tref>node reference</tref> in the <tref>node state map</tref>:
<ol class="algorithm">
@@ -1790,6 +1848,7 @@
then sort the list according to the lexicographical order of the
keys' associated values. Append the list to the
<tref>list of nodes to label</tref>.
+ <span class="issue"><tdef>list of nodes to label</tdef> not defined.</span>
</li>
<li>For each key-value pair from its associated
<tref>incoming serialization map</tref>, add the key to a list and
@@ -1835,7 +1894,7 @@
<ol class="algorithm">
<li>Compare the total number of node properties. The node with fewer
properties is first.</li>
- <li>Lexicographically sort the property IRIs for each node and compare
+ <li>Lexicographically sort the property <tref>IRI</tref>s for each node and compare
the sorted lists. If an IRI is found to be lexicographically smaller, the
node containing that IRI is first.</li>
<li>Compare the values of each property against one another:
@@ -1924,7 +1983,7 @@
</li>
</ol>
</li>
- <li>If both values are expanded IRIs, the
+ <li>If both values are expanded <tref>IRI</tref>s, the
lexicographically lesser string associated with <code>@iri</code>
is first.</li>
<li>Otherwise, the two values are equivalent.</li>
@@ -1956,7 +2015,7 @@
<dt><tdef>mapping counter</tdef></dt>
<dd>
Keeps track of the number of nodes that have been mapped to
- <tref>serialization labels</tref>. It is initialized to
+ <tref>serialization label</tref>s. It is initialized to
<code>1</code>.
</dd>
<dt><tdef>processed labels map</tdef></dt>
@@ -1975,7 +2034,7 @@
Maps a <tref>serialization label</tref> to the node
<tref>label</tref> associated with it, the list of sorted
<tref>serialization label</tref>s for adjacent nodes, and the map of
- adjacent node <tref>serialiation label</tref>s to their associated
+ adjacent node <tref>serialization label</tref>s to their associated
node <tref>label</tref>s. It is initialized to an empty map.
</dd>
<dt><tdef>key stack</tdef></dt>
@@ -2072,12 +2131,12 @@
<li>Set the value associated with the <tref>label</tref> in the
<tref>processed labels map</tref> to <code>true</code>.
</li>
-<li>Generate the next <tdef>serialization label</tdef> for the
+<li>Generate the next <tref>serialization label</tref> for the
<tref>label</tref> according to the
<a href="#serialization-label-generation-algorithm">Serialization Label Generation Algorithm</a>.
</li>
<li>Create an empty map called the <tdef>adjacent serialized labels map</tdef>
-that will store mappings from <tref>serialized label</tref>s to adjacent
+that will store mappings from <tref>serialization label</tref>s to adjacent
node <tref>label</tref>s.</li>
<li>Create an empty array called the
<tdef>adjacent unserialized labels list</tdef> that will store
@@ -2092,7 +2151,10 @@
<li>Look up the <tref>target node label</tref> in the
<tref>processed labels map</tref> and if a mapping exists,
update the <tref>adjacent serialized labels map</tref> where the key is
- the value in the <tref>serialization map</tref> and the value is the
+ the value in the <tref>serialization map</tref>
+ (<span class="issue"><tdef>serialization map</tdef> is used, but should it be <tref>directed serialization map</tref>,
+ <tref>outgoing serialization map</tref>or <tref>incoming serialization map</tref>?</span>)
+ and the value is the
<tref>target node label</tref>.</li>
<li>Otherwise, add the <tref>target node label</tref> to the
<tref>adjacent unserialized labels list</tref>.
@@ -2127,6 +2189,8 @@
<ol class="algorithm">
<li>If the <tref>label</tref> is already in the
<tref>serialization labels map</tref>, return its associated value.
+ (<span class="issue"><tdef>serialization labels map</tdef> is used, but should it be <tref>directed serialization map</tref>,
+ <tref>outgoing serialization map</tref>or <tref>incoming serialization map</tref>?</span>)
</li>
<li>If the <tref>label</tref> starts with the string <code>_:c14n</code>,
the <tref>serialization label</tref> is the letter <code>c</code>
@@ -2135,7 +2199,7 @@
</li>
<li>Otherwise, the <tref>serialization label</tref> is the
letter <code>s</code> followed by the string value of
- <tref>mapping count</tref>. Increment the <tref>mapping count</tref> by
+ <tref>mapping counter</tref>. Increment the <tref>mapping counter</tref> by
<code>1</code>.
</li>
<li>Create a new key-value pair in the <tref>serialization labels map</tref>
@@ -2162,7 +2226,7 @@
<ol class="algorithm">
<li>Copy the <tref>adjacent serialized labels map</tref> to the
<tdef>adjacent serialized labels map copy</tdef>.</li>
- <li>Remove the first <tref>unserialized label</tref> from the
+ <li>Remove the first <tdef>unserialized label</tdef> from the
<tref>adjacent unserialized labels list</tref> and create a new
<tdef>new serialization label</tdef> according to the
<a href="#serialization-label-generation-algorithm">Serialization Label Generation Algorithm</a>.
@@ -2306,12 +2370,12 @@
</li>
<li>Set the <tdef>serialization fragment</tdef> to the value of
the <tref>serialization key</tref>.</li>
- <li>Set the <tref>adjacent info</tref> to the value of the
+ <li>Set the <tdef>adjacent info</tdef> to the value of the
<tref>serialization key</tref> in the
<tref>adjacent info map</tref>.
</li>
- <li>Set the <tref>adjacent node label</tref> to the node
- <tref>label</tref> from the <tref>adjacent info</tref>.
+ <li>Set the <tdef>adjacent node label</tdef> to the node
+ <tref>label</tref> from the <tref>adjacent info map</tref>.
</li>
<li>If a mapping for the <tref>adjacent node label</tref>
exists in the <tref>map of all labels</tref>:
@@ -2321,15 +2385,16 @@
<tref>serialization fragment</tref>.
</li>
</ol>
+ <span class="issue"><tdef>map of all labels</tdef> referenced but not defined.</span>
</li>
- <li>Append all of the keys in the <tref>adjacent info</tref>
+ <li>Append all of the keys in the <tref>adjacent info map</tref>
to the <tref>serialization fragment</tref>.
</li>
<li>Append the <tref>serialization fragment</tref> to the
<tref>serialization string</tref>.
</li>
<li>Push a new key info object containing the keys from the
- <tref>adjacent info</tref> and an index of <code>0</code>
+ <tref>adjacent info map</tref> and an index of <code>0</code>
onto the <tref>key stack</tref>.
</li>
<li>Recursively update the <tref>serialization string</tref>
@@ -2355,7 +2420,7 @@
</p>
<ol class="algorithm">
- <li>Initialize the <tref>label serialization</tref> to an empty string.</li>
+ <li>Initialize the <tdef>label serialization</tdef> to an empty string.</li>
<li>Append the <code>[</code> character to the
<tref>label serialization</tref>.</li>
<li>Append all properties to the <tref>label serialization</tref> by
@@ -2435,7 +2500,8 @@
<li>Append all <tref>adjacent node labels</tref> to the
<tref>label serialization</tref> by concatenating the string value
for all of them, one after the other, to the
- <tref>label serialization</tref>.</li>
+ <tref>label serialization</tref>.
+ <span class="issue"><tdef>adjacent node labels</tdef> referenced but not defined.</span></li>
<li>Push the <tref>adjacent node labels</tref> onto the
<tref>key stack</tref> and append the result of the
<a href="#mapping-serialization-algorithm">Mapping Serialization Algorithm</a>
@@ -2544,13 +2610,21 @@
</p>
<p>
As with other grammars used for describing <tref>Linked Data</tref>, a key concept is that of
- a <em>resource</em>. Resources may be of three basic types: <em>IRI</em>s, for describing
+ a <em>resource</em>. Resources may be of three basic types: <em><tref>IRI</tref></em>s, for describing
externally named entities, <em>BNodes</em>, resources for which an external name does not
exist, or is not known, and Literals, which describe terminal entities such as strings,
dates and other representations having a lexical representation possibly including
an explicit language or datatype.
</p>
<p>
+ An Internationalized Resource Identifier
+ (<tdef><abbr title="Internationalized Resource Identifier">IRI</abbr></tdef>),
+ as described in [[!RFC3987]], is a mechanism for representing unique
+ identifiers on the web. In <tref>Linked Data</tref>, an IRI is commonly
+ used for expressing a <tref>subject</tref>, a <tref>property</tref> or an
+ <tref>object</tref>.
+ </p>
+ <p>
Data described with JSON-LD may be considered to be the representation of a graph made
up of <tref>subject</tref> and <tref>object</tref> resources related via a <tref>property</tref> resource.
However, specific implementations may choose to operate on the document as a normal
@@ -2656,7 +2730,7 @@
</li>
<li>
If the <tref>JSON object</tref> does not have a <code>@subject</code> key, set the <tref>active
- object</tref> to newly generated <tdef>blank node identifier</tdef>. Generate a triple
+ object</tref> to newly generated <tref>blank node identifier</tref>. Generate a triple
representing the <tref>active subject</tref>, the <tref>active property</tref> and the
<tref>active object</tref>. Set the <tref>active subject</tref> to the <tref>active
object</tref>.
@@ -2710,15 +2784,15 @@
</li>
<li>
Otherwise, generate a triple using using the <tref>active subject</tref>, <tref>active property</tref>
- and a newly generated BNode identified as <em>first <tdef>blank node identifier</tdef></em>.
+ and a newly generated BNode identified as <em>first <tref>blank node identifier</tref></em>.
</li>
<li>
For each element other than the last element in the list:
<ol class="algorithm">
- <li>Create a processor state using the active context, <em>first <tdef>blank node identifier</tdef></em> as the <tref>active subject</tref>, and <code>rdf:first</code> as the <tref>active property</tref>.</li>
- <li>Unless this is the last element in the list, generate a new BNode identified as <em>rest <tdef>blank node identifier</tdef></em>, otherwise use <code>rdf:nil</code>.</li>
- <li>Generate a new triple using <em>first <tdef>blank node identifier</tdef></em>, <code>rdf:rest</code> and <em>rest <tdef>blank node identifier</tdef></em>.</li>
- <li>Set <em>first <tdef>blank node identifier</tdef></em> to <em>rest <tdef>blank node identifier</tdef></em>.</li>
+ <li>Create a processor state using the active context, <em>first <tref>blank node identifier</tref></em> as the <tref>active subject</tref>, and <code>rdf:first</code> as the <tref>active property</tref>.</li>
+ <li>Unless this is the last element in the list, generate a new BNode identified as <em>rest <tref>blank node identifier</tref></em>, otherwise use <code>rdf:nil</code>.</li>
+ <li>Generate a new triple using <em>first <tref>blank node identifier</tref></em>, <code>rdf:rest</code> and <em>rest <tref>blank node identifier</tref></em>.</li>
+ <li>Set <em>first <tref>blank node identifier</tref></em> to <em>rest <tref>blank node identifier</tref></em>.</li>
</ol>
</li>
</ol>
--- a/spec/latest/json-ld-syntax/index.html Sun Oct 23 12:19:00 2011 -0700
+++ b/spec/latest/json-ld-syntax/index.html Sun Oct 23 16:26:25 2011 -0700
@@ -94,6 +94,7 @@
}
// now do terms
refs = document.querySelectorAll('tdef') ;
+ var tdefs = [];
for (var i = 0; i < refs.length; i++) {
var item = refs[i];
if (!item) continue ;
@@ -104,10 +105,15 @@
ref = item.textContent ;
}
if (ref) {
- ref = ref.replace(/\n/g, '_') ;
- ref = ref.replace(/\s+/g, '_') ;
+ ref = ref.replace(/\s+/g, '_').toLowerCase() ;
}
+
+ if ( tdefs[ref]) {
+ throw "Duplicate definition of term '" + ref + "'" ;
+ }
+
var sp = document.createElement( 'dfn' ) ;
+ tdefs[ref] = sp ;
sp.title = ref ;
sp.innerHTML = con ;
p.replaceChild(sp, item) ;
@@ -124,10 +130,12 @@
ref = item.textContent ;
}
if (ref) {
- ref = ref.replace(/\n/g, '_') ;
- ref = ref.replace(/\s+/g, '_') ;
+ ref = ref.replace(/\s+/g, '_').toLowerCase() ;
}
+ if ( !tdefs[ref]) {
+ throw "Reference to undefined term '" + ref + "'" ;
+ }
var sp = document.createElement( 'a' ) ;
var id = item.textContent ;
sp.className = 'tref' ;
@@ -376,7 +384,7 @@
<dd>
An array is an ordered collection of values. An array structure is represented as square brackets surrounding zero or more values (or elements). Elements are separated by commas. Within JSON-LD, array order is not preserved by default, unless
specific markup is provided (see <a href="#lists">Lists</a>). This is because the basic data model of JSON-LD
- is a directed <tref>graph</tref>, which is inherently unordered.
+ is a <tref>linked data graph</tref>, which is inherently unordered.
</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
@@ -405,11 +413,11 @@
<dl>
<dt><code>@context</code></dt><dd>Used to set the <tref>local context</tref>.</dd>
- <dt><code>@base</code></dt><dd>Used to set the base IRI for all object IRIs affected by the <tref>active context</tref>.</dd>
- <dt><code>@vocab</code></dt><dd>Used to set the base IRI for all property IRIs affected by the <tref>active context</tref>.</dd>
+ <dt><code>@base</code></dt><dd>Used to set the base <tref>IRI</tref> for all object IRIs affected by the <tref>active context</tref>.</dd>
+ <dt><code>@vocab</code></dt><dd>Used to set the base <tref>IRI</tref> for all property IRIs affected by the <tref>active context</tref>.</dd>
<dt><code>@coerce</code></dt><dd>Used to specify type coercion rules.</dd>
<dt><code>@literal</code></dt><dd>Used to specify a literal value.</dd>
- <dt><code>@iri</code></dt><dd>Used to specify an IRI value.</dd>
+ <dt><code>@iri</code></dt><dd>Used to specify an <tref>IRI</tref> value.</dd>
<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>
@@ -483,7 +491,7 @@
more practical than theoretical in its approach to Linked Data.</dd>-->
<dt>Zero Edits, most of the time</dt>
<dd>JSON-LD provides a mechanism that allows developers to specify
- context in a way that is out-of-band. This allows organizations that have
+ <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
@@ -567,7 +575,7 @@
<section>
<h3>The Context</h3>
-<p>In JSON-LD, a context is used to map <tref>term</tref>s, i.e., keys and values
+<p>In JSON-LD, a <tdef>context</tdef> 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
@@ -645,6 +653,11 @@
may specify multiple contexts, to be processed in order, for example to include standard prefix
definitions along with a local language definition used to set the language of <tref>plain literal</tref>s:</p>
+<p>
+ The set of contexts defined within a specific <tref>JSON Object</tref> is termed a <tdef>local context</tdef>.
+ The <tdef>active context</tdef> refers to the accumulation of <tref>local context</tref>s that are in scope
+ at a specific point within the document.</p>
+
<pre class="example" data-transform="updateExample">
<!--
{
@@ -663,7 +676,7 @@
<p>JSON-LD strives to ensure that developers don't have to change the JSON
that is going into and being returned from their Web APIs. This means
- that developers can also specify a context for JSON data in an out-of-band
+ that developers can also specify a <tref>context</tref> for JSON data in an out-of-band
fashion. This is described later in this document. </p>
<p>
@@ -671,19 +684,18 @@
<tdef>Web Vocabulary</tdef> to define <tref>term</tref>s that are then used
to describe concepts and "things" in the world.
Typically, these Web Vocabulary documents have <tref>prefix</tref>es associated
- with them and contain a number of <tref>term</tref> declarations. A
- <tdef>prefix</tdef>, like a <tref>term</tref>, is a short word that expands
- to a Web Vocabulary base IRI. <tref>Prefix</tref>es are helpful when a developer
- wants to mix multiple vocabularies together in a context, but does not want
+ with them and contain a number of <tref>term</tref> declarations.
+ <tref>Prefix</tref>es are helpful when a developer
+ wants to mix multiple vocabularies together in a <tref>context</tref>, but does not want
to go to the trouble of defining every single term in every single vocabulary.
Some Web Vocabularies may have dozens of terms defined. If a developer wants to use
3-4 different vocabularies, the number of terms that
- would have to be declared in a single context could become quite large. To
+ would have to be declared in a single <tref>context</tref> could become quite large. To
reduce the number of different terms that must be defined, JSON-LD also allows
prefixes to be used to compact IRIs.
<p>
-<p>For example, the IRI <code>http://xmlns.com/foaf/0.1/</code>
+<p>For example, the <tref>IRI</tref> <code>http://xmlns.com/foaf/0.1/</code>
specifies a <tref>Web Vocabulary</tref> which may be represented using the
<code>foaf</code> <tref>prefix</tref>. The <code>foaf</code> Web Vocabulary
contains a term called <strong>name</strong>. If you join the
@@ -695,7 +707,7 @@
term is used to specify a person's name.
</p>
-<p>Developers, and machines, are able to use this IRI (plugging it
+<p>Developers, and machines, are able to use this <tref>IRI</tref> (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 <a href="http://wordnet.princeton.edu/">WordNet</a> today to
see the definition
@@ -704,13 +716,13 @@
are unambiguous.
</p>
-<p>The context provides a collection of vocabulary <tref>term</tref>s and
+<p>The <tref>context</tref> provides a collection of vocabulary <tref>term</tref>s and
<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.
+put the <tref>context</tref> 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 <tref>context</tref> is processed.
This creates a memory and complexity burden for one-pass processors.</p>
<section>
<h2>External Contexts</h2>
@@ -718,7 +730,7 @@
<p>Authors may choose to declare JSON-LD <tref>context</tref>s in external
documents to promote re-use of contexts as well as reduce the size of JSON-LD
documents.
-In order to use an external context, an author MAY specify an IRI to a valid
+In order to use an external context, an author MAY specify an <tref>IRI</tref> to a valid
JSON-LD document. The referenced document MUST have a top-level <tref>JSON Object</tref>.
The value of any <code>@context</code> key within that object is substituted for
the IRI within the referencing document to have the same effect as if the value were
@@ -756,10 +768,10 @@
-->
</pre>
-<p>Each context in a list will be evaluated in-order. Duplicate mappings within the contexts MUST be
+<p>Each context in a list will be evaluated in-order. Duplicate mappings within the <tref>context</tref>s MUST be
overwritten on a last-defined-overrides basis. The context list MUST contain
-either de-referenceable IRIs or <tref>JSON Object</tref>s that conform to the
-context syntax as described in this document.</p>
+either de-referenceable <tref>IRI</tref>s or <tref>JSON Object</tref>s that conform to the
+<tref>context</tref> syntax as described in this document.</p>
<p>External JSON-LD context documents MAY contain extra information located
outside of the <code>@context</code> key, such as
@@ -778,7 +790,7 @@
<p>If a set of terms such as, <strong>name</strong>, <strong>homepage</strong>,
and <strong>avatar</strong>,
-are defined in a context, and that context is used to resolve the
+are defined in a <tref>context</tref>, and that context is used to resolve the
names in JSON objects, machines are able to automatically expand the terms to
something meaningful and unambiguous, like this:</p>
@@ -809,28 +821,28 @@
<p>JSON-LD is designed to ensure that Linked Data concepts can be marked
up in a way that is simple to understand and author by Web developers. In many
cases, regular JSON markup can become Linked Data with the simple addition
-of a context. As more JSON-LD features are used, more semantics are added
+of a <tref>context</tref>. As more JSON-LD features are used, more semantics are added
to the JSON markup.</p>
<section>
<h2>IRIs</h2>
-<p>Expressing IRIs are fundamental to Linked Data as that is how most
-<tref>subject</tref>s and many <tref>object</tref> are named. IRIs can be
+<p>Expressing <tref>IRI</tref>s are fundamental to Linked Data as that is how most
+<tref>subject</tref>s and many <tref>object</tref> are named. <tref>IRI</tref>s can be
expressed in a variety of different ways in JSON-LD.</p>
<ol>
<li>In general, <tref>term</tref>s in the key position in
- a <tref>JSON object</tref> that have a mapping to an IRI or another key in the context are
+ a <tref>JSON object</tref> that have a mapping to an <tref>IRI</tref> or another key in the <tref>context</tref> are
expanded to an IRI by JSON-LD processors. There are special rules for
processing keys in <code>@context</code> and when dealing with keys that
start with the <code>@subject</code> character.</li>
- <li>An IRI is generated for the value specified using <code>@subject</code>,
+ <li>An <tref>IRI</tref> is generated for the value specified using <code>@subject</code>,
if it is a <tref>string</tref>.</li>
- <li>An IRI is generated for the value specified using <code>@type</code>.</li>
- <li>An IRI is generated for the value specified using the <code>@iri</code>
+ <li>An <tref>IRI</tref> is generated for the value specified using <code>@type</code>.</li>
+ <li>An <tref>IRI</tref> is generated for the value specified using the <code>@iri</code>
keyword.</li>
- <li>An IRI is generated when there are <code>@coerce</code> rules in
+ <li>An <tref>IRI</tref> is generated when there are <code>@coerce</code> rules in
effect for a key named <code>@iri</code>.</li>
</ol>
@@ -848,7 +860,7 @@
</pre>
<p>In the example above, the key
-<code>http://xmlns.com/foaf/0.1/name</code> is interpreted as an IRI, as
+<code>http://xmlns.com/foaf/0.1/name</code> is interpreted as an <tref>IRI</tref>, as
opposed to being interpreted as a string.</p>
<p>Term expansion occurs for IRIs if a term is defined within the
@@ -881,7 +893,7 @@
<p><code>foaf:name</code> above will automatically expand out to the IRI
<code>http://xmlns.com/foaf/0.1/name</code>.</p>
-<p>An IRI is generated when a value is associated with a key using
+<p>An <tref>IRI</tref> is generated when a value is associated with a key using
the <code>@iri</code> keyword:</p>
<pre class="example" data-transform="updateExample">
@@ -1043,7 +1055,7 @@
that is generated. Languages MUST be expressed in [[!BCP47]] format.</p>
<p>It is also possible to set a language to use within a <code>@context</code>, to allow specify a language
-to apply to all <tref>plain literal</tref>s within the scope of the context</p>
+to apply to all <tref>plain literal</tref>s within the scope of the <tref>context</tref></p>
<pre class="example" data-transform="updateExample">
<!--
@@ -1065,7 +1077,7 @@
<p>
A value with an associated datatype, also known as a
<tdef>typed literal</tdef>, is indicated by associating a literal with
- an IRI which indicates the literal's datatype. Typed literals may be
+ an <tref>IRI</tref> which indicates the literal's datatype. Typed literals may be
expressed in JSON-LD in three ways:
</p>
@@ -1326,11 +1338,11 @@
<section>
<h3>Base URI</h3>
-<p>JSON-LD allows IRIs to be specified in a relative form. For <tref>subject</tref> and <tref>object</tref>
+<p>JSON-LD allows <tref>IRI</tref>s to be specified in a relative form. For <tref>subject</tref> and <tref>object</tref>
IRIs, relative IRIs are resolved against the document base using
<cite><a href="http://www.ietf.org/rfc/rfc2396.txt">section 5.1 Establishing a
Base URI</a></cite> of [[RFC3986]]. This value may be explicitly
- set with a context using the <code>@base</code> keyword.</p>
+ set with a <tref>context</tref> using the <code>@base</code> keyword.</p>
<p>For example, if a JSON-LD document was retrieved from <code>http://manu.sporny.org/</code>,
relative IRIs would resolve against that URI:</p>
@@ -1346,10 +1358,10 @@
</pre>
<p>This document uses an empty <code>@subject</code>, which resolves to the document base. However, if
- the document is moved to a different location, the subject IRI would change. To prevent this, a context
+ the document is moved to a different location, the subject IRI would change. To prevent this, a <tref>context</tref>
may have a <code>@base</code> mapping, to set an absolute base for the document in spite of where
it actually is retrieved from. It MUST have a value of a simple
- <tref>string</tref> with the lexical form of an absolute IRI.</p>
+ <tref>string</tref> with the lexical form of an absolute <tref>IRI</tref>.</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -1368,8 +1380,8 @@
<p>It is often common that all types and properties come from the same vocabulary. JSON-LD provides
a way to set a base URI to be used for all properties and types that aren't based on terms,
prefixes or absolute IRIs. Much like the <code>@base</code> keyword, the <code>@vocab</code> keyword
- can be used to set a base IRI to use for all types and properties that don't otherwise resolve to
- an absolute IRI.
+ can be used to set a base <tref>IRI</tref> to use for all types and properties that don't otherwise resolve to
+ an absolute <tref>IRI</tref>.
<pre class="example" data-transform="updateExample">
<!--
@@ -1405,7 +1417,7 @@
-->
</pre>
-<p>By specifying <code>@language</code> within a context, multiple language-tagged literals may be
+<p>By specifying <code>@language</code> within a <tref>context</tref>, multiple language-tagged literals may be
marked up using a simple string form:</p>
</section>
@@ -1428,20 +1440,21 @@
hundreds of potential vocabulary terms that may be used across an
application. This is a concern for at least three reasons; the
first is the cognitive load on the developer, the second is
- the serialized size of the context, the third is future-proofing
+ the serialized size of the <tref>context</tref>, the third is future-proofing
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
<tref>IRI</tref> to a <tref>Web Vocabulary</tref>.
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.
+ a <em>suffix</em> separated by a colon (<code>:</code>).
+ The <tref>prefix</tref> is a <tref>term</tref> taken from the <tref>active context</tref>,
+ a short string that identifies a particular Web vocabulary.
For example, the prefix <code>foaf</code> may be used as a short
hand for the Friend-of-a-Friend Web Vocabulary, which is identified using
the IRI <code>http://xmlns.com/foaf/0.1/</code>. A developer may append any of
the FOAF Vocabulary terms to the end of the prefix to specify a short-hand
- version of the full IRI for the vocabulary term. For example,
+ version of the absolute IRI for the vocabulary term. For example,
<code>foaf:name</code> would be expanded out to the IRI
<code>http://xmlns.com/foaf/0.1/name</code>. Instead of having to remember
and type out the entire IRI, the developer can instead use the prefix in
@@ -1450,18 +1463,18 @@
<p>
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
+ the JSON-LD <tref>context</tref>. This reduces document serialization size because
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
<code>http://xmlns.com/foaf/0.1/name</code>. The use of prefixes also
- ensures that a context document does not have to be updated in lock-step
+ ensures that a <tref>context</tref> document does not have to be updated in lock-step
with an externally defined <tref>Web Vocabulary</tref>. Without prefixes, a developer
would need to keep their application context terms in lock-step with an
externally defined Web Vocabulary. Rather, by just declaring the
Web Vocabulary prefix, one can use new terms as they're declared
- without having to update the application's JSON-LD context.
+ without having to update the application's JSON-LD <tref>context</tref>.
</p>
<p>Consider the following example:</p>
<pre class="example" data-transform="updateExample">
@@ -1491,14 +1504,14 @@
<p>
In this example, two different vocabularies are referred to using
prefixes. Those prefixes are then used as type and property values using
- the <code>prefix:term</code> notation.
+ the <code>prefix:suffix</code> notation.
</p>
<p>
Prefixes, also known as CURIEs, are defined more formally in RDFa Core 1.1,
<cite><a href="http://www.w3.org/TR/rdfa-core/#s_curies">Section 6
"CURIE Syntax Definition"</a></cite> [[RDFA-CORE]].
JSON-LD does not support the square-bracketed CURIE syntax as the
- mechanism is not required to disambiguate IRIs in a JSON-LD document like
+ mechanism is not required to disambiguate <tref>IRI</tref>s in a JSON-LD document like
it is in HTML documents.
</p>
</section>
@@ -1556,7 +1569,7 @@
<p>JSON-LD supports the coercion of values to particular data types.
Type coercion allows someone deploying JSON-LD to coerce the incoming or
-outgoing types to the proper data type based on a mapping of data type IRIs to
+outgoing types to the proper data type based on a mapping of data type <tref>IRI</tref>s to
property types. Using type coercion, one may convert simple JSON data to
properly typed RDF data.</p>
@@ -1707,7 +1720,7 @@
unlabeled node. This practice, however, is usually frowned upon when
generating Linked Data. If a developer finds that they refer to the unlabeled
node more than once, they should consider naming the node using a resolve-able
-IRI.
+<tref>IRI</tref>.
</p>
</section>
@@ -1718,7 +1731,7 @@
<p>JSON-LD allows all of the syntax keywords, except for <code>@context</code>,
to be aliased. This feature allows more legacy JSON content to be supported
by JSON-LD. It also allows developers to design domain-specific implementations
-using only the JSON-LD context.</p>
+using only the JSON-LD <tref>context</tref>.</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -1779,7 +1792,7 @@
</pre>
<p>An example JSON-LD implementation is described below, however, there are
-other ways to mark-up this information such that the context is not
+other ways to mark-up this information such that the <tref>context</tref> is not
repeated.</p>
<pre class="example" data-transform="updateExample">
@@ -1827,7 +1840,7 @@
</pre>
<p>The representation of the hCard expresses the Microformat terms in the
-context and uses them directly for the <code>url</code> and <code>fn</code>
+<tref>context</tref> and uses them directly for the <code>url</code> and <code>fn</code>
properties. Also note that the Microformat to JSON-LD processor has
generated the proper URL type for <code>http://tantek.com</code>.</p>
@@ -1888,7 +1901,7 @@
<p>Note that the JSON-LD representation of the Microdata information stays
true to the desires of the Microdata community to avoid contexts and
-instead refer to items by their full IRI.</p>
+instead refer to items by their full <tref>IRI</tref>.</p>
<pre class="example" data-transform="updateExample">
<!--