--- a/spec/latest/json-ld-api/index.html Thu Mar 22 20:09:13 2012 +0800
+++ b/spec/latest/json-ld-api/index.html Thu Mar 22 21:59:20 2012 +0800
@@ -812,8 +812,8 @@
<p>The <tref>active context</tref> is used for expanding keys and values of a <tref>JSON object</tref> (or elements
of a list (see <span a="#list-processing">List Processing</span>)) using a <tdef>term mapping</tdef>.
It is also used to maintain
- <tdef>coercion mapping</tdef>s from <tref>IRI</tref>s associated with terms to datatypes,
- <tdef>list mapping</tdef>s, and <tdef>set mapping</tdef>s for IRIs associated with terms.</p>
+ <tdef>coercion mapping</tdef>s from terms to datatypes, <tdef>language mapping</tdef>s from terms to language codes,
+ and <tdef>list mapping</tdef>s and <tdef>set mapping</tdef>s for terms.</p>
<p>A <tref>local context</tref> is identified within a <tref>JSON object</tref> having a key of
<code>@context</code> with <tref>string</tref>, <tref>array</tref> or a <tref>JSON object</tref> value.
When processing a <tref>local context</tref>, special processing rules apply:</p>
@@ -871,6 +871,9 @@
<li>If the value has a <code>@container</code> key, the value MUST be
<code>@list</code> or <code>@set</code>. Merge the <tref>list mapping</tref> or
<tref>set mapping</tref> into the <tref>local context</tref>.</li>
+ <li>If the value has a <code>@language</code> key but no <code>@type</code> key, the value of the
+ <code>@language</code> key MUST be a <tref>string</tref> or <tref>null</tref>.
+ Merge the <tref>language mapping</tref> into the <tref>local context</tref>.</li>
</ol>
</li>
<li>Merge the <tref>local context</tref> into the <tref>active context</tref>.</li>
--- a/spec/latest/json-ld-syntax/index.html Thu Mar 22 20:09:13 2012 +0800
+++ b/spec/latest/json-ld-syntax/index.html Thu Mar 22 21:59:20 2012 +0800
@@ -418,8 +418,8 @@
<a href="#string-internationalization">String Internationalization</a> and
<a href="#typed-values">Typed Values</a>.</dd>
<dt><code>@language</code></dt>
- <dd>Used to specify the native language for a particular value.
- This keyword is described in the section titled
+ <dd>Used to specify the native language for a particular value or the default
+ language of a JSON-LD document. This keyword is described in the section titled
<a href="#string-internationalization">String Internationalization</a>.</dd>
<dt><code>@type</code></dt>
<dd>Used to set the data type of a <tref>subject</tref> or
@@ -948,48 +948,102 @@
</section>
<section>
-<h2>Strings</h2>
+<h2>String Internationalization</h2>
-<p>Regular text strings, also referred to as <tdef>string value</tdef>s, are
-easily expressed using regular JSON <tref>string</tref>s.</p>
+<p>In different scenarios it is important to annotate a <tref>string</tref>
+ with its language. In JSON-LD this is possible in a variety of ways.
+ Firstly, it is possible to define a default language for a JSON-LD document
+ by setting the <code>@language</code> key in the <code>@context</code>:</p>
<pre class="example" data-transform="updateExample">
<!--
{
-...
- "name": "****Mark Birbeck****",
-...
+ ****"@context":
+ {
+ ...
+ "@language": "ja"
+ },****
+ "name": ****"花澄"****,
+ "occupation": ****"科学者"****
}
- -->
+-->
</pre>
-</section>
+<p>The example above would associate the <code>ja</code> language
+ code with the two <tref>string</tref>s <em>花澄</em> and <em>科学者</em>.
+ Languages MUST be expressed in [[!BCP47]] format.</p>
-<section>
-<h2>String Internationalization</h2>
-
-<p>JSON-LD makes an assumption that strings with associated language encoding
-information are not very common when used in JavaScript and Web Services.
-Thus, it takes a little more effort to express strings with associated
-language information.</p>
+<p>It is possible to override the default language by using the expanded
+form of a value:</p>
<pre class="example" data-transform="updateExample">
<!--
{
-...
- "name": ****
- {
- "@value": "花澄",
+ "@context": {
+ ...
"@language": "ja"
+ },
+ "name": "花澄",
+ "occupation": ****{
+ "@value": "Scientist",
+ "@language": "en"
}****
-...
}
-->
</pre>
-<p>The example above would generate a <tref>string value</tref> for
-<em>花澄</em> and associate the <code>ja</code> language code with the triple
-that is generated. Languages MUST be expressed in [[!BCP47]] format.</p>
+<p>It is also possible to override the default language or specify a plain
+value by omitting the <code>@language</code> tag or setting it to
+<code>null</code> when expressing the expanded value:</p>
+
+<pre class="example" data-transform="updateExample">
+<!--
+{
+ "@context": {
+ ...
+ "@language": "ja"
+ },
+ "name": ****{
+ "@value": "花澄"
+ },****
+ "occupation": **** {
+ "@value": "Ninja",
+ "@language": "en"
+ }****,
+ "speciality": "手裏剣"
+}
+-->
+</pre>
+
+<p class="note">Please note that language associations MUST only be applied
+ to plain literal <tref>string</tref>s. That is, <tref>typed value</tref>s
+ or values that are subject to <a href="#type-coercion">type coercion</a>
+ won't be language tagged.</p>
+
+<p>To clear the default language for a subtree, <code>@language</code> can
+be set to <code>null</code> in a <tref>local context</tref> as follows:</p>
+
+<pre class="example" data-transform="updateExample">
+<!--
+{
+ "@context": {
+ ...
+ "@language": "ja"
+ },
+ "name": "花澄",
+ "details": {
+**** "@context": {
+ "@language": null
+ },****
+ "occupation": "Ninja"
+ }
+}
+-->
+</pre>
+
+<p class="note">JSON-LD allows to associate language information with terms.
+ See <a href="#expanded-term-definition">Expanded Term Definition</a> for
+ more details.</p>
</section>
@@ -1522,138 +1576,19 @@
</section>
<section>
-<h3>Default Language</h3>
-
-<p>JSON-LD allows a default value to use as the language for
-<tref>string value</tref>s. It is commonly the case that documents are
-written using a single language. As described in
-<a href="string-internationalization">String Internationalization</a>, a
-language-tagged value MAY be specified as follows:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- ...
- "name":
- ****{
- "@value": "花澄",
- "@language": "ja"
- }****
-}
--->
-</pre>
-
-<p>It is also possible to apply a particular language code to all
-<tref>string value</tref>s by setting the <code>@language</code> key in the
-<code>@context</code>:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- ****"@context":
- {
- ...
- "@language": "ja"
- },****
- "name": ****"花澄"****,
- "occupation": ****"科学者"****
-}
--->
-</pre>
-
-<p>The example above would generate a <tref>string value</tref> for
-<em>花澄</em> and <em>科学者</em> and associate the <code>ja</code> language
-code with each value.</p>
-
-<p>It is possible to override the default language by using the expanded
-form of a value:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "@context":
- {
- ...
- "@language": "ja"
- },
- "name": "花澄",
- "occupation":
- ****{
- "@value": "Scientist",
- "@language": "en"
- }****
-}
--->
-</pre>
+<h3>Expanded Term Definition</h3>
-<p>It is also possible to override the default language and specify a plain
-value by omitting the <code>@language</code> tag when expressing the
-expanded value:</p>
-
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "@context":
- {
- ...
- "@language": "ja"
- },
- "name": "花澄",
- "occupation": ****
- {
- "@value": "Ninja"
- }****
-}
--->
-</pre>
-
-<p>Object <tref title="property">properties</tref> that use the expanded form
-are considered explicitly defined. The <code>@language</code> keyword,
-when used in the <tref>context</tref>, MUST only be applied to
-<tref>string value</tref>s. That is, <tref>string value</tref>s expressed in
-expanded form are not affected by the <code>@language</code> keyword, when
-it is used in the <tref>context</tref>.
-</p>
-
-<p>To clear the default language for a subtree, <code>@language</code> can
-be set to <code>null</code> in a <tref>local context</tref> as follows:</p>
+<p>Within a <tref>context</tref> definition, <tref>term</tref>s MAY be
+ defined using an expanded notation to allow for additional information
+ associated with the term to be specified (see also
+ <a href="#type-coercion">Type Coercion</a> and
+ <a href="#sets-and-lists">Sets and Lists</a>).</p>
-<pre class="example" data-transform="updateExample">
-<!--
-{
- "@context":
- {
- ...
- "@language": "ja"
- },
- "name": "花澄",
- "details":
- {
-**** "@context":
- {
- "@language": null
- },****
- "occupation": "Ninja"
- }
-}
--->
-</pre>
-
-</section>
-
-<section>
- <h3>Expanded Term Definition</h3>
- <p>Within a <tref>context</tref> definition, <tref>term</tref>s MAY be
- defined using an expanded notation to allow for additional information
- associated with the term to be specified (see
- <a href="#type-coerceion">Type Coercion</a> and
- <a href="#sets-and-lists">Sets and Lists</a>).</p>
-
- <p>Instead of using a string representation of an IRI, the IRI MAY be
- specified using an object having an <code>@id</code> key.
- The value of the <code>@id</code> key MUST be either a
- <tref>prefix</tref>:suffix value, an <tref>IRI</tref>. Type information
- may be specified</p>
+<p>Instead of using a string representation of an IRI, the IRI MAY be
+specified using an object having an <code>@id</code> key.
+The value of the <code>@id</code> key MUST be either a
+<tref>prefix</tref>:suffix value, an <tref>IRI</tref>. Type information
+may be specified</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -1672,6 +1607,39 @@
-->
</pre>
+<p>This allows additional information to be associated with the term. This
+ MAY be used for <a href="#type-coercion">Type Coercion</a>,
+ <a href="#sets-and-lists">Sets and Lists</a>), or to associate language
+ information with a term as shown in the following example:</p>
+
+<pre class="example" data-transform="updateExample">
+<!--
+{
+ "@context": {
+ ...
+ "ex": "http://example.com/",
+ "@language": "ja",
+ "name": { "@id": "ex:name", ****"@language": "null"**** },
+ "occupation": { "@id": "ex:occupation" },
+ "occupation_en": { "@id": "ex:occupation", ****"@language": "en"**** },
+ "occupation_de": { "@id": "ex:occupation", ****"@language": "cs"**** }
+ },
+ ****"name": "Yagyū Muneyoshi",
+ "occupation": "忍者",
+ "occupation_en": "Ninja",
+ "occupation_cs": "Nindža",****
+ ...
+}
+-->
+</pre>
+
+<p>The example above would associate <em>忍者</em> with the specified default
+ language code <code>ja</code>, <em>Ninja</em> with the language code
+ <code>en</code>, and <em>Nindža</em> with the language code <code>cs</code>.
+ The value of <code>name</code>, <em>Yagyū Muneyoshi</em> wouldn't be
+ associated with any language code since it was reset in the expanded term
+ definition.</p>
+
</section>
<section>