--- a/spec/latest/json-ld/index.html Wed Aug 07 18:23:35 2013 -0400
+++ b/spec/latest/json-ld/index.html Wed Aug 07 23:58:47 2013 -0400
@@ -13,9 +13,9 @@
doRDFa: "1.1",
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
- specStatus: "ED",
+ specStatus: "CR",
// if you wish the publication date to be other than today, set this
- //publishDate: "2012-12-25",
+ publishDate: "2013-08-22",
copyrightStart: "2010",
// the specification's short name, as in http://www.w3.org/TR/short-name/
@@ -32,8 +32,9 @@
edDraftURI: "http://dvcs.w3.org/hg/json-ld/raw-file/default/spec/latest/json-ld/index.html",
// if this is a LCWD, uncomment and set the end of its review period
- // lcEnd: "2009-08-05",
-
+ lcEnd: "2009-08-05",
+ crEnd: "2013-09-19",
+
issueBase: "https://github.com/json-ld/json-ld.org/issues/",
// atRiskBase: "https://github.com/json-ld/json-ld.org/issues/",
@@ -108,11 +109,11 @@
</section>
<section id="sotd">
- <p>This document has been under development for over 27 months in the
- JSON for Linking Data Community Group. The document has recently been
+ <p>This document has been under development for over 30 months in the
+ JSON for Linking Data Community Group. The document has been
transferred to the RDF Working Group for review, improvement, and publication.
The specification has undergone significant development, review, and changes
- during the course of the last 27 months.</p>
+ during the course of the last 30 months.</p>
<p>There are several independent
<a href="http://json-ld.org/#impl">interoperable implementations</a> of
@@ -168,6 +169,9 @@
<li>Align the JSON-LD Data Model with the RDF Data Model</li>
<li>Support processing of documents with a <code>+json</code> media type as defined in
[[RFC6839]]</li>
+ <li>Added a brief description of the data model to the introduction.</li>
+ <li>Fixed a number of document readability and flow issues related to all
+ of the updates made over the last several moths.</li>
</ul>
</section>
@@ -210,7 +214,7 @@
or RDF Dataset in a JSON-based syntax will find JSON-LD of interest. People
intending to use JSON-LD with RDF tools will find it can be used as another
RDF syntax, like Turtle [[TURTLE]]. Complete details of how JSON-LD relates
- to RDF are in <a href="#relationship-to-rdf"></a>.
+ to RDF are in section <a href="#relationship-to-rdf"></a>.
</p>
<p>
@@ -244,14 +248,14 @@
<p>To understand the basics in this specification you must first be familiar with
JSON, which is detailed in [[!RFC4627]].</p>
-
- <p>This document almost exclusively uses the term IRI
- (<a href="http://www.w3.org/TR/ld-glossary/#internationalized-resource-identifier">Internationalized Resource Indicator</a>)
- when discussing hyperlinks. Many Web developers are more familiar with the
- URL (<a href="http://www.w3.org/TR/ld-glossary/#uniform-resource-locator">Uniform Resource Locator</a>)
- terminology. The document also uses, albeit rarely, the URI
- (<a href="http://www.w3.org/TR/ld-glossary/#uniform-resource-identifier">Uniform Resource Indicator</a>)
- terminology. While these terms are often used interchangeably among
+
+ <p>This document almost exclusively uses the term IRI
+ (<a href="http://www.w3.org/TR/ld-glossary/#internationalized-resource-identifier">Internationalized Resource Indicator</a>)
+ when discussing hyperlinks. Many Web developers are more familiar with the
+ URL (<a href="http://www.w3.org/TR/ld-glossary/#uniform-resource-locator">Uniform Resource Locator</a>)
+ terminology. The document also uses, albeit rarely, the URI
+ (<a href="http://www.w3.org/TR/ld-glossary/#uniform-resource-identifier">Uniform Resource Indicator</a>)
+ terminology. While these terms are often used interchangeably among
technical communities, they do have important distinctions from one
another and the specification goes to great lengths to try and use the
proper terminology at all times.
@@ -281,7 +285,7 @@
<dd>The JSON-LD syntax is very terse and human readable, requiring as
little effort as possible from the developer.</dd>
<dt>Zero Edits, most of the time</dt>
- <dd>JSON-LD ensures a smooth and simple transition from existing
+ <dd>JSON-LD ensures a smooth and simple transition from existing
JSON-based systems. In many cases,
zero edits to the JSON document and the addition of one line to the HTTP response
should suffice (see <a class="sectionRef" href="#interpreting-json-as-json-ld"></a>).
@@ -289,18 +293,18 @@
already deployed large JSON-based infrastructure to use JSON-LD's features
in a way that is not disruptive to their day-to-day operations and is
transparent to their current customers. However, there are times where
- mapping JSON to a graph representation is a complex undertaking.
- In these instances, rather than extending JSON-LD to support
- esoteric use cases, we chose not to support the use case. While Zero
- Edits is a design goal, it is not always possible without adding
- great complexity to the language. JSON-LD focuses on simplicity when
+ mapping JSON to a graph representation is a complex undertaking.
+ In these instances, rather than extending JSON-LD to support
+ esoteric use cases, we chose not to support the use case. While Zero
+ Edits is a design goal, it is not always possible without adding
+ great complexity to the language. JSON-LD focuses on simplicity when
possible.</dd>
<dt>Usable as RDF</dt>
<dd>JSON-LD is usable by developers as
idiomatic JSON, with no need to understand RDF [[RDF11-CONCEPTS]].
JSON-LD is also usable as RDF, so people intending to use JSON-LD
with RDF tools will find it can be used like any other RDF syntax.
- Complete details of how JSON-LD relates to RDF are in
+ Complete details of how JSON-LD relates to RDF are in section
<a href="#relationship-to-rdf"></a>.</dd>
</dl>
</section>
@@ -340,7 +344,7 @@
Values that are used to express one of two possible boolean states.</dd>
<dt><tdef>null</tdef></dt>
<dd>The <tref>null</tref> value, which is typically used to clear or forget
- data. For example, A key-value pair in the
+ data. For example, a key-value pair in the
<code>@context</code> where the value is <tref>null</tref> explicitly
decouples a <tref>term</tref>'s association with an <tref>IRI</tref>.
A key-value pair in the body of a JSON-LD document whose
@@ -351,6 +355,33 @@
</dl>
</section>
+ <section class="informative">
+ <h2>Data Model Overview</h2>
+
+ <p>Generally speaking, the data model used for JSON-LD is a labeled,
+ directed <tref>graph</tref>. The graph contains
+ <tref title="node">nodes</tref>, which are connected by
+ <tref title="edge">edges</tref>. A <tref>node</tref> is typically data
+ such as a <tref>string</tref>, <tref>number</tref>,
+ <tref title="typed value">typed values</tref> (like dates and times)
+ or an <tref>IRI</tref>.
+ There is also a special class of <tref>node</tref> called a
+ <tref>blank node</tref>, which is typically used to express data that does
+ not have a global identifier like an <tref>IRI</tref>.
+ <tref title="blank node">Blank nodes</tref> are identified using a
+ <tref>blank node identifier</tref>. This simple data model is incredibly
+ flexible and powerful, capable of modeling almost any kind of
+ software system. For a deeper explanation of the data model, see
+ section <a href="#data-model"></a>.
+ </p>
+
+ <p>Developers that are familar with Linked Data technologies will
+ recognize the data model as the RDF Data Model. To dive deeper into how
+ JSON-LD and RDF are related, see
+ section <a href="#relationship-to-rdf"></a>.
+ </p>
+ </section>
+
<section class="normative">
<h2>Syntax Tokens and Keywords</h2>
@@ -439,11 +470,13 @@
<section class="informative">
<h1>Basic Concepts</h1>
- <p>JSON [[RFC4627]] is a lightweight, language-independent data-interchange format.
+ <p>JSON [[RFC4627]] is a lightweight, language-independent data interchange format.
It is easy to parse and easy to generate. However, it is difficult to integrate JSON
- from different sources as the data has just local meaning. Furthermore, JSON has no
- built-in support for hyperlinks - a fundamental building block on the Web. Let's look
- at an example that we will be using for the rest of this section:</p>
+ from different sources as the data may contain keys that conflict with other
+ data sources. Furthermore, JSON has no
+ built-in support for hyperlinks, which are a fundamental building block on
+ the Web. Let's start by looking at an example that we will be using for the
+ rest of this section:</p>
<pre class="example" data-transform="updateExample"
title="Sample JSON document">
@@ -456,7 +489,8 @@
-->
</pre>
- <p>It's obvious to humans that the data is about a person whose name is "Manu Sporny"
+ <p>It's obvious to humans that the data is about a person whose
+ <code>name</code> is "Manu Sporny"
and that the <code>homepage</code> property contains the URL of that person's homepage.
A machine doesn't have such an intuitive understanding and sometimes,
even for humans, it is difficult to resolve ambiguities in such representations. This problem
@@ -465,15 +499,16 @@
<p>Linked Data, and the Web in general, uses <tref title="IRI">IRIs</tref>
(Internationalized Resource Identifiers as described in [[!RFC3987]]) for unambiguous
- identification. The idea is to assign <tref title="IRI">IRIs</tref> to something that may
- be of use to other developers and that it is useful to give them an unambiguous identifier.
- That is, it is useful for <tref title="term">terms</tref> to expand to <tref title="IRI">IRIs</tref>
+ identification. The idea is to use <tref title="IRI">IRIs</tref>
+ to assign unambiguous identifiers to data that may be of use to other developers.
+ It is useful for <tref title="term">terms</tref>,
+ like <code>name</code> and <code>homepage</code>, to expand to <tref title="IRI">IRIs</tref>
so that developers don't accidentally step on each other's terms. Furthermore, developers and
machines are able to use this <tref>IRI</tref> (by using a web browser, for instance) to go to
the term and get a definition of what the term means. This process is known as <tref>IRI</tref>
dereferencing.</p>
- <p>Leveraging the well-known <a href="http://schema.org/">schema.org vocabulary</a>,
+ <p>Leveraging the popular <a href="http://schema.org/">schema.org vocabulary</a>,
the example above could be unambiguously expressed as follows:</p>
<pre class="example" data-transform="updateExample"
@@ -497,6 +532,15 @@
<section class="informative">
<h2>The Context</h2>
+ <p>When two people communicate with one another, the conversation takes
+ place in a shared environment, typically called
+ "the context of the conversation". This shared context allows the
+ individuals to use shortcut terms, like the first name of a mutual friend,
+ to communicate more quickly but without losing accuracy. A context in
+ JSON-LD works in the same way. It allows two applications to use shortcut
+ terms to communicate with one another more efficiently, but without
+ losing accuracy.</p>
+
<p>Simply speaking, a <tdef>context</tdef> is used to map <tref title="term">terms</tref> to
<tref title="IRI">IRIs</tref>. <tref title="term">Terms</tref> are case sensitive
and any valid <tref>string</tref> that is not a reserved JSON-LD <tref>keyword</tref>
@@ -518,7 +562,7 @@
},
"homepage": {
"@id": "http://schema.org/url", **** ← This means that 'homepage' is shorthand for 'http://schema.org/url' ****
- "@type": "@id" **** ← This means that the value associated with 'homepage' should be interpreted as an identifier that is an IRI ****
+ "@type": "@id" **** ← This means that the value associated with 'homepage' should be interpreted as an identifier that is an IRI ****
}
}****
}
@@ -577,8 +621,8 @@
as described in <a class="sectionRef" href="#interpreting-json-as-json-ld"></a>. It is also
possible to apply a custom context using the JSON-LD API [[JSON-LD-API]].</p>
- <p>In <tref title="JSON-LD document">JSON-LD documents</tref>
- <tref title="context">contexts</tref> may also be specified in-line.
+ <p>In <tref title="JSON-LD document">JSON-LD documents</tref>,
+ <tref title="context">contexts</tref> may also be specified inline.
This has the advantage that documents can be processed even in the
absence of a connection to the Web. Ultimately, this is a modeling decision
and different use cases may require different handling.</p>
@@ -605,9 +649,9 @@
}
-->
</pre>
-
+
<p>This section only covers the most basic features of the JSON-LD
- Context. More advanced features related to the JSON-LD Context are covered
+ Context. More advanced features related to the JSON-LD Context are covered
in section <a href="#advanced-concepts"></a>.
</p>
</section>
@@ -625,7 +669,7 @@
<em>fragment</em> segments. A <tdef>relative IRI</tdef> is an IRI
that is relative to some other <tref>absolute IRI</tref>.
In JSON-LD all <tref title="relative IRI">relative IRIs</tref> are resolved
- relative to the <tdef>base IRI</tdef> associated with the document.</p>
+ relative to the <tdef>base IRI</tdef>.</p>
<p>A <tref>string</tref> is interpreted as an <tref>IRI</tref> when it is the
value of an <code>@id</code> member:</p>
@@ -647,7 +691,7 @@
<code>http://example.com/about/</code>, the <tref>relative IRI</tref>
<code>../</code> would expand to <code>http://example.com/</code> (for more
information on where <tref title="relative IRI">relative IRIs</tref> can be
- used, please refer to appendix <a href="#json-ld-grammar"></a>).</p>
+ used, please refer to section <a href="#json-ld-grammar"></a>).</p>
<pre class="example" data-transform="updateExample"
title="IRIs can be relative">
@@ -675,9 +719,7 @@
</pre>
<p>In the example above, the key <code>http://schema.org/name</code>
- is interpreted as an <tref>absolute IRI</tref> because it contains a colon
- (<code>:</code>) and it is neither a <tref>compact IRI</tref> nor a
- <tref>blank node identifier</tref>.</p>
+ is interpreted as an <tref>absolute IRI</tref>.</p>
<p>Term-to-IRI expansion occurs if the key matches a <tref>term</tref> defined
within the <tref>active context</tref>:</p>
@@ -725,8 +767,8 @@
<p>In the example above, even though the value <code>http://manu.sporny.org/</code>
is expressed as a JSON <tref>string</tref>, the type <tref>coercion</tref>
- rules will transform the value into an IRI when generating the
- <tref>graph</tref>. See <a class="sectionRef" href="#type-coercion"></a> for more
+ rules will transform the value into an IRI when processing the data.
+ See <a class="sectionRef" href="#type-coercion"></a> for more
details about this feature.</p>
<p>In summary, <tref title="IRI">IRIs</tref> can be expressed in a variety of
@@ -744,10 +786,10 @@
</ol>
<p>This section only covers the most basic features associated with IRIs
- in JSON-LD. More advanced features related to IRIs are covered in
+ in JSON-LD. More advanced features related to IRIs are covered in
section <a href="#advanced-concepts"></a>.
</p>
-
+
</section>
<section class="informative">
@@ -784,8 +826,8 @@
<p>The example above contains a <tref>node object</tref> identified by the IRI
<code>http://me.markus-lanthaler.com/</code>.</p>
- <p>This section only covers the most basic features associated with
- node identifiers in JSON-LD. More advanced features related to
+ <p>This section only covers the most basic features associated with
+ node identifiers in JSON-LD. More advanced features related to
node identifiers are covered in section <a href="#advanced-concepts"></a>.
</p>
@@ -841,8 +883,8 @@
-->
</pre>
-<p>This section only covers the most basic features associated with
-types in JSON-LD. More advanced features related to
+<p>This section only covers the most basic features associated with
+types in JSON-LD. More advanced features related to
types are covered in section <a href="#advanced-concepts"></a>.
</p>