--- a/spec/latest/json-ld-api/index.html Thu Mar 22 12:47:26 2012 -0700
+++ b/spec/latest/json-ld-api/index.html Thu Mar 22 18:00:46 2012 -0700
@@ -400,6 +400,7 @@
</dd>
<dt><tdef>null</tdef></dt><dd>
The use of the <tref>null</tref> value within JSON-LD is used to ignore or reset values.
+ </dd>
</dl>
</p>
</section>
@@ -584,13 +585,13 @@
</dd>
- <dt>DOMString normalize()</dt>
+ <dt>object normalize()</dt>
<dd><a href="#normalization">Normalizes</a> the given <code>input</code>
according to the steps in the
<a href="#normalization-algorithm">Normalization Algorithm</a>. The
<code>input</code> MUST be copied, normalized and returned if there are
no errors. If the compaction fails, <tref>null</tref> MUST be returned.
- The output is the serialized representation returned from the
+ The output is an array of <tref>JSON Object</tref> definitions normalized by the
<a href="#normalization-algorithm">Normalization Algorithm</a>.
<span class="issue">It's still an open question if the result is a DOMString
representing the serialized graph in JSON-LD, or an <tref>array</tref> representation
@@ -620,18 +621,24 @@
</dd>
- <dt>void triples()</dt>
+ <dt>object fromTriples()</dt>
+ <dd>Creates a JSON-LD document given an set of <a>Triple</a>s, in the form of an iterator.
+ <dl class="parameters">
+ <dt>Triple[] input</dt>
+ <dd>An array of triples, ordered by <code>subject</code>.</dd>
+ </dl>
+ </dd>
+
+ <dt>void toTriples()</dt>
<dd>Processes the <code>input</code> according to the
- <a href="#rdf-conversion-algorithm">RDF Conversion Algorithm</a>, calling
- the provided <code>tripleCallback</code> for each triple generated.
+ <a href="#convert-to-rdf-algorithm">Convert to RDF Algorithm</a>, calling
+ the provided <code>tripleCallback</code> for each <a>Triple</a> generated.
<dl class="parameters">
<dt>object input</dt>
<dd>The JSON-LD object to process when outputting triples.</dd>
- <dt>JsonLdTripleCallback tripleCallback</dt>
- <dd>A callback that is called whenever a processing error occurs on
- the given <code>input</code>.
- <div class="issue">This callback should be aligned with the
- RDF API.</div></dd>
+ <dt>TripleCallback tripleCallback</dt>
+ <dd>A callback that is called a <a>Triple</a> is created from processing
+ the given <code>input</code>.</dd>
<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>
@@ -659,34 +666,125 @@
</section>
<section>
- <h3>JsonLdTripleCallback</h3>
- <p>The JsonLdTripleCallback is called whenever the processor generates a
+ <h3>TripleCallback</h3>
+ <p>The TripleCallback is called whenever the processor generates a
triple during the <code>triple()</code> call.</p>
- <dl title="[NoInterfaceObject Callback] interface JsonLdTripleCallback"
+ <dl title="[NoInterfaceObject Callback] interface TripleCallback"
class="idl">
<dt>void triple()</dt>
<dd>This callback is invoked whenever a triple is generated by the processor.
<dl class="parameters">
- <dt>DOMString subject</dt>
- <dd>The subject <tref>IRI</tref> that is associated with the triple.</dd>
- <dt>DOMString property</dt>
- <dd>The property <tref>IRI</tref> that is associated with the triple.</dd>
- <dt>DOMString objectType</dt>
- <dd>The type of object that is associated with the triple. Valid values
- are <code>IRI</code> and <code>literal</code>.</dd>
- <dt>DOMString object</dt>
- <dd>The object value associated with the subject and the property.</dd>
- <dt>DOMString? datatype</dt>
- <dd>The datatype associated with the object.</dd>
- <dt>DOMString? language</dt>
- <dd>The language associated with the object in BCP47 format.</dd>
+ <dt>Triple triple</dt>
+ <dd>The triple.</dd>
</dl>
</dd>
</dl>
</section>
+ <section>
+ <h3>Data Structures</h3>
+ <p>The following data structures are used for representing data about RDF Triples. They
+ are used for normalization, triples, and from Triples interfaces.</p>
+
+ <section>
+ <h3>Triple</h3>
+ <p>The <a>Triple</a> interface represents an RDF Triple.</p>
+ <dl title="[NoInterfaceObject] interface Triple" class="idl">
+ <dt>readonly attribute Node subject</dt>
+ <dd>The subject associated with the <a>Triple</a>.</dd>
+ <dt>readonly attribute Node property</dt>
+ <dd>The property associated with the <a>Triple</a>.</dd>
+ <dt>readonly attribute Node object</dt>
+ <dd>The object associated with the <a>Triple</a>.</dd>
+ </dl>
+ </section>
+
+ <section class="normative">
+ <h3>Node</h3>
+ <p><a>Node</a> is the base class of <a>NamedNode</a>,
+ <a>BlankNode</a>, and <a>LiteralNode</a>.</p>
+ <dl title="[NoInterfaceObject] interface Node" class="idl">
+ <dt>readonly attribute DOMString nominalValue</dt>
+ <dd>
+ <p>The <code>nominalValue</code> of an <a>Node</a> is refined by
+ each interface which extends <a>Node</a>.</p>
+ </dd>
+ <dt>readonly attribute DOMString interfaceName</dt>
+ <dd>
+ <p>Provides access to the string name of the current interface,
+ normally one of <code>"IRI"</code>, <code>"BlankNode"</code> or <code>"LiteralNode"</code>.</p>
+ <p>This method serves to disambiguate instances of <a>Node</a> which
+ are otherwise identical, such as <a>NamedNode</a> and <a>BlankNode</a>.</p>
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h3>NamedNode</h3>
+ <p>A node identified by an <tref>IRI</tref>. NamedNodes are defined by International
+ Resource Identifier [[!IRI]].</p>
+ <dl title="[NoInterfaceObject] interface NamedNode : Node"
+ class="idl">
+ <dt>readonly attribute DOMString nominalValue</dt>
+ <dd>The IRI identifier of the node.</dd>
+ </dl>
+ </section>
+
+ <section class="normative">
+ <h3>Blank Node</h3>
+ <p>A <a>BlankNode</a> is a reference to an unnamed resource
+ (one for which an IRI is not known), and may be used in a <a>Triple</a>
+ as a unique reference to that unnamed resource.</p>
+ <dl title="[NoInterfaceObject] interface BlankNode : Node"
+ class="idl">
+ <dt>readonly attribute DOMString nominalValue</dt>
+ <dd>
+ <p>The temporary identifier of the <a>BlankNode</a>.</p>
+ <p>The nominalValue MUST NOT be relied upon in any way between two
+ separate processing runs of the same document.</p>
+ </dd>
+ </dl>
+ <p class="note">Developers and authors must not assume that the
+ nominalValue of a <a>BlankNode</a> will remain the same between two
+ processing runs. <a>BlankNode</a> nominalValues are only valid for the
+ most recent processing run on the document. <a>BlankNode</a>s
+ nominalValues will often be generated differently by different processors.</p>
+
+ <p class="note">Implementers MUST ensure that <a>BlankNode</a> nominalValues are unique
+ within the current environment, two <a>BlankNode</a>s are considered equal if, and only if,
+ their nominalValues are strictly equal.</p>
+ </section>
+
+ <section class="normative">
+ <h3>LiteralNode</h3>
+ <p>LiteralNodes represent values such as numbers, dates and strings in
+ RDF data. A <a>LiteralNode</a> is comprised of three attributes:</p>
+ <ul>
+ <li>a lexical representation of the <code>nominalValue</code></li>
+ <li>an optional <code>language</code> represented by a string token</li>
+ <li>an optional <code>datatype</code> specified by a <a>NamedNode</a></li>
+ </ul>
+
+ <p>LiteralNodes representing plain text in a natural language may have a
+ <code>language</code> attribute specified by a text string token, as
+ specified in [[!BCP47]], normalized to lowercase (e.g., <code>'en'</code>, <code>'fr'</code>, <code>'en-gb'</code>).
+ They may also have a datatype attribute such as <code>xsd:string</code>.</p>
+ <p>LiteralNodes representing values with a specific datatype, such as
+ the integer 72, may have a <code>datatype</code> attribute specified in
+ the form of a <a>NamedNode</a> (e.g., <code><http://www.w3.org/2001/XMLSchema#integer></code>).</p>
+ <dl title="[NoInterfaceObject] interface LiteralNode : Node" class="idl">
+ <dt>readonly attribute DOMString nominalValue</dt>
+ <dd>The lexical representation of the LiteralNodes value.</dd>
+ <dt>readonly attribute DOMString? language</dt>
+ <dd>An optional language string as defined in [[!BCP47]], normalized to lowercase.</dd>
+ <dt>readonly attribute NamedNode? datatype</dt>
+ <dd>An optional datatype identified by a NamedNode.</dd>
+ </dl>
+ </section>
+ </section>
+
</section>
<section>
@@ -1078,7 +1176,7 @@
<ol class="algorithm">
<li>If value is <tref>null</tref>, skip this key/value pair and remove key from <em>value</em></li>
<li>Otherwise, if value is a <tref>JSON object</tref> having either a <code>@value</code>,
- <code>@list</code>, or <code>@set</code> key with a <tref>null</tref> value, skip this key/value pair
+ <code>@list</code>, or <code>@set</code> key with a <tref>null</tref> value, skip this key/value pair.</li>
<li>Otherwise, if <em>value</em> is a <tref>JSON object</tref> having a <code>@set</code> key with a
non-<tref>null</tref> value, replace <em>value</em> with the value of <code>@set</code>.
<li>Otherwise, if the key is <code>@id</code> or <code>@type</code> and the value is a <tref>string</tref>,
@@ -1229,6 +1327,7 @@
</section>
</section>
+</section>
<section>
<h2>Framing</h2>
@@ -1608,75 +1707,29 @@
containing exactly the same information would be normalized to exactly the same form
shown above.</p>
<section>
-<h3>Normalization Algorithm</h3>
-
-<p>The normalization algorithm transforms the <tref>JSON-LD input</tref>
- into RDF, normalizes it according to [[!RDF-NORMALIZATION]] and then
- transforms back to JSON-LD. The result is an object representation that
- deterministically represents a RDF graph.</p>
+ <h3>Normalization Algorithm</h3>
-<ol class="algorithm">
- <li>Transform the <tref>JSON-LD input</tref> to RDF according to the steps in
- the <a href="#rdf-conversion-algorithm">RDF Conversion Algorithm</a>.</li>
- <li>Perform [[!RDF-NORMALIZATION]] of that RDF to create a serialized N-Triples
- representation of the RDF graph.</li>
- <li>Construct a JSON <tref>array</tref> <em>array</em> to serve as the output object.</li>
- <li>For each triple in the N-Triples document having <em>subject</em>, <em>predicate</em>,
- and <em>object</em>:
- <ol class="algorithm">
- <li>If <em>predicate</em> is <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#first</code>,
- let <em>object representation</em> be <em>object</em> represented in expanded
- form as described in <a href="#value-expansion">Value Expansion</a>.
- <ol class="algorithm">
- <li>Set <em>value</em> as the last entry in <em>array</em>.</li>
- <li>If the last entry in <em>value</em> is <em>subject</em>, replace it with
- the a <tref>JSON object</tref> having a key/value pair of <code>@list</code> and an
- <tref>array</tref> containing <em>object representation</em>.</li>
- <li>Otherwise, the last key/value entry in <em>value</em> MUST be a <tref>JSON object</tref>
- having a single key of <code>@list</code> with a value that is an <tref>array</tref>.
- Append <em>object representation</em>.</li>
- </ol>
- </li>
- <li>Otherwise, if <em>predicate</em> is
- <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#rest</code>, ignore this triple.</li>
- <li>Otherwise, if the last entry in <em>array</em> is not a <tref>JSON Object</tref> with an
- <code>@id</code> having a value of <em>subject</em>:
- <ol class="algorithm">
- <li>Create a new <tref>JSON Object</tref> with key/value pair of <code>@id</code> and
- a string representation of <em>subject</em> and use as <em>value</em>.</li>
- <li>Otherwise, set <em>value</em> to that value.</li>
- </ol>
- </li>
- <li>If <code>predicate</code> is <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</code>:
- <ol class="algorithm">
- <li>If <em>value</em> has an key/value pair of <code>@type</code> and an <tref>array</tref>,
- append the string representation of <tref>object</tref> to that array.</li>
- <li>Otherwise, if <em>value</em> has an key of <code>@type</code>, replace that value
- with a new array containing the existing value and a string representation of
- <em>object</em>.</li>
- <li>Otherwise, create a new entry in value with a key of <code>@type</code> and value being a
- string representation of <em>object</em>.</li>
- </ol>
- </li>
- <li>Otherwise, let <em>key</em> by the string representation of <em>predicate</em> and
- let <em>object representation</em> be <em>object</em> represented in expanded
- form as described in <a href="#value-expansion">Value Expansion</a>.</li>
- <li>If <em>value</em> has an key/value pair of <em>key</em> and an <tref>array</tref>,
- append <em>object representation</em> to that array.</li>
- <li>Otherwise, if <em>value</em> has an key of <em>key</em>, replace that value
- with a new array containing the existing value and <em>object representation</em>.</li>
- <li>Otherwise, create a new entry in value with a key of <em>key</em> and
- <em>object representation</em>.</li>
- </ol>
- </li>
- <li>Return <em>array</em> as the normalized graph representation.</li>
-</ol>
+ <p>The normalization algorithm transforms the <tref>JSON-LD input</tref>
+ into RDF, normalizes it according to [[!RDF-NORMALIZATION]] and then
+ transforms back to JSON-LD. The result is an object representation that
+ deterministically represents a RDF graph.</p>
+
+ <ol class="algorithm">
+ <li>Transform the <tref>JSON-LD input</tref> to RDF according to the steps in
+ the <a href="#convert-to-rdf-algorithm">Convert to RDF Algorithm</a>.</li>
+ <li>Perform [[!RDF-NORMALIZATION]] of that RDF to create an array of <a>Triple</a>s
+ representation of the RDF graph.</li>
+ <li>Transform the array of <a>Triple</a>s to a JSON <tref>array</tref> with
+ <tref>JSON Object</tref> definitions using
+ <a href="#convert-from-rdf-algorithm">Convert from RDF Algorithm</a>
+ and return as the normalized form of the
+ <tref>JSON-LD input</tref>.</li>
+ </ol>
</section>
</section>
<section>
-
<h3>Data Round Tripping</h3>
<p>When coercing numbers to <strong>xsd:integer</strong> or <strong>xsd:double</strong>
@@ -1687,7 +1740,6 @@
between the canonical lexical representation and a value in the value space as defined in
[[!XMLSCHEMA-2]]. In other words, every value MUST be converted to a deterministic string
representation.</p>
-<p>
<p>The canonical lexical representation of an <em>integer</em>, i.e., a number without fractions
or a number coerced to <strong>xsd:integer</strong>, is a finite-length sequence of decimal
digits (<code>0-9</code>) with an optional leading minus sign; leading zeroes are prohibited.
@@ -1762,22 +1814,19 @@
<section>
<h2>RDF Conversion</h2>
-<p>A JSON-LD document MAY be converted to any other RDF-compatible document
-format using the algorithm specified in this section.</p>
+<p>A JSON-LD document MAY be converted between other RDF-compatible document
+ formats using the algorithms specified in this section.</p>
-<p>
- The JSON-LD Processing Model describes processing rules for extracting RDF
- from a JSON-LD document. Note that many uses of JSON-LD may not require
- generation of RDF.
-</p>
+<p>The JSON-LD Processing Model describes processing rules for extracting RDF
+ from a JSON-LD document, and for transforming an array of <a>Triple</a> retrieved by processing
+ another serialization format into JSON-LD. Note that many uses of JSON-LD may not require
+ generation of RDF.</p>
-<p>
-The processing algorithm described in this section is provided in
-order to demonstrate how one might implement a JSON-LD to RDF processor.
-Conformant implementations are only required to produce the same type and
-number of triples during the output process and are not required to
-implement the algorithm exactly as described.
-</p>
+<p>The processing algorithms described in this section are provided in
+ order to demonstrate how one might implement a JSON-LD to RDF processor.
+ Conformant implementations are only required to produce the same type and
+ number of triples during the output process and are not required to
+ implement the algorithm exactly as described.</p>
<section class="informative">
<h4>Overview</h4>
@@ -1788,26 +1837,24 @@
</p>
<p>
As with other grammars used for describing <tref>Linked Data</tref>, a key concept is that of
- a <tdef>resource</tdef>. 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,
+ a <tdef>resource</tdef>. Resources may be of three basic types: <a>NamedNode</a>, representing
+ IRIs for describing
+ externally named entities, <a>BlankNode</a>, resources for which an external name does not
+ exist, or is not known, and <a>LiteralNode</a>, 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> <tref>resource</tref>s related via a <tref>property</tref> <tref>resource</tref>.
+ <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> <tref>resource</tref>s related via a
+ <tref>property</tref> <tref>resource</tref>.
However, specific implementations may choose to operate on the document as a normal
- JSON description of objects having attributes.
- </p>
+ JSON description of objects having attributes.</p>
</section>
<section>
@@ -1821,7 +1868,7 @@
</section>
<section>
- <h3>RDF Conversion Algorithm</h3>
+ <h3>Convert to RDF Algorithm</h3>
<p>
The algorithm below is designed for in-memory implementations with random access to <tref>JSON object</tref> elements.
</p>
@@ -1990,6 +2037,76 @@
</li>
</ol>
</section>
+
+<section>
+ <h2>Convert from RDF Algorithm</h2>
+ <p>In some cases, data exists natively in Triples form; for example, if the data was originally
+ represented in an RDF graph or triple store. This algorithm is designed to simply translate
+ an array of triples into a JSON-LD document.</p>
+ <p>The <a href="#normalization-algorithm">Normalization Algorithm</a> also depends on returning
+ an ordered array of <a>Triple</a> objects.</p>
+ <p>The conversion algorithm takes a single parameter <em>input</em> in the form of an
+ array of <a>Triple</a> representations.</p>
+ <ol class="algorithm">
+ <li>Construct a JSON <tref>array</tref> <em>array</em> to serve as the output object.</li>
+ <li>Construct a <tref>JSON object</tref> <em>listMap</em> to contain objects derived from
+ triples having a property of <code>rdf:first</code>.</li>
+ <li>Construct a <tref>JSON object</tref> <em>restMap</em> to map subjects to objects
+ derived from triples having a property of <code>rdf:rest</code>.</li>
+ <li>For each triple in <em>input</em>:
+ <ol class="algorithm">
+ <li>If <em>property</em> is <code>rdf:first</code>,
+ create a new entry in <em>listMap</em> with a key of <em>subject</em> and an array value
+ containing the object representation and skip to the next statement.</li>
+ <li>If <em>property</em> is <code>rdf:rest</code>,
+ and <em>object</em> is a <a>BlankNode</a>,
+ create a new entry in <em>restMap</em> with a key of <em>subject</em> and value being the
+ result of <a href="#iri-expansion">IRI expansion</a> on the object and skip to the next statement.</li>
+ <li>If the last entry in <em>array</em> is not a <tref>JSON Object</tref> with an
+ <code>@id</code> having a value of <em>subject</em>:
+ <ol class="algorithm">
+ <li>Create a new <tref>JSON Object</tref> with key/value pair of <code>@id</code> and
+ a string representation of <em>subject</em> and use as <em>value</em>.</li>
+ </ol>
+ </li>
+ <li>Otherwise, set <em>value</em> to the last entry in <em>array</em>.</li>
+ <li>If <code>property</code> is <code>rdf:type</code>:
+ <ol class="algorithm">
+ <li>If <em>value</em> has an key/value pair of <code>@type</code> and an <tref>array</tref>,
+ append the string representation of <tref>object</tref> to that array.</li>
+ <li>Otherwise, if <em>value</em> has an key of <code>@type</code>, replace that value
+ with a new array containing the existing value and a string representation of
+ <em>object</em>.</li>
+ <li>Otherwise, create a new entry in value with a key of <code>@type</code> and value being a
+ string representation of <em>object</em>.</li>
+ </ol>
+ </li>
+ <li>Otherwise,
+ <ol class="algorithm">
+ <li>Let <em>key</em> be the string representation of <em>property</em> and let
+ <em>object representation</em>
+ be <em>object</em> represented in expanded form as described in
+ <a href="#value-expansion">Value Expansion</a>.</li>
+ <li>If object is <code>rdf:nil</code>, replace
+ <em>object representation</em> with <code>{"@list": []}</code>.</li>
+ <li>If <em>value</em> has an key/value pair of <em>key</em> and an <tref>array</tref>,
+ append <em>object representation</em> to that array.</li>
+ <li>Otherwise, if <em>value</em> has an key of <em>key</em>, replace that value
+ with a new array containing the existing value and <em>object representation</em>.</li>
+ <li>Otherwise, create a new entry in <em>value</em> with a key of <em>key</em> and
+ <em>object representation</em>.</li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ <li>For each key/value <em>prev</em>, <em>rest</em> entry in <em>restMap</em>,
+ append to the <em>listMap</em> value identified
+ by <em>prev</em> the <em>listMap</em> value identified by <em>rest</em>.</li>
+ <li>For each key/value <em>node</em>, <em>list</em>, in <em>listMap</em> where <em>list</em>
+ exists as a value of an object in <em>array</em>,
+ replace the object value with <em>list</em>.</li>
+ <li>Return array as the graph representation.</li>
+ </ol>
</section>
</section>