--- a/spec/latest/json-ld-api/index.html Wed May 23 22:56:57 2012 +0800
+++ b/spec/latest/json-ld-api/index.html Wed May 23 16:56:29 2012 -0700
@@ -68,9 +68,10 @@
ref = ref.replace(/\s+/g, '_') ;
}
var sp = document.createElement( 'a' ) ;
- sp.className = 'datatype';
+ sp.className = 'datatype idlType';
sp.title = ref ;
- sp.innerHTML = con ;
+ sp.setAttribute('href', '#idl-def-' + ref);
+ sp.innerHTML = '<code>' + con + '</code>';
p.replaceChild(sp, item) ;
}
// external datatype references
@@ -658,10 +659,13 @@
</dd>
<dt>void fromRDF()</dt>
- <dd>Creates a JSON-LD document given an set of <a>Statement</a>s.
+ <dd>Creates a JSON-LD document given an set of <ldtref title="quad">Quads</ldtref>.
<dl class="parameters">
- <dt>Statement[] input</dt>
- <dd>An array of RDF statements.</dd>
+ <dt>Quad[] input</dt>
+ <dd>
+ An array of RDF statements.
+ <div class="issue">This could change to <a>RDFDataset</a>.</div>
+ </dd>
<dt>JsonLdCallback callback</dt>
<dd>A callback that is called when processing is complete on
the given <code>input</code>.</dd>
@@ -676,14 +680,17 @@
<dd>
Processes the <code>input</code> according to the
<a href="#convert-to-rdf-algorithm">Convert to RDF Algorithm</a>, calling
- the provided <code>callback</code> for each <a>Statement</a> generated.
+ the provided <code>callback</code> for each <a>Quad</a> generated.
<dl class="parameters">
<dt>object or object[] or URL input</dt>
<dd>The JSON-LD object or array of JSON-LD objects to convert to RDF or an <tref>IRI</tref>
referencing the JSON-LD document to convert to RDF.</dd>
- <dt>StatementCallback callback</dt>
- <dd>A callback that is called when a <a>Statement</a> is created from processing
- the given <code>input</code>.</dd>
+ <dt>QuadCallback callback</dt>
+ <dd>A callback that is called when a <a>Quad</a> is created from processing
+ the given <code>input</code>.
+ <div class="issue">To be more compatible with [[!RDF-CONCEPTS]], this could
+ change to be a single callback of <a>RDFDataset</a>.</div>
+ </dd>
<dt>optional JsonLdOptions options</dt>
<dd>A set of options that MAY affect the conversion to RDF such as, e.g.,
the input document's base <tref>IRI</tref>.</dd>
@@ -730,17 +737,17 @@
</dl>
</section>
<section>
- <h3>StatementCallback</h3>
- <p>The <a>StatementCallback</a> is called whenever the processor generates a
+ <h3>QuadCallback</h3>
+ <p>The <a>QuadCallback</a> is called whenever the processor generates a
statement during the <code>statement()</code> call.</p>
- <dl title="[NoInterfaceObject Callback] interface StatementCallback"
+ <dl title="[NoInterfaceObject Callback] interface QuadCallback"
class="idl">
<dt>void statement()</dt>
<dd>This callback is invoked whenever a statement is generated by the processor.
<dl class="parameters">
- <dt>Statement statement</dt>
+ <dt>Quad statement</dt>
<dd>The statement.</dd>
</dl>
</dd>
@@ -790,28 +797,66 @@
</p>
<section>
- <h3>Statement</h3>
- <p>The <a>Statement</a> interface represents an RDF Statement.</p>
- <dl title="[NoInterfaceObject] interface Statement" class="idl">
+ <h3>RDF Graph</h3>
+ <p><tdef>RDF graph</tdef>, is defined in [[!RDF-CONCEPTS]] as a set of RDF triples.
+ Within the JSON-LD API, this is representing using <a>RDFGraph</a>.</p>
+ <dl title="[NoInterfaceObject] interface RDFGraph" class="idl">
+ <dt>readonly attribute Quad[] statements</dt>
+ <dd>An <a>RDFGraph</a> is represented as an array of <a>Quad</a>, although underlying
+ implementations MAY NOT guarantee statement order.
+ <div class="issue">[[!RDF-CONCEPTS]] uses RDF triple instead of <a>Quad</a>.</div>
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h3>RDF Dataset</h3>
+ <p>An <tdef>RDF Dataset</tdef> defines a single default <tref>RDF Graph</tref> and zero or more
+ named <tref title="RDF graph">RDF Graphs</tref>.</p>
+ <dl title="[NoInterfaceObject] interface RDFDataset" class="idl">
+ <dt>readonly attribute RDFGraph defaultGraph</dt>
+ <dd>The default <tref>RDF Graph</tref></dd>
+ <dt>readonly attribute object namedGraphs</dt>
+ <dd>An object containing <em>name</em>/graph pairs, where <em>name</em> is a
+ <a>node</a> and <em>graph</em> is an <a>RDFGraph</a>.
+ <div class="note">[[!RDF-CONCEPTS]] requires that <em>name</em> by an
+ <ldtref>IRI</ldtref>, JSON-LD allows this to be a <a>BlankNode</a>.</div>
+ <div class="issue">Is there a more IDLish way to do this?.</div>
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h3>Quad</h3>
+ <p>The <a>Quad</a> interface represents an RDF Quad.
+ See [[!RDF-CONCEPTS]] definition for
+ <cite><a href="http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple">RDF triple</a></cite>,
+ which most closely aligns to <a>Quad</a>.
+ <div class="issue">If we use the <a>RDFDataset</a> type, this can
+ revert back to RDF triple.</div>
+ </p>
+ <dl title="[NoInterfaceObject] interface Quad" class="idl">
<dt>readonly attribute Node subject</dt>
- <dd>The subject associated with the <a>Statement</a>.</dd>
+ <dd>The subject associated with the <a>Quad</a>.</dd>
<dt>readonly attribute Node property</dt>
- <dd>The property associated with the <a>Statement</a>.</dd>
+ <dd>The property associated with the <a>Quad</a>.</dd>
<dt>readonly attribute Node object</dt>
- <dd>The object associated with the <a>Statement</a>.</dd>
+ <dd>The object associated with the <a>Quad</a>.</dd>
<dt>readonly attribute Node? name</dt>
- <dd>The name associated with the <a>Statement</a> identifying
+ <dd>The name associated with the <a>Quad</a> identifying
it as a member of a named graph. If the attribute is present,
it indicates that this statement is a member of a <em>named graph</em>
associated with <em>name</em>. If it is missing, the statement
- is a member of the <em>default graph</em>.</dd>
+ is a member of the <em>default graph</em>.
+ <div class="issue">This element is at risk, and may be removed.</div>
+ </dd>
</dl>
</section>
<section>
<h3>Node</h3>
- <p><a>Node</a> is the base class of <a>NamedNode</a>,
- <a>BlankNode</a>, and <a>LiteralNode</a>.</p>
+ <p><a>Node</a> is the base class of <ldtref>IRI</ldtref>,
+ <a>BlankNode</a>, and <ldtref>Literal</ldtref>.</p>
<dl title="[NoInterfaceObject] interface Node" class="idl">
<dt>readonly attribute DOMString nominalValue</dt>
<dd>
@@ -821,18 +866,19 @@
<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>
+ normally one of <code>"IRI"</code>, <code>"BlankNode"</code> or <code>"Literal"</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>
+ are otherwise identical, such as <ldtref>IRI</ldtref> 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"
+ <h3>IRI</h3>
+ <p>A node identified by an <tref>IRI</tref>. IRIs are defined by International
+ Resource Identifier [[!IRI]]. See [[!RDF-CONCEPTS]] definition for
+ <cite><a href="http://www.w3.org/TR/rdf11-concepts/#dfn-iri">IRI</a></cite>.</p>
+ <dl title="[NoInterfaceObject] interface IRI : Node"
class="idl">
<dt>readonly attribute DOMString nominalValue</dt>
<dd>The IRI identifier of the node.</dd>
@@ -843,8 +889,9 @@
<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>Statement</a>
- as a unique reference to that unnamed resource.</p>
+ (one for which an IRI may not be known), and may be used in a <a>Quad</a>
+ as a unique reference to that unnamed node. See [[!RDF-CONCEPTS]] definition for
+ <cite><a href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node">blank node</a></cite>.</p>
<dl title="[NoInterfaceObject] interface BlankNode : Node" class="idl">
<dt>readonly attribute DOMString nominalValue</dt>
@@ -856,45 +903,48 @@
<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
+ most recent processing run on the document. <ldtref title="blanknode">BlankNodes</ldtref>
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,
+ within the current environment, two <ldtref title="blanknode">BlankNodes</ldtref> are considered equal if, and only if,
their nominalValues are strictly equal.</p>
</section>
<section>
- <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:
+ <h3>Literal</h3>
+ <p>Literals represent values such as numbers, dates and strings in
+ RDF data. A <ldtref>Literal</ldtref> 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>
+ <li>an optional <code>datatype</code> specified by an <ldtref>IRI</ldtref></li>
</ul>
- <p>LiteralNodes representing plain text in a natural language may have a
+ <p>Literals 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
+ <p>Literals 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.,
+ of a <a>IRI</a> (e.g.,
<code><http://www.w3.org/2001/XMLSchema#integer></code>).</p>
- <dl title="[NoInterfaceObject] interface LiteralNode : Node" class="idl">
+ <p> See[[!RDF-CONCEPTS]] definition for
+ <cite><a href="http://www.w3.org/TR/rdf11-concepts/#dfn-literal">literal</a></cite>.</p>
+
+ <dl title="[NoInterfaceObject] interface Literal : Node" class="idl">
<dt>readonly attribute DOMString nominalValue</dt>
- <dd>The lexical representation of the LiteralNodes value.</dd>
+ <dd>The lexical representation of the Literals 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>
+ <dt>readonly attribute IRI? datatype</dt>
+ <dd>An optional datatype identified by a IRI.</dd>
</dl>
</section>
</section>
@@ -1296,8 +1346,8 @@
<li>Set the first key-value pair to <code>@value</code> and the unexpanded <em>value</em>.</li>
<li>If the <tref>active property</tref> is the target of typed literal coercion, set the second key-value pair
to <code>@type</code> and the associated coercion datatype expanded according to the
- <a href="#iri-expansion">IRI Expansion</a> rules.
- </li>Otherwise, if the <tref>active property</tref> is the target of language tagging, set the second key-value
+ <a href="#iri-expansion">IRI Expansion</a> rules.</li>
+ <li>Otherwise, if the <tref>active property</tref> is the target of language tagging, set the second key-value
pair to <code>@language</code> and value of the language tagging from the <tref>active context</tref>.</li>
</ol>
</li>
@@ -1307,7 +1357,7 @@
<section>
<h2>Value Compaction</h2>
- <p>Some values, such as IRIs and typed literals, may be expressed in an
+ <p>Some values, such as <tref title="IRI">IRIs</tref> and <tref title="typed literal">typed literals</tref>, may be expressed in an
expanded form in JSON-LD. These values are required to be compacted at
times when processing JSON-LD documents.
</p>
@@ -1328,7 +1378,7 @@
value is the value associated with the <code>@id</code> key,
processed according to the
<a href="#iri-compaction">IRI Compaction</a> steps.</li>
- <li>If the coercion target is a typed literal, the compacted
+ <li>If the coercion target is a <tref>typed literal</tref>, the compacted
value is the value associated with the <code>@value</code> key.</li>
</ol>
</li>
@@ -1880,30 +1930,24 @@
<li>If <em>element</em> is an array, process each entry in <em>element</em> recursively, using this algorithm
and return.</li>
<li>If <em>element</em> is not a <tref>JSON object</tref> or if it has a <code>@value</code> property,
- then if <em>list</em> is not <tref>null</tref>, append <em>element</em> to <em>list</em> and return.
- </li>
+ then if <em>list</em> is not <tref>null</tref>, append <em>element</em> to <em>list</em> and return.</li>
<li>If the <code>@id</code> property exists and is an <tref>IRI</tref>, set <em>id</em> to its value, otherwise
set it to a <tref>blank node</tref> identifer created by the
- <a href="#generate-blank-node-identifier">Generate Blank Node Identifier</a> algorithm.
- </li>
+ <a href="#generate-blank-node-identifier">Generate Blank Node Identifier</a> algorithm.</li>
<li>If <em>list</em> is not <tref>null</tref>, append a new <tref>subject reference</tref> to <em>list</em> using
- <em>id</em> at the value for <code>@id</code>.
- </li>
+ <em>id</em> at the value for <code>@id</code>.</li>
<li>Let <em>subjects</em> be the value in <em>subjectMap</em> where the key is <em>graph</em>; if no such
value exists, insert a new <tref>JSON object</tref> for the key <em>graph</em>. If <em>id</em> is not in
<em>subjects</em>, create a new <tref>JSON object</tref> <em>subject</em> with <em>id</em> as the value
for <code>@id</code>. Let <em>subject</em> be the value of <em>id</em> in <em>subjects</em>.</li>
- </li>
<li>For each <em>property</em> that is not <code>@id</code> and each <em>value</em> in <em>element</em> ordered
by <em>property</em>:
<ol class="algorithm">
<li>If <em>property</em> is <code>@graph</code>, recursively call this algorithm passing <em>value</em>
for <em>element</em>, <em>subjectMap</em>, <tref>null</tref> for <em>list</em> and if <em>graph</em>
- is <code>merged</code> use <em>graph</em>, otherwise use <em>id</em> for <em>graph</em> and then continue.
- </li>
+ is <code>merged</code> use <em>graph</em>, otherwise use <em>id</em> for <em>graph</em> and then continue.</li>
<li>If <em>property</em> is not <code>@type</code> and is a keyword, merge <code>property</code> and
- <code>value</code> into <code>subject</code> and then continue.
- </li>
+ <code>value</code> into <code>subject</code> and then continue.</li>
<li>For each value <em>v</em> in the array <em>value</em>:
<ol class="algorithm">
<li>If <em>v</em> is a <tref>subject definition</tref> or <tref>subject reference</tref>:
@@ -1911,23 +1955,19 @@
<li>If the property <code>@id</code> is not an <tref>IRI</tref> or it does not exist,
map <em>v</em> to a <a href="#generate-blank-node-identifier">new blank node identifier</a>
to avoid collisions. If one does not already exist, add a <tref>subject reference</tref> for
- <em>v</em> into <em>subject</em> for <em>property</em>.
- </li>
+ <em>v</em> into <em>subject</em> for <em>property</em>.</li>
<li>Recursively call this algorithm passing <em>v</em> for <em>value</em>, <em>subjectMap</em>,
- <em>graph</em>, and <tref>null</tref> for <em>list</em>.
- </li>
+ <em>graph</em>, and <tref>null</tref> for <em>list</em>.</li>
</ol>
</li>
<li>Otherwise if <em>v</em> has the property <code>@list</code> then recursively call this algorithm
with the value of <code>@list</code> as <em>element</em>, <em>subjectMap</em>, <em>graph</em>, and
a new array <em>flattenedList</em> as <em>list</em>. Create a new <tref>JSON object</tref> with the
property <code>@list</code> set to <em>flattenedList</em> and add it to <em>subject</em> for
- <em>property</em>.
- </li>
+ <em>property</em>.</li>
<li>Otherwise, if <em>property</em> is <code>@type</code> and <em>v</em> is not an <tref>IRI</tref>,
generate a <a href="#generate-blank-node-identifier">new blank node identifier</a> and add it
- to <em>subject</em> for <em>property</em>.
- </li>
+ to <em>subject</em> for <em>property</em>.</li>
<li>Otherwise, add <em>v</em> to <em>subject</em> for <em>property</em>.</li>
</ol>
</li>
@@ -1937,7 +1977,7 @@
<p>After the above outlined algorithm has been executed, the subject map for all graphs including the default graph are contained in
<em>subjectMap</em>. To also create the subject map for the merged graph, execute the algorithm again, but pass <code>merged</code>
- for <em>graph</em>.
+ for <em>graph</em>.</p>
</section>
@@ -2081,90 +2121,6 @@
</section>
</section>
-</section>
-
-<section>
-<h3>Data Round Tripping</h3>
-
-<p>When coercing numbers to <strong>xsd:integer</strong> or <strong>xsd:double</strong>
- as it, e.g., happens during <a href="#rdf-conversion">RDF Conversion</a>, implementers MUST
- ensure that the result is a canonical lexical representation in the form of a
- <tref>string</tref>. A <tdef>canonical lexical representation</tdef> is a set of literals
- from among the valid set of literals for a datatype such that there is a one-to-one mapping
- 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>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.
- To convert the number in JavaScript, implementers can use the following snippet of code:</p>
-<pre class="example" data-transform="updateExample">
-<!--
-(value).toFixed(0).toString()
--->
-</pre>
-<p>The canonical lexical representation of a <em>double</em>, i.e., a number with fractions
- or a number coerced to <strong>xsd:double</strong>, consists of a mantissa followed by the
- character "E", followed by an exponent. The mantissa MUST be a decimal number. The exponent
- MUST be an integer. Leading zeroes and a preceding plus sign (<code>+</code>) are prohibited
- in the exponent. If the exponent is zero, it must be indicated by <code>E0</code>.
- For the mantissa, the preceding optional plus sign is prohibited and the decimal point is
- required. Leading and trailing zeroes are prohibited subject to the following: number
- representations must be normalized such that there is a single digit which is non-zero to the
- left of the decimal point and at least a single digit to the right of the decimal point unless
- the value being represented is zero. The canonical representation for zero is <code>0.0E0</code>.
- To convert the number in JavaScript, implementers can use the following snippet of code:</p>
-<pre class="example" data-transform="updateExample">
-<!--
-(value).toExponential().replace(/e\+?/,'E')
--->
-</pre>
-<p><strong>xsd:double</strong>'s value space is defined by the IEEE double-precision 64-bit
-floating point type [[!IEEE-754-1985]].</p>
-
-<p class="note">When data such as decimals need to be normalized, JSON-LD authors should
-not use values that are going to undergo automatic conversion. This is due to the lossy nature
-of <strong>xsd:double</strong> values. Authors should instead use the expanded object form to
-set the canonical lexical representation directly.</p>
-
-<p class="note">When JSON-native datatypes, like <tref>number</tref>s, are type coerced, lossless
-data round-tripping can not be guaranted. Consider the following code example:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-var myObj1 = {
- "@context": {
- "number": {
- "@id": "http://example.com/vocab#number",
- ****"@type": "xsd:nonNegativeInteger"****
- }
- },
- "number" : ****42****
- };
-
-// Convert the JSON-LD document to RDF; this converts 42 to a string
-var jsonldText = jsonld.toRDF(myObj1, myRdfTripleCollector);
-
-// Convert the RDF triples back to a JavaScript object
-var myObj2 = jsonld.fromRDF(myRdfTripleCollector.getTriples());
--->
-</pre>
-
-<p>At this point, <code>myObj1</code> and <code>myObj2</code> will have different
- values for the "number" property. <code>myObj1</code> will have the number
- <code>42</code>, while <code>myObj2</code> have an object consisting of
- <code>@value</code> set to the string <code>"42"</code> and <code>@type</code>
- set to the expanded value of <em>xsd:nonNegativeInteger</em>.</p>
-
-<p class="note">Some JSON serializers, such as PHP's native implementation in some versions,
- backslash-escape the forward slash character. For example, the value
- <code>http://example.com/</code> would be serialized as <code>http:\/\/example.com\/</code>.
- This is problematic as other JSON parsers might not understand those escaping characters.
- 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 forward slashes.</p>
-
-</section>
-
<section>
<h2>RDF Conversion</h2>
@@ -2172,7 +2128,7 @@
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, and for transforming an array of <a>Statement</a> retrieved by processing
+ from a JSON-LD document, and for transforming an array of <a>Quad</a> retrieved by processing
another serialization format into JSON-LD. Note that many uses of JSON-LD may not require
generation of RDF.</p>
@@ -2191,10 +2147,10 @@
</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: <a>NamedNode</a>, representing
- IRIs for describing
+ a <tdef>resource</tdef>. Resources may be of three basic types: <ldtref>IRI</ldtref>, representing
+ <tref title="IRI">IRIs</tref> 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,
+ exist, or is not known, and <ldtref>Literal</ldtref>, which describe terminal entities such as strings,
dates and other representations having a lexical representation possibly including
an explicit language or datatype.
</p>
@@ -2210,7 +2166,7 @@
<dl>
<dt><tdef>graph name</tdef></dt>
<dd>
- A <tref>IRI</tref> or <tref>Blank Node</tref> used to identify statements belonging to a
+ A <ldtref>IRI</ldtref> or <ldtref>BlankNode</ldtref> used to identify statements belonging to a
<em>named graph</em>.
</dd>
</dl>
@@ -2223,7 +2179,7 @@
</p>
<p>
A conforming JSON-LD processor implementing RDF conversion MUST implement a
- processing algorithm that results in the same set of RDF <a>Statement</a>s that the following
+ processing algorithm that results in the same set of RDF <ldtref title="quad">Quads</ldtref> that the following
algorithm generates:
</p>
@@ -2271,7 +2227,7 @@
<li>If <tref>active object</tref> is not <tref>null</tref>:
<ol class="algorithm">
<li>If neither <tref>active subject</tref> nor <tref>active property</tref> are <tref>null</tref>,
- generate a <a>Statement</a>
+ generate a <a>Quad</a>
representing <tref>active subject</tref>, <tref>active property</tref>,
<tref>active object</tref>, and <tref>graph name</tref>.</li>
<li>Return <tref>active object</tref>.</li>
@@ -2279,7 +2235,7 @@
</li>
<li id="processing-step-subject">If <em>element</em> has a <code>@id</code> property,
the value MUST be a <tref>string</tref>, set the <tref>active subject</tref> to the previously
- expanded value (either a <tref>blank node</tref> or an <tref>IRI</tref>).</li>
+ expanded value (either a <a>BlankNode</a> or an <ldtref>IRI</ldtref>).</li>
<li>
Otherwise, if <em>element</em> does not have a <code>@id</code> property, set the <tref>active
subject</tref> to newly generated <tref>blank node</tref>.</li>
@@ -2313,10 +2269,10 @@
<tref>active subject</tref>, <tref>active property</tref>, and <tref>graph name</tref>.</li>
<li>Otherwise, if <em>element</em> is a <tref>string</tref>, then the <tref>active property</tref>
- must be <code>rdf:type</code> so set the <tref>active object</tref> to an <tref>IRI</tref>.</li>
+ must be <code>rdf:type</code> so set the <tref>active object</tref> to an <ldtref>IRI</ldtref>.</li>
<li>If any of these steps created an <tref>active object</tref> and neither <tref>active subject</tref>
- nor <tref>active property</tref> are <tref>null</tref>, generate a <a>Statement</a> using
+ nor <tref>active property</tref> are <tref>null</tref>, generate a <a>Quad</a> using
<tref>active subject</tref>,<tref>active property</tref>, <tref>active object</tref> and
<tref>graph name</tref>.
</li>
@@ -2338,27 +2294,27 @@
If <em>array</em> is empty return <code>rdf:nil</code>.
</li>
<li>
- Otherwise, generate a <a>Statement</a> using using the <tref>active subject</tref>, <tref>active property</tref>
- and a newly generated <tref>blank node</tref> identified as <em>first <tref>blank node</tref></em>.
+ Otherwise, generate a <a>Quad</a> using using the <tref>active subject</tref>, <tref>active property</tref>
+ and a newly generated <a>BlankNode</a> identified as <em>first <tref>blank node</tref></em>.
</li>
<li>
For each element in <em>array</em> other than the last element:
<ol class="algorithm">
<li>Create a processor state using
- <em>first <tref>blank node</tref></em> as the <tref>active subject</tref>, and
+ <em>first blank node</em> as the <tref>active subject</tref>, and
<code>rdf:first</code> as the <tref>active property</tref>.
<ol class="algorithm">
<li>Process the value starting at <a href="#processing-step-associative">Step 1</a>.</li>
<li>Proceed using the previous <tref>processor state</tref>.</li>
</ol>
</li>
- <li>Unless this is the last element in <em>array</em>, generate a new <tref>blank node</tref> identified as
- <em>rest <tref>blank node</tref></em>, otherwise use <code>rdf:nil</code>.</li>
- <li>Generate a new <a>Statement</a> using <em>first <tref>blank node</tref></em>,
- <code>rdf:rest</code> and <em>rest <tref>blank node</tref></em>.</li>
- <li>Set <em>first <tref>blank node</tref></em> to
- <em>rest <tref>blank node</tref></em>.</li>
- <li>Return <em>first <tref>blank node</tref></em>.</li>
+ <li>Unless this is the last element in <em>array</em>, generate a new <a>BlankNode</a> identified as
+ <em>rest blank node</em>, otherwise use <code>rdf:nil</code>.</li>
+ <li>Generate a new <a>Quad</a> using <em>first blank node</em>,
+ <code>rdf:rest</code> and <em>rest blank node</em>.</li>
+ <li>Set <em>first blank node</em> to
+ <em>rest blank node</em>.</li>
+ <li>Return <em>first blank node</em>.</li>
</ol>
</li>
</ol>
@@ -2368,9 +2324,9 @@
<h2>Convert from RDF Algorithm</h2>
<p>In some cases, data exists natively in Triples or Quads form; for example, if the data was originally
represented in an RDF graph or triple/quad store. This algorithm is designed to simply translate
- an array of <a>Statement</a>s into a JSON-LD document.</p>
+ an array of <ldtref title="quad">Quads</ldtref> into a JSON-LD document.</p>
<p>The conversion algorithm takes a single parameter <em>input</em> in the form of an
- array of <a>Statement</a> representations.</p>
+ array of <a>Quad</a> representations.</p>
<ol class="algorithm">
<li id="new_graph">Construct <em>defaultGraph</em> as a <tref>JSON object</tref>
containing <em>subjects</em> and <em>listMap</em>,each an empty <tref>JSON object</tref>.</li>
@@ -2472,6 +2428,90 @@
</section>
</section>
+</section>
+
+<section>
+<h3>Data Round Tripping</h3>
+
+<p>When coercing numbers to <strong>xsd:integer</strong> or <strong>xsd:double</strong>
+ as it, e.g., happens during <a href="#rdf-conversion">RDF Conversion</a>, implementers MUST
+ ensure that the result is a canonical lexical representation in the form of a
+ <tref>string</tref>. A <tdef>canonical lexical representation</tdef> is a set of literals
+ from among the valid set of literals for a datatype such that there is a one-to-one mapping
+ 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>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.
+ To convert the number in JavaScript, implementers can use the following snippet of code:</p>
+<pre class="example" data-transform="updateExample">
+<!--
+(value).toFixed(0).toString()
+-->
+</pre>
+<p>The canonical lexical representation of a <em>double</em>, i.e., a number with fractions
+ or a number coerced to <strong>xsd:double</strong>, consists of a mantissa followed by the
+ character "E", followed by an exponent. The mantissa MUST be a decimal number. The exponent
+ MUST be an integer. Leading zeroes and a preceding plus sign (<code>+</code>) are prohibited
+ in the exponent. If the exponent is zero, it must be indicated by <code>E0</code>.
+ For the mantissa, the preceding optional plus sign is prohibited and the decimal point is
+ required. Leading and trailing zeroes are prohibited subject to the following: number
+ representations must be normalized such that there is a single digit which is non-zero to the
+ left of the decimal point and at least a single digit to the right of the decimal point unless
+ the value being represented is zero. The canonical representation for zero is <code>0.0E0</code>.
+ To convert the number in JavaScript, implementers can use the following snippet of code:</p>
+<pre class="example" data-transform="updateExample">
+<!--
+(value).toExponential().replace(/e\+?/,'E')
+-->
+</pre>
+<p><strong>xsd:double</strong>'s value space is defined by the IEEE double-precision 64-bit
+floating point type [[!IEEE-754-1985]].</p>
+
+<p class="note">When data such as decimals need to be normalized, JSON-LD authors should
+not use values that are going to undergo automatic conversion. This is due to the lossy nature
+of <strong>xsd:double</strong> values. Authors should instead use the expanded object form to
+set the canonical lexical representation directly.</p>
+
+<p class="note">When JSON-native datatypes, like <tref>number</tref>s, are type coerced, lossless
+data round-tripping can not be guaranted. Consider the following code example:</p>
+
+<pre class="example" data-transform="updateExample">
+<!--
+var myObj1 = {
+ "@context": {
+ "number": {
+ "@id": "http://example.com/vocab#number",
+ ****"@type": "xsd:nonNegativeInteger"****
+ }
+ },
+ "number" : ****42****
+ };
+
+// Convert the JSON-LD document to RDF; this converts 42 to a string
+var jsonldText = jsonld.toRDF(myObj1, myRdfTripleCollector);
+
+// Convert the RDF triples back to a JavaScript object
+var myObj2 = jsonld.fromRDF(myRdfTripleCollector.getTriples());
+-->
+</pre>
+
+<p>At this point, <code>myObj1</code> and <code>myObj2</code> will have different
+ values for the "number" property. <code>myObj1</code> will have the number
+ <code>42</code>, while <code>myObj2</code> have an object consisting of
+ <code>@value</code> set to the string <code>"42"</code> and <code>@type</code>
+ set to the expanded value of <em>xsd:nonNegativeInteger</em>.</p>
+
+<p class="note">Some JSON serializers, such as PHP's native implementation in some versions,
+ backslash-escape the forward slash character. For example, the value
+ <code>http://example.com/</code> would be serialized as <code>http:\/\/example.com\/</code>.
+ This is problematic as other JSON parsers might not understand those escaping characters.
+ 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 forward slashes.</p>
+
+</section>
+
<section class="appendix informative">
<h1>IANA Considerations</h1>