--- a/spec/latest/basic/index.html Sat Aug 06 19:08:35 2011 -0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,706 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-<title>JSON-LD Basic - Simple Linked Data Expression in JSON</title>
-<meta http-equiv="content-type" content="text/html; charset=UTF-8">
-<!--
- === NOTA BENE ===
- For the three scripts below, if your spec resides on dev.w3 you can check them
- out in the same tree and use relative links so that they'll work offline,
- -->
-<script type="text/javascript"
- src="http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js" class="remove">
- </script>
-<script type="text/javascript" class="remove">
-
- var preProc = {
- apply: function(c) {
- // extend the bibliography entries
- berjon.biblio["MICRODATA"] = "Ian Hickson; et al. <a href=\"http://www.w3.org/TR/microdata/\"><cite>Microdata</cite></a> 04 March 2010. W3C Working Draft. URL: <a href=\"http://www.w3.org/TR/microdata/\">http://www.w3.org/TR/microdata/</a> ";
- berjon.biblio["HTML-RDFA"] = "Manu Sporny; et al. <a href=\"http://www.w3.org/TR/rdfa-in-html/\"><cite>HTML+RDFa</cite></a> 04 March 2010. W3C Working Draft. URL: <a href=\"http://www.w3.org/TR/rdfa-in-html/\">http://www.w3.org/TR/rdfa-in-html/</a> ";
-
- // process the document before anything else is done
- var refs = document.querySelectorAll('adef') ;
- for (var i = 0; i < refs.length; i++) {
- var item = refs[i];
- var p = item.parentNode ;
- var con = item.innerHTML ;
- var sp = document.createElement( 'dfn' ) ;
- var tit = item.getAttribute('title') ;
- if (!tit) {
- tit = con;
- }
- sp.className = 'adef' ;
- sp.title=tit ;
- sp.innerHTML = con ;
- p.replaceChild(sp, item) ;
- }
- refs = document.querySelectorAll('aref') ;
- for (var i = 0; i < refs.length; i++) {
- var item = refs[i];
- var p = item.parentNode ;
- var con = item.innerHTML ;
- var sp = document.createElement( 'a' ) ;
- sp.className = 'aref' ;
- sp.setAttribute('title', con);
- sp.innerHTML = '@'+con ;
- p.replaceChild(sp, item) ;
- }
- // local datatype references
- refs = document.querySelectorAll('ldtref') ;
- for (var i = 0; i < refs.length; i++) {
- var item = refs[i];
- if (!item) continue ;
- var p = item.parentNode ;
- var con = item.innerHTML ;
- var ref = item.getAttribute('title') ;
- if (!ref) {
- ref = item.textContent ;
- }
- if (ref) {
- ref = ref.replace(/\n/g, '_') ;
- ref = ref.replace(/\s+/g, '_') ;
- }
- var sp = document.createElement( 'a' ) ;
- sp.className = 'datatype';
- sp.title = ref ;
- sp.innerHTML = con ;
- p.replaceChild(sp, item) ;
- }
- // external datatype references
- refs = document.querySelectorAll('dtref') ;
- for (var i = 0; i < refs.length; i++) {
- var item = refs[i];
- if (!item) continue ;
- var p = item.parentNode ;
- var con = item.innerHTML ;
- var ref = item.getAttribute('title') ;
- if (!ref) {
- ref = item.textContent ;
- }
- if (ref) {
- ref = ref.replace(/\n/g, '_') ;
- ref = ref.replace(/\s+/g, '_') ;
- }
- var sp = document.createElement( 'a' ) ;
- sp.className = 'externalDFN';
- sp.title = ref ;
- sp.innerHTML = con ;
- p.replaceChild(sp, item) ;
- }
- // now do terms
- refs = document.querySelectorAll('tdef') ;
- for (var i = 0; i < refs.length; i++) {
- var item = refs[i];
- if (!item) continue ;
- var p = item.parentNode ;
- var con = item.innerHTML ;
- var ref = item.getAttribute('title') ;
- if (!ref) {
- ref = item.textContent ;
- }
- if (ref) {
- ref = ref.replace(/\n/g, '_') ;
- ref = ref.replace(/\s+/g, '_') ;
- }
- var sp = document.createElement( 'dfn' ) ;
- sp.title = ref ;
- sp.innerHTML = con ;
- p.replaceChild(sp, item) ;
- }
- // now term references
- refs = document.querySelectorAll('tref') ;
- for (var i = 0; i < refs.length; i++) {
- var item = refs[i];
- if (!item) continue ;
- var p = item.parentNode ;
- var con = item.innerHTML ;
- var ref = item.getAttribute('title') ;
- if (!ref) {
- ref = item.textContent ;
- }
- if (ref) {
- ref = ref.replace(/\n/g, '_') ;
- ref = ref.replace(/\s+/g, '_') ;
- }
-
- var sp = document.createElement( 'a' ) ;
- var id = item.textContent ;
- sp.className = 'tref' ;
- sp.title = ref ;
- sp.innerHTML = con ;
- p.replaceChild(sp, item) ;
- }
- }
- } ;
-
-
- var respecConfig = {
- // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
- specStatus: "unofficial",
- //publishDate: "2010-04-29",
- //copyrightStart: "2010",
-
- // the specification's short name, as in http://www.w3.org/TR/short-name/
- shortName: "json-ld-basic",
- subtitle: "A Basic Context-based JSON Serialization for Linked Data",
- // if you wish the publication date to be other than today, set this
- // publishDate: "2009-08-06",
-
- // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
- // and its maturity status
- //previousPublishDate: "2011-05-07",
- //previousMaturity: "ED",
- //previousDiffURI: "http://json-ld.org/spec/ED/20100529/index.html",
- diffTool: "http://www.aptest.com/standards/htmldiff/htmldiff.pl",
-
- // if there a publicly available Editor's Draft, this is the link
- edDraftURI: "http://json-ld.org/spec/latest/basic/",
-
- // if this is a LCWD, uncomment and set the end of its review period
- // lcEnd: "2009-08-05",
-
- // if you want to have extra CSS, append them to this list
- // it is recommended that the respec.css stylesheet be kept
- extraCSS: [
- "http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css",
- "spec.css"
- ],
-
- // editors, add as many as you like
- // only "name" is required
- editors: [
- { name: "Manu Sporny", url: "http://digitalbazaar.com/",
- company: "Digital Bazaar, Inc.", companyURL: "http://digitalbazaar.com/" },
- { name: "Gregg Kellogg", url: "http://greggkellogg.net/",
- company: "Kellogg Associates" },
- ],
-
- // authors, add as many as you like.
- // This is optional, uncomment if you have authors as well as editors.
- // only "name" is required. Same format as editors.
-
- authors: [
- { name: "Mark Birbeck", url: "http://webbackplane.com/",
- company: "Backplane Ltd.", companyURL: "http://webbackplane.com/" },
- { name: "Manu Sporny", url: "http://digitalbazaar.com/",
- company: "Digital Bazaar, Inc.", companyURL: "http://digitalbazaar.com/" },
- ],
-
- // name of the WG
- wg: "JSON-LD Community Group",
-
- // URI of the public WG page
- wgURI: "http://json-ld.org/",
-
- // name (with the @w3c.org) of the public mailing to which comments are due
- wgPublicList: "public-linked-json@w3.org",
-
- // URI of the patent status for this WG, for Rec-track documents
- // !!!! IMPORTANT !!!!
- // This is important for Rec-track documents, do not copy a patent URI from a random
- // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
- // Team Contact.
- wgPatentURI: "",
- maxTocLevel: 3,
- preProcess: [ preProc ]
- //alternateFormats: [ {uri: "diff-20110507.html", label: "diff to previous version"} ],
- };
-
- function updateExample(doc, content) {
- // perform transformations to make it render and prettier
- content = content.replace(/<!--/, '');
- content = content.replace(/-->/, '');
- content = doc._esc(content);
- content = content.replace(/\*\*\*\*([^*]*)\*\*\*\*/g, '<span class="diff">$1</span>') ;
- return content ;
- }
-
- function updateDTD(doc, content) {
- // perform transformations to
- // make it render and prettier
- content = '<pre class="dtd">' + doc._esc(content) + '</pre>';
- content = content.replace(/!ENTITY % ([^ \t\r\n]*)/g, '!ENTITY <span class="entity">% $1</span>');
- content = content.replace(/!ELEMENT ([^ \t$]*)/mg, '!ELEMENT <span class="element">$1</span>');
- return content;
- }
-
- function updateSchema(doc, content) {
- // perform transformations to
- // make it render and prettier
- content = '<pre class="dtd">' + doc._esc(content) + '</pre>';
- content = content.replace(/<xs:element\s+name="([^&]*)"/g, '<xs:element name="<span class="element" id="schema_element_$1">$1</span>"') ;
- return content;
- }
-
- function updateTTL(doc, content) {
- // perform transformations to
- // make it render and prettier
- content = '<pre class="sh_sourceCode">' + doc._esc(content) + '</pre>';
- content = content.replace(/@prefix/g, '<span class="sh_keyword">@prefix</span>');
- return content;
- }
- </script>
-<style>
-.diff { font-weight:bold; color:#0a3; }
-</style>
-</head>
-
-<body>
-<section id="abstract">
-<p>
-Developers that embed structured data in their Web pages can choose among
-a number of languages such as RDFa [[RDFA-CORE]], Microformats [[MICROFORMATS]]
-and Microdata [[MICRODATA]]. Each of these structured data languages, while
-incompatible at the syntax level, express Linked Data. JSON has
-proven to be a highly useful object serialization and messaging format.
-In an attempt to harmonize the representation of Linked Data in JSON,
-this specification outlines a common JSON representation format for
-Linked Data that can be used to represent a basic set of objects specified
-via RDFa, Microformats and Microdata.
-</p>
-</section>
-
-<section id='sotd'>
-<p>This document is an experimental work in progress.</p>
-<!-- <p>
-This document has been reviewed by W3C Members, by software
-developers, and by other W3C groups and interested parties, and is
-endorsed by the Director as a W3C Recommendation. It is a stable
-document and may be used as reference material or cited from another
-document. W3C's role in making the Recommendation is to draw attention
-to the specification and to promote its widespread deployment. This
-enhances the functionality and interoperability of the Web.
-</p> -->
-</section>
-
-<section>
-<h1>Introduction</h1>
-
-<p>
-JSON-LD is designed as a light-weight syntax that can be used to express
-Linked Data. It is primarily intended to be a way to express Linked Data
-in Javascript and other Web-based programming environments. It is also
-useful when building interoperable Web Services and when storing Linked
-Data in JSON-based document storage engines. It is practical and designed
-to be as simple as possible, utilizing the large number of JSON parsers
-and existing code that is in use today.
-<p>
-
-<p>
-This document outlines <strong>JSON-LD Basic</strong>, which is a subset
-of <strong>JSON-LD Advanced</strong>. JSON-LD Basic allows developers that do
-not require about more formal ways of modeling data, such as RDF,
-to still create simple Linked Data systems for the Web.
-</p>
-
-
-<p>JSON-LD Basic does not require anyone to change their simple JSON markup, but
-easily add meaning by adding context in a way that is out-of-band. The syntax is
-designed to not disturb already deployed systems running on JSON, but
-provide a smooth migration path from JSON to JSON with added
-semantics. Finally, the format is intended to be fast to parse, fast to
-generate, stream-based and document-based processing compatible, and require
-a very small memory footprint in order to operate.
-</p>
-
-<p>
- JSON, as specified in [[!RFC4627]], is a simple language for representing objects on the web.
- Linked Data is a way of describing content across different documents, or web resources. Web
- resources are described using <tref>IRI</tref>s, and typically are dereferencable entities that may be used
- to find more information, creating a "web of knowledge". JSON-LD is intended to be a simple
- publishing method for expressing Linked Data in JSON.
-</p>
-<section>
-<h2>How to Read this Document</h2>
-
-<p>
-This document is a basic specification for a serialization of JSON for Linked
-data called <strong>JSON-LD Basic</strong>. The document is primarily intended
-for the following audiences:
-</p>
-
-<ul>
- <li>Novice Web developers that want to understand the basic features and
- language syntax for JSON-LD.</li>
- <li>Web developers that want to learn about marking up simple Linked Data
- concepts in JSON.</li>
-</ul>
-
-<p>
-To understand this specification you must first be familiar with JSON,
-which is detailed in [[!RFC4627]].</p>
-</section>
-
-<section>
-<h2>Contributing</h2>
-
-<p>There are a number of ways that one may participate in the development of
-this specification:</p>
-
-<ul>
-<li>All comments and discussion takes place on the public mailing list:
-<a href="http://lists.w3.org/Archives/Public/public-linked-json/">public-linked-json@w3.org</a>
-</li>
-
-<li>Specification bugs and issues should be reported in the
-<a href="https://github.com/json-ld/json-ld.org/issues">issue tracker</a>.</li>
-
-<li><a href="https://github.com/json-ld/json-ld.org/tree/master/spec">Source code</a> for the
-specification can be found on Github.</li>
-
-<li>The <a href="http://webchat.freenode.net/?channels=#json-ld">#json-ld</a>
-IRC channel is available for real-time discussion on irc.freenode.net.</li>
-</ul>
-
-</section>
-
-</section>
-
-<section>
-<h1>Design Goals and Rationale</h1>
-
-<p>The following section outlines the design goals and rationale behind the
-JSON-LD markup language.
-</p>
-
-<section>
-<h2>Goals</h2>
-
-<p>
-A number of design considerations were explored during the creation of this
-markup language:
-</p>
-
-<dl>
- <dt>Simplicity</dt>
- <dd>Most Web Developers don't need to know anything about RDF in order to
- use the basic Linked Data functionality provided by JSON-LD.</dd>
- <dt>JSON Compatibility</dt>
- <dd>The Basic JSON-LD markup should be 100% compatible with JSON.</dd>
- <dt>Upwards Compatibility</dt>
- <dd>The Basic JSON-LD markup should be 100% upward compatible with
- <strong>JSON-LD Advanced</strong>.</dd>
- <dt>Terseness</dt>
- <dd>The JSON-LD syntax must be very terse and human readable.</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
- already deployed large JSON-based infrastructure to add meaning to their
- JSON 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
- Linked Data may become difficult - in these instances, rather than having
- JSON-LD support esoteric markup, we chose not to support the use case and
- support a simplified syntax instead. So, while we strive for Zero Edits,
- it was not always possible without adding great complexity to the language.
- </dd>
-</dl>
-</section>
-
-<section>
-<h2>Mapping Terms to IRIs</h2>
-
-<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 Linked Data,
- IRIs (or URI references) are commonly used for describing entities and properties.
-</p>
-
-<p>Establishing a mechanism to map JSON keys to IRIs helps to establish that
-the keys used in markup are exactly the same between two JSON-LD
-serializations if the IRIs are equivalent.
-</p>
-
-<p>We will be using the following JSON object as the example for this section:
-</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "@context": "http://example.org/contexts/Person",
- "@type": "Person",
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/"
- "avatar": "http://twitter.com/account/profile_image/manusporny"
-}
--->
-</pre>
-</section>
-
-<section>
-<h3>Unambiguous Identifiers for JSON</h3>
-
-<p>If a set of terms, like <strong>Person</strong>,
-<strong>name</strong>, and <strong>homepage</strong>,
-are defined in a context, and that context is used to resolve the
-names in JSON objects, machines could automatically expand the terms to
-something meaningful and unambiguous, like this:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "****http://www.w3.org/1999/02/22-rdf-syntax-ns#type****": "****http://xmlns.com/foaf/0.1/Person****",
- "****http://xmlns.com/foaf/0.1/name****": "Manu Sporny",
- "****http://xmlns.com/foaf/0.1/homepage****": "http://manu.sporny.org"
- "****http://rdfs.org/sioc/ns#avatar****": "http://twitter.com/account/profile_image/manusporny"
-}
- -->
-</pre>
-
-<p>Doing this would mean that JSON would start to become unambiguously
-machine-readable, play well with the semantic web, and basic markup wouldn't
-be that much more complex than basic JSON markup. A win, all around.</p>
-</section>
-
-<section>
-<h3>The JSON-LD Context</h3>
-
-<p>A context is used to allow developers to use aliases for
-<tref>IRI</tref>s. The Linked Data web, just like the document-based web, uses IRIs for
-unambiguous identification. The idea is that these terms mean something,
-which you will eventually want to query. A context allows the expression of a number of
-terms which map directly to <tref>IRI</tref>s. For example, the term <code>name</code>
-may map directly to the IRI <code>http://xmlns.com/foaf/0.1/name</code>. This allows
-JSON-LD documents to be constructed using common JSON syntax of using simple name/value
-pairs.
-</p>
-
-<p>Developers, and machines, would be able to use this IRI (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 WordNet today to
-see the
-<a href="http://wordnetweb.princeton.edu/perl/webwn?s=definition">definition</a>
-of words in the English language. Machines need the same sort of
-dictionary of terms, and IRIs provide a way to ensure that these terms
-are unambiguous.
-</p>
-
-<p>The context provides a collection of vocabulary terms that can be used
-for a JSON object.</p>
-
-<p>Developers can specify which context to use by using the
-<code>@context</code> keyword, like so:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- ****"@context": "http://example.org/contexts/myvocab",****
- "@type": "Person",
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/",
- "avatar": "http://twitter.com/account/profile_image/manusporny"****,
- "personality": "friendly"****
-}
-
--->
-</pre>
-
-<p>The <code>@context</code> keyword is used to change how the JSON-LD
-processor evaluates key-value pairs. In this case, it is used to specify
-that the Vocabulary document specified
-(<code>http://example.org/contexts/myvocab</code>) is to be used to interpret
-the keys in the Linked Data object. In the fictional example above,
-"<code>personality</code>" would
-expand to "<code>http://example.org/myvocab#personality</code>". Any
-Web developer that used the <code>http://example.org/contexts/myvocab</code>
-for their context could expect that the keys in their JSON object mean the
-exact same thing as the keys in another JSON object that uses the
-same <code>@context</code>.</p>
-
-</section>
-
-<section>
-<h3>An Example of a Context</h3>
-
-<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 applications. A JSON-LD
-aware Web Service MAY define a known context. For example, the
-following <tref>default context</tref> could apply to all incoming Web Service
-calls previously accepting only JSON data:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "@context":
- {
- "Person": "http://xmlns.com/foaf/0.1/Person",
- "name": "http://xmlns.com/foaf/0.1/name",
- "homepage": "http://xmlns.com/foaf/0.1/homepage",
- "****personality****": "****http://example.org/myvocab#personality****",
- "@coerce":
- {
- "IRI": ["@type", "homepage"]
- }
- }
-}
--->
-</pre>
-
-<p>The <code>@coerce</code> keyword is used to specify type coercion
-rules for the data. For each key in the map, the key is the type to
-be coerced to and the value is the vocabulary term to be coerced.
-Type coercion for the key <code>IRI</code> asserts that all
-vocabulary terms listed should undergo coercion to an IRI.
-</p>
-
-</section>
-</section>
-
-<section>
-<h2>JSON-LD Basic Keywords</h2>
-
-<p>
-There are four keywords in <strong>JSON-LD Basic</strong>:
-</p>
-
-<dl>
-<dt><code>@context</code></dt><dd>Used to set the <tref>local context</tref>.</dd>
-<dt><code>@coerce</code></dt><dd>Used to specify type coercion rules.</dd>
-<dt><code>@subject</code></dt><dd>Sets the active subject.</dd>
-<dt><code>@type</code></dt><dd>Used to set the rdf:type of the active subjects. This token may be conferred as syntactic sugar for rdf:type.</dd>
-</dl>
-
-<p>
-Each section below explains their syntax and usage.
-</p>
-
-<section>
-<h3>Context</h3>
-<p>
-The context is used to specify the IRIs that JSON keys map to when interpreted
-as Linked Data. If two JSON objects contain the same context, their JSON keys
-are guaranteed to map to the same IRIs. Thus, the JSON objects become
-machine-readable Linked Data objects. In <strong>JSON-LD Basic</strong>, a
-valid context MUST only have one value associated with it and this value MUST
-be a string.
-</p>
-
-<p>An example of correct usage:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- ****"@context": "http://example.org/contexts/myvocab",****
- ...
-}
-
--->
-</pre>
-</section>
-
-<section>
-<h3>Coerce</h3>
-<p>
-At times, it is important for applications to be able to understand when
-a value is an IRI and when a value is just plain text. The <code>@coerce</code>
-keyword can be used to specify the difference between JSON values that are
-IRIs and JSON values that are plain text.
-</p>
-
-<p>An example demonstrating that both the "homepage" and "@type" JSON key-value
-pairs should have their values coerced to an IRI:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "@context":
- {****
- "@coerce":
- {
- "IRI": ["@type", "homepage"]
- }****
- }
-}
--->
-</pre>
-
-</section>
-
-<section>
-<h3>Subject</h3>
-
-<p>
-The subject identifies the item that is being described using an IRI. By using
-an IRI for identification, the developer ensures that the object can be
-referred to by other systems in a way that is universal to the Web. IRIs are always
-evaluated relative to the URI of the document. JSON
-objects identified using IRIs SHOULD ensure that the IRI is dereferenceable in some way so that
-machines can find out more about the resource by dereferencing the link. This
-might be represented as another JSON-LD document containing property
-definitions for that IRI as a <code>@subject</code>.
-</p>
-
-<p>The following example demonstrates the identification of a JSON Linked Data
-object:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "@context": "http://example.org/Person",
- ****"@subject": "http://manu.sporny.org/about#me"****,
- "name": "Manu Sporny"
-}
--->
-</pre>
-
-</section>
-
-<section>
-<h3>Type</h3>
-
-<p>The <code>@type</code> attribute is used to identify the type of a
-particular JSON-LD object. In Object Oriented Programming, this is known as
-the Class of an object.</p>
-
-<p>The following example demonstrates how to specify a type of "Person" for
-the JSON-LD object below:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "@context": "http://example.org/Person",
- "@subject": "http://manu.sporny.org/about#me",
- ****"@type": "Person"****,
- "name": "Manu Sporny"
-}
--->
-</pre>
-
-<p>
-The value(s) of <code>@type</code> may be terms defined in a <code>@context</code>,
-otherwise they are evaluated relative to the URI of the document.
-</p>
-
-<p>
-A JSON-LD object may have more than one type:
-</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "@context": "http://example.org/Person",
- "@subject": "http://manu.sporny.org/about#me",
- ****"@type": ["Person", "Developer"]****,
- "name": "Manu Sporny"
-}
--->
-</pre>
-
-</section>
-
-</section>
-
-<section class="appendix">
-<h1>Acknowledgements</h1>
-
-<p>The editor would like to thank Mark Birbeck, who provided a great deal of the
-rationale and reasoning behind the JSON-LD work via his work on RDFj,
-Dave Longley who reviewed, provided feedback, and performed several
-implementation on the specification, and Ian Davis, who created RDF/JSON.
-Thanks also to Nathan Rixham, Bradley P. Allen and Richard Cyganiak for their
-input on the specification.</p>
-</section>
-
-</body>
-</html>
-
--- a/spec/latest/basic/spec.css Sat Aug 06 19:08:35 2011 -0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,4 +0,0 @@
-ol.algorithm { counter-reset:numsection; list-style-type: none; }
-ol.algorithm li { margin: 0.5em 0; }
-ol.algorithm li:before { font-weight: bold; counter-increment: numsection; content: counters(numsection, ".") ") "; }
-
--- a/spec/latest/index.html Sat Aug 06 19:08:35 2011 -0400
+++ b/spec/latest/index.html Sat Aug 06 19:09:13 2011 -0400
@@ -209,7 +209,7 @@
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
wgPatentURI: "",
- maxTocLevel: 3,
+ maxTocLevel: 2,
preProcess: [ preProc ]
//alternateFormats: [ {uri: "diff-20110507.html", label: "diff to previous version"} ],
};
@@ -250,6 +250,13 @@
</script>
<style>
.diff { font-weight:bold; color:#0a3; }
+ol.algorithm.update { margin-left: 2em; }
+ol.algorithm.update>li { list-style-type: none; }
+ol.algorithm.update>li>span.list-number {
+ display:block;
+ float: left;
+ margin-left: -3.5em;
+}
</style>
</head>
@@ -966,6 +973,11 @@
arrays. If a subject has multiple values for the same property, the author
MAY express each property as an array.</p>
+<p class="note">In JSON-LD, Multiple objects on a property are not ordered. This is because typically graphs
+are not inherently ordered data structures. To see more on creating ordered collections
+in JSON-LD, see <a href="#lists">Lists</a>.
+</p>
+
<pre class="example" data-transform="updateExample">
<!--
{
@@ -1481,13 +1493,14 @@
<section>
<h2>Normalization</h2>
-<p>Normalization is the process of taking a JSON-LD document and performing a
-deterministic transformation on that document that results in a final document
-that any conforming JSON-LD processor would have generated given the same
-input document. The problem is a fairly difficult technical problem to solve
-because it requires a directed graph to be ordered into a set of nodes and
-edges in a deterministic way. This is easy to do when all of the nodes have
-unique names, but very difficult to do when some of the nodes are unlabeled.
+<p>Normalization is the process of taking <tref>JSON-LD input</tref> and
+performing a deterministic transformation on that input that results in a
+<tref>JSON-LD output</tref> that any conforming JSON-LD processor would have
+generated given the same input. The problem is a fairly difficult technical
+problem to solve because it requires a directed graph to be ordered into a
+set of nodes and edges in a deterministic way. This is easy to do when all of
+the nodes have unique names, but very difficult to do when some of the nodes
+are not labeled.
</p>
<p>Normalization is useful when comparing two graphs against one another,
@@ -2108,84 +2121,143 @@
<section>
<h2>Normalization</h2>
-<p class="issue">Needs to be updated.</p>
-<p class="issue">This algorithm is very rough, untested, and probably contains
-many bugs. Use at your own risk. It will change in the coming months.</p>
-
-<p>The JSON-LD normalization algorithm is as follows:</p>
+
+<p class="issue">This algorithm is a work in progress, do not implement it.</p>
+
+<p></p>
+
+<section>
+<h3>Normalization Algorithm Terms</h3>
+ <dl>
+ <dt><tdef>term1</tdef></dt>
+ <dd>
+ definition1
+ </dd>
+</dl>
+</section>
+
+<section>
+<h3>Normalization Algorithm</h3>
<ol class="algorithm">
- <li>Remove the <code>@context</code> key and preserve it as the
- <tdef>transformation map</tdef> while running this algorithm.</li>
- <li>For each key
- <ol class="algorithm">
- <li>If the key is a CURIE, expand the CURIE to an IRI using the
- <tref>transformation map</tref>.</li>
- </ol>
+<li>Expand input (resolve keywords and CURIEs, etc).</li>
+<li>Flatten input (give unique names to unnamed blank nodes, remove embeds, duplicate objects for predicates, etc.).</li>
+<li>Label the unlabeled nodes.</li>
+</ol>
+</section>
+
+<section>
+<h4>Node Labeling Algorithm</h4>
+
+<ol class="algorithm">
+<li>Rename any blank nodes that start with 'c14n' using a temporary prefix.</li>
+<li>Initialize property and reference relation serializations for all blank nodes to null.</li>
+<li>Until all blank nodes are canonically named, keep sorting them according to DeepCompare and naming them according to NameNode.</li>
+</ol>
+</section>
+
+<section>
+<h4>Deep Comparison Algorithm</h4>
+
+<p>
+DeepCompare(bnodeA, bnodeB):
+</p>
+
+<ol class="algorithm">
+ <li>Return the value of ShallowCompare if it is non-zero.</li>
+ <li>Compare property serializations and then reference serializations, recycling the mapping from property serializations for reference serializations.
+ <ol class="algorithm">
+ <li>If the serialization for bnodeA is null, do SerializeNode(bnodeA, new Mapping).</li>
+ <li>If the serialization for bnodeB is null, do SerializeNode(bnodeA, new Mapping).</li>
+ <li>Return the result of a lexicographical comparison of the two serializations.</li>
+ </ol>
+</ol>
+</section>
+
+<section>
+<h4>Node Serialization Algorithm</h4>
+
+<p>
+SerializeNode(bnode, mapping, dir):
+</p>
+
+<ol class="algorithm">
+<li>If the bnode's label is already marked as mapped, return.</li>
+<li>Mark the bnode's label as mapped.</li>
+<li>Assign the next serialization name to the bnode's label and store it in "top".</li>
+<li>Split the bnode's adjacent bnodes into a map and a list. The map contains a reverse mapping of serialization names to bnode labels for all labels in the mapping, the list (notMapped) contains all labels not in the mapping yet.</li>
+<li>Save a copy of the mapping.</li>
+<li>Do SerializeCombos for max(1, notMapped.length) using the original mapping for the first call and a copy of the mapping for each subsequent call.</li>
+</ol>
+
+</section>
+
+<section>
+<h4>Combinatorial Serialization Algorithm</h4>
+
+<p>
+SerializeCombos(top, mapping, mapped, notMapped, dir):
+</p>
+
+<ol class="algorithm">
+ <li>If notMapped is non-empty, copy mapped and assign the next serialization name to its first bnode, remove it from the list, and update mapped.
+ <ol class="algorithm">
+ <li>For max(1, notMapped.length) recurse into SerializeCombos with the original mapping for the first call and a copy of the mapping for each subsequent call. Rotate notMapped on each iteration.</li>
+ </ol>
</li>
- <li>For each value
- <ol class="algorithm">
- <li>If the value should be type coerced per the
- <tref>transformation map</tref>, ensure that it is transformed to the
- new value.</li>
- <li>If the value is a CURIE, expand the CURIE to an IRI using the
- <tref>transformation map</tref>.</li>
- <li>If the value is a <tref>typed literal</tref> and the type is a CURIE,
- expand it to an IRI using the <tref>transformation map</tref>.</li>
- <li>When generating the final value, use expanded object value form to
- store all IRIs, typed literals and <tref>plain literal</tref>s with language
- information.</li>
- </ol>
- </li>
- <li>Output each sorted key-value pair without any extraneous whitespace. If
- the value is an associative array, perform this algorithm, starting
- at step #1, recursively on the sub-tree. There should be no nesting in
- the outputted JSON data. That is, the top-most element should be an
- array. Each item in the array contains a single subject with a
- corresponding array of properties in UTF-8 sort order. Any related
- objects that are complex objects themselves should be given a top-level
- object in the top-level array.</li>
+ <li>If notMapped is empty, save an entry mapping from the bnode's serialization name to the reverse mapping (mapped) and its sorted keys then do SerializeMapping.
+ <ol class="algorithm">
+ <li>If the serialization is lexicographically less than the current serialization or the current serialization is null, then iterate over the sorted keys, get the reverse-mapped adjacent bnode and recursively call SerializeNode on each iteration.</li>
+ <li>Do SerializeMapping then if the serialization is lexicographically less than the current serialization or the current serialization is null, then set it as the least serialization for the bnode in the given edge direction ('property' or 'reference').</li>
+ </ol>
</li>
</ol>
-<p class="issue">Note that normalizing named blank nodes is impossible at
-present since one would have to specify a blank node naming algorithm. For
-the time being, you cannot normalize graphs that contain named blank
-nodes. However, normalizing graphs that contain non-named blank nodes
-is supported.</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-var myObj = { "@context" : {
- "xsd" : "http://www.w3.org/2001/XMLSchema#",
- "name" : "http://xmlns.com/foaf/0.1/name",
- "age" : "http://xmlns.com/foaf/0.1/age",
- "homepage" : "http://xmlns.com/foaf/0.1/homepage",
- "@coerce": {
- "xsd:nonNegativeInteger": "age",
- "xsd:anyURI": "homepage"
- }
- },
- "name" : "Joe Jackson",
- "age" : "42",
- "homepage" : "http://example.org/people/joe" };
-
-// Map the language-native object to JSON-LD
-var jsonldText = jsonld.normalize(myObj);
--->
-</pre>
-
-<p>After the code in the example above has executed, the
-<strong>jsonldText</strong> value will be (line-breaks added for
-readability):</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-[{"http://xmlns.com/foaf/0.1/age":{"@datatype":"http://www.w3.org/2001/XMLSchema#nonNegativeInteger","@literal":"42"},
-"http://xmlns.com/foaf/0.1/homepage":{"@iri":"http://example.org/people/joe"},
-"http://xmlns.com/foaf/0.1/name":"Joe Jackson"}]
--->
-</pre>
+</section>
+
+<section>
+<h4>Mapping Serialization Algorithm</h4>
+
+<p>
+SerializeMapping(mapping):
+(This function incrementally updates the relation serialization for a mapping)
+</p>
+
+<ol class="algorithm">
+ <li>If there is an entry on the mapping's key stack, pop it and iterate over every key.</li>
+ <li>For each key, if an entry for the key hasn't been added to the mapping yet, break out of the loop.</li>
+ <li>Update the key stack entry's index.</li>
+ <li>If the key has already been serialized, output "'_' + key" and continue.</li>
+ <li>For each key, serialize the key then its associated bnode properties, then its bnode references. The entire property list is surrounded by '[' and ']' and so is the reference list. Individual properties/references are seperated by '|'. If a property is an array, all of the serializations are concatenated together with no joining delimiter. The '@subject' property is skipped. The property IRI is turtle-serialized. If a property or reference object is a bnode, it is serialized to '_:', otherwise the turtle serialization is used.</li>
+ <li>Join all of the adjacent keys and add them to the serialization.</li>
+ <li>Push the adjacent keys onto the key stack.</li>
+ <li>Do SerializeMapping.</li>
+</ol>
+
+</section>
+
+<section>
+<h4>Label Generation Algorithm</h4>
+
+<p>
+NameNode(bnode):
+</p>
+
+<ol class="algorithm">
+ <li>Remove the first blank node from the list of sorted blank nodes.</li>
+ <li>Give it the next canonical name.</li>
+ <li>Give canonical names to each blank node key in its property serialization mapping in lexicographical order.</li>
+ <li>Give canonical names to each blank node key in its reference serialization mapping in lexicographical order.</li>
+ <li>Set all serializations containing newly-named blank nodes to null.</li>
+</ol>
+
+</section>
+
+</section>
+
+<section>
+
+<h3>Data Round Tripping</h3>
<p>When normalizing <strong>xsd:double</strong> values, implementers MUST
ensure that the normalized value is a string. In order to generate the
@@ -2237,6 +2309,7 @@
"coerce validation" phase in the parsing/normalization phases would be a
good idea. It would prevent data round-tripping issues like the
one mentioned above.</p>
+
</section>
<section>
@@ -2350,7 +2423,7 @@
Generate a triple representing the <tref>active subject</tref>, the <tref>active
property</tref> and the <tref>active object</tref>. Return the <tref>active object</tref> to the calling location.
</li>
- <li>If the associative array has a <code>@subject</code> key:
+ <li id="processing-step-subject">If the associative array has a <code>@subject</code> key:
<ol class="algorithm">
<li>
If the value is a string, set the <tref>active object</tref> to the result of performing
@@ -2403,31 +2476,7 @@
<ol class="algorithm">
<li>
- If the value is a regular array, generate an RDF List by linking
- each element of the list using <code>rdf:first</code> and <code>rdf:next</code>, terminating the list with <code>rdf:nil</code>
- using the following sequence:
- <ol class="algorithm">
- <li>
- If the list has no element, generate a triple using the <tref>active subject</tref>, <tref>active property</tref>
- and <code>rdf:nil</code>.
- </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>.
- </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>
- </ol>
- </li>
- </ol>
- </li>
- <li>
- Otherwise, create a new <tref>processor state</tref> using copies of the <tref>active
+ Create a new <tref>processor state</tref> using copies of the <tref>active
context</tref>, <tref>active subject</tref> and <tref>active property</tref> and process the value
starting at <a href="#processing-step-associative">Step 2</a> then proceed using the previous
<tref>processor state</tref>.
@@ -2606,6 +2655,149 @@
</section>
<section>
+ <h2>Lists</h2>
+ <p>
+ Because graphs do not describe ordering for links between nodes, multi-valued properties
+ in JSON do not provide an ordering of the listed objects. For example, consider the following
+ simple document:
+ </p>
+ <pre class="example" data-transform="updateExample">
+ <!--
+ {
+ ...
+ "@subject": "http://example.org/people#joebob",
+ "foaf:nick": ****["joe", "bob", "jaybee"]****,
+ ...
+ }
+ -->
+ </pre>
+ <p>
+ This results in three triples being generated, each relating the subject to an individual
+ object, with no inherent order. To address this issue, RDF-based languages, such as [[TURTLE]]
+ use the concept of an <code>rdf:List</code> (as described in [[RDF-SCHEMA]]). This uses a sequence
+ of unlabeled nodes with properties describing a value, a null-terminated next property. Without
+ specific syntactical support, this could be represented in JSON-LD as follows:
+ </p>
+ <pre class="example" data-transform="updateExample">
+ <!--
+ {
+ ...
+ "@subject": "http://example.org/people#joebob",
+ "foaf:nick": ****{****,
+ ****"@first": "joe"****,
+ ****"@rest": {****
+ ****"@first": "bob"****,
+ ****"@rest": {****
+ ****"@first": "jaybee"****,
+ ****"@rest": "@nil"****
+ ****}****
+ ****}****
+ ****}****
+ ****}****,
+ ...
+ }
+ -->
+ </pre>
+ <p>
+ As this notation is rather unwieldy and the notion of ordered collections is rather important
+ in data modeling, it is useful to have specific language support. In JSON-LD, a list may
+ be represented using the <code>@list</code> keyword as follows:
+ </p>
+ <pre class="example" data-transform="updateExample">
+ <!--
+ {
+ ...
+ "@subject": "http://example.org/people#joebob",
+ "foaf:nick": ****{"@list": ["joe", "bob", "jaybee"]}****,
+ ...
+ }
+ -->
+ </pre>
+ <p>
+ This describes the use of this array as being ordered, and order is maintained through
+ normalization and RDF conversion. If every use of a given multi-valued property is a
+ list, this may be abbreviated by adding an <code>@coerce</code> term:
+ </p>
+ <pre class="example" data-transform="updateExample">
+ <!--
+ {
+ ****"@context": {****
+ ...
+ ****"@context": {****
+ ****"@list": ["foaf:nick"]****
+ ****}****
+ ****}****,
+ ...
+ "@subject": "http://example.org/people#joebob",
+ "foaf:nick": ****["joe", "bob", "jaybee"]****,
+ ...
+ }
+ -->
+ </pre>
+ <section><h3 id="list-expansion">Expansion</h3>
+ <p class="issue">TBD.</p>
+ </section>
+ <section><h3 id="list-normalization">Normalization</h3>
+ <p class="issue">TBD.</p>
+ </section>
+ <section><h3 id="list-rdf">RDF Conversion</h3>
+ <p>
+ To support RDF Conversion of lists, <a href="#rdf-conversion-algorithm">RDF Conversion Algorithm</a>
+ is updated as follows:
+ </p>
+ <ol class="algorithm update">
+ <li>
+ <span class="list-number">2.2.4a.</span>
+ If the associative array has a <code>@list</code> key and the value is an array
+ process the value as a list starting at <a href="#processing-step-list">Step 3a</a>.
+ </li>
+ <li>
+ <span class="list-number">2.9.3.</span>
+ Create a new <tref>processor state</tref> copies of the <tref>active context</tref>,
+ <tref>active subject</tref> and <tref>active property</tref>.
+ <ol class="algorithm">
+ <li>
+ If the <tref>active property</tref> is the target of a <code>@list</code> coercion,
+ and the value is an array,
+ process the value as a list starting at <a href="#processing-step-list">Step 3a</a>.
+ </li>
+ <li>
+ Otherwise, process the value starting at
+ <a href="#processing-step-associative">Step 2</a>.
+ </li>
+ <li>Proceed using the previous <tref>processor state</tref>.</li>
+ </ol>
+ </li>
+ <li id="processing-step-list">
+ <span class="list-number">3a.</span>
+ Generate an RDF List by linking
+ each element of the list using <code>rdf:first</code> and <code>rdf:next</code>, terminating the list with <code>rdf:nil</code>
+ using the following sequence:
+ <ol class="algorithm">
+ <li>
+ If the list has no element, generate a triple using the <tref>active subject</tref>, <tref>active property</tref>
+ and <code>rdf:nil</code>.
+ </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>.
+ </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>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ </ol>
+ </section>
+</section>
+
+<section>
<h2>The JSON-LD API</h2>
<p>This API provides a clean mechanism that enables developers to convert