--- a/spec/latest/json-ld-syntax/index.html Fri Aug 17 18:15:37 2012 +0200
+++ b/spec/latest/json-ld-syntax/index.html Sat Aug 18 14:40:30 2012 -0400
@@ -1212,7 +1212,7 @@
<p>
<tref>Term</tref>s in <tref>Linked Data</tref> documents may draw from
a number of different <tref title="vocabulary">vocabularies</tref>.
- At times, declaring every single term that a document uses can require the
+ At times, declaring every single <tref>term</tref> that a document uses can require the
developer to declare tens, if not hundreds of potential
<tref>vocabulary</tref> <tref>term</tref>s that are used across an
application. This is a concern for at least two reasons: the
@@ -1633,7 +1633,7 @@
<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
+ associated with the <tref>term</tref> to be specified (see also
<a href="#type-coercion"></a> and
<a href="#sets-and-lists"></a>).</p>
@@ -1664,7 +1664,7 @@
<p>This allows additional information to be associated with the term. This
MAY be used for <a href="#type-coercion"></a>,
<a href="#sets-and-lists"></a>), or to associate language
- information with a term as shown in the following example:</p>
+ information with a <tref>term</tref> as shown in the following example:</p>
<pre class="example" data-transform="updateExample"
title="Expanded term definition with language">
@@ -1808,7 +1808,7 @@
</pre>
<p>In this case the <code>@id</code> definition is optional, but if it does exist, the <tref>compact IRI</tref>
- or <tref>IRI</tref> is treated as a term (not a <code>prefix:suffix</code> construct)
+ or <tref>IRI</tref> is treated as a <tref>term</tref> (not a <code>prefix:suffix</code> construct)
so that the actual definition of a <tref>prefix</tref> becomes unnecessary.</p>
<p class="note">Keys in the context are treated as <tref title="term">terms</tref> for the purpose of
@@ -1917,7 +1917,7 @@
In this example, the <tref>compact IRI</tref> form is used in two different
ways.
In the first approach, <code>foaf:age</code> declares both the
-<tref>IRI</tref> for the term (using short-form) as well as the
+<tref>IRI</tref> for the <tref>term</tref> (using short-form) as well as the
<code>@type</code> associated with the <tref>term</tref>. In the second
approach, only the <code>@type</code> associated with the <tref>term</tref> is
specified. The JSON-LD processor will derive the full <tref>IRI</tref> for
@@ -2451,20 +2451,14 @@
<section class="appendix normative">
<h2>JSON-LD Grammar</h2>
-
-<p>This appendix restates the syntactic conventions described in
- previous sections to form a more formal fashion.</p>
-
-<p class="issue" data-number="114">This is an attempt to resolve
- <a href="https://github.com/json-ld/json-ld.org/issues/114#issuecomment-5820544">ISSUE-114</a>.</p>
-
-<p class="note">The JSON-LD context allows <tref title="keyword">keywords</tref> to be
- aliased within the <tref>active context</tref>. Whenever a <tref>keyword</tref> is
- discussed, this is also understood to apply to an alias for that <tref>keyword</tref>
- For example, if the <tref>active context</tref> defines the term <code>id</code> as
- an alias for <code>@id</code>, that alias may be legitimately used as a substitution
- for <code>@id</code>. Note that <tref>keyword</tref> aliases are not expanded during
- context processing.</p>
+<em>This section is normative</em>
+
+<p class="issue" data-number="114">This section is an attempt to formalize
+a normative grammar for JSON-LD.</p>
+
+<p>This appendix restates the syntactic conventions described in the
+ previous sections more formally.</p>
+
<p>A JSON-LD processor SHOULD attempt to process non-conforming
JSON-LD documents. Conformance variations MUST be reported through a
callback mechanism defined in [[!JSON-LD-API]].</p>
@@ -2472,12 +2466,21 @@
<p>The JSON-LD syntax is a subset of the JSON syntax. For a JSON-LD document
to be conforming, it MUST be a valid JSON document as described in
[[!RFC4627]].</p>
+
<p>JSON-LD introduces a number of keywords of the form '<code>@</code>'
followed by a set of one or more lower case alphabetic characters
(<code>@[a-z]+</code>). JSON-LD documents SHOULD NOT define terms beginning
with '<code>@</code>'.
(See <a href="#syntax-tokens-and-keywords"></a> for a complete definition of JSON-LD keywords).</p>
+<p class="note">The JSON-LD context allows <tref title="keyword">keywords</tref> to be
+ aliased within the <tref>active context</tref>. Whenever a <tref>keyword</tref> is
+ discussed, this is also understood to apply to an alias for that <tref>keyword</tref>
+ For example, if the <tref>active context</tref> defines the <tref>term</tref> <code>id</code> as
+ an alias for <code>@id</code>, that alias may be legitimately used as a substitution
+ for <code>@id</code>. Note that <tref>keyword</tref> aliases are not expanded during
+ context processing.</p>
+
<p>A JSON-LD document is either a
a single <tref>subject definition</tref>
or a JSON <tref>array</tref> containing a set of
@@ -2512,8 +2515,9 @@
<section id="grammar-subject-definition">
<h3>Subject Definition</h3>
<p>A <tref>subject definition</tref> is a <tref>JSON object</tref>
- containing one or more key/value pairs. Keys are IRIs, Compact IRIs,
- terms defined within the <tref>active context</tref>, or one of the
+ containing one or more key/value pairs. Keys are <tref>IRI</tref>s,
+ <tref>Compact IRI</tref>s,
+ <tref>term</tref>s defined within the <tref>active context</tref>, or one of the
following keywords:</p>
<ul>
<li><code>@context</code>,</li>
@@ -2527,7 +2531,7 @@
<li>a <tref>string</tref> with the lexical form of <tref>IRI</tref>,</li>
<li>a <tref>JSON object</tref> conforming the the syntax requirements stated
in <a href="#grammar-context"></a>, or</li>
- <li>a <tref>array</tref> composed of any number of the previous two expressions.</li>
+ <li>an <tref>array</tref> composed of any number of the previous two expressions.</li>
</ul>
<pre class="example" data-transform="updateExample"
title="Subject definition with external context">
@@ -2547,8 +2551,9 @@
<p>If the <tref>subject definition</tref> contains the <code>@id</code>
key, it's value
MUST be a <tref>string</tref> having the lexical form of <tref>IRI</tref>,
- <tref>Compact IRI</tref> (Including <tref>unlabeled node</tref>), or a
- term defined in the <tref>active context</tref> expanding into an <tref>IRI</tref> or <tref>unlabeled node</tref>.</p>
+ <tref>Compact IRI</tref> (including <tref>unlabeled node</tref>), or a
+ <tref>term</tref> defined in the <tref>active context</tref> expanding
+ into an <tref>IRI</tref> or an <tref>unlabeled node</tref>.</p>
<pre class="example" data-transform="updateExample"
title="Subject definition with @id">
@@ -2566,14 +2571,14 @@
<p>If the <tref>subject definition</tref> contains the <code>@type</code>
key, it's value
MUST be either a <tref>string</tref> having the lexical form of
- <tref>absolute IRI</tref>, <tref>Compact IRI</tref>, a term defined in the
+ <tref>absolute IRI</tref>, <tref>Compact IRI</tref>, a <tref>term</tref> defined in the
<tref>active context</tref> expanding into an <tref>absolute IRI</tref>,
or an <tref>array</tref> of any of these.</p>
<p class="note">A JSON-LD processor SHOULD process non-conforming documents
- having <code>@type</code> values including <tref title="subject definition">subject definitions</tref> or
- <tref title="subject reference">subject references</tref> entries but MUST
- discard everything but the value of the <code>@id</code> key.</p>
+ having <code>@type</code> values including <tref>subject definition</tref> or
+ <tref>subject reference</tref> entries but MUST
+ discard everything except for the value of the <code>@id</code> key.</p>
<pre class="example" data-transform="updateExample"
title="Subject definition with @type">
@@ -2641,6 +2646,11 @@
<p>Other keys MUST expand to an <tref>absolute IRI</tref> using the
<tref>active context</tref>. The values of these keys may be any
of the following:</p>
+
+<p class="issue">This section is vague. For example, following
+'subject reference' below seems to indicate that {"@id": "http://example.com"}
+is valid. Clearly, it isn't... but perhaps we should tighten up the list below
+a bit?</p>
<ul>
<li><tref>string</tref>,</li>
<li><tref>subject reference</tref>,</li>
@@ -2689,32 +2699,42 @@
<section id="grammar-expanded-values">
<h2>Expanded Values</h2>
-<p>An <tdef>Expanded Value</tdef> is a <tref>JSON object</tref> containing the key
- <code>@value</code> (or alias) and optionally either the <code>@type</code> or
- <code>@language</code> keys (or aliases). An <tref>Expanded Value</tref> MUST NOT
- contain keys other than <code>@value</code>, <code>@language</code> and <code>@type</code>.
- An <tref>Expanded Value</tref> MUST NOT contain both the <code>@language</code> and
- <code>@type</code> keys.</p>
-<p>The value of the <code>@value</code> key (or alias) MUST be either a <tref>string</tref>,
- <tref>number</tref>, <tref>true</tref> or <tref>false</tref>.</p>
-<p>If an <tref>Expanded Value</tref> contains a <code>@language</code> key, it MUST NOT
- contain any other key except <code>@value</code>. The value of the <code>@language</code>
- key MUST have the lexical form described in [[!BCP47]] or <tref>null</tref>.</p>
-<p>If an <tref>Expanded Value</tref> contains a <code>@type</code> key, it MUST NOT
- contain any other key except <code>@value</code>. The value of
- <code>@type</code> MUST be <code>null</code>, a <tref>compact IRI</tref>, an
- <tref>absolute IRI</tref> or a <tref>term</tref> expanding to an
- <tref>absolute IRI</tref>.</p>
+<p>An <tdef>expanded value</tdef> is a <tref>JSON object</tref> containing the
+ <code>@value</code> key, or an alias for the <code>@value</code> value key.
+ It MAY
+ also contain the <code>@type</code> or <code>@language</code> keys, or their
+ respective keyword aliases. An <tref>expanded value</tref> MUST NOT
+ contain keys other than <code>@value</code>, <code>@language</code>, and
+ <code>@type</code>.
+ An <tref>expanded value</tref> MUST NOT contain both the
+ <code>@language</code> and <code>@type</code> keys.</p>
+ <p>The value of the <code>@value</code> key, or its alias, MUST be either a
+ <tref>string</tref>, <tref>number</tref>, <tref>true</tref>, or
+ <tref>false</tref>.</p>
+<p>If an <tref>expanded value</tref> contains a <code>@language</code> key,
+ it MUST NOT contain any other key except <code>@value</code>. The value of
+ the <code>@language</code> key MUST have the lexical form described in
+ [[!BCP47]], or be <tref>null</tref>.</p>
+<p>If an <tref>expanded value</tref> contains a <code>@type</code> key, it
+ MUST NOT contain any other key except <code>@value</code>. The value of
+ <code>@type</code> MUST be a <tref>term</tref>, <tref>compact IRI</tref>,
+ <tref>absolute IRI</tref>, or <code>null</code>.</p>
<p>See <a href="#typed-values"></a> and <a href="#language-values"></a>
- for a further discussion of <tref title="expanded value">Expanded Values</tref>.</p>
+ for a further discussion of
+ <tref title="expanded value">expanded values</tref>.</p>
</section>
<section id="grammar-set-list">
<h2>List and Set Values</h2>
-<p>A <tdef>List</tdef> is a <tref>JSON object</tref> having only the <code>@list</code>
+
+<p class="issue">This definition for lists and sets don't seem to support
+arrays of strings or numbers... or arrays of IRIs. The subject definition
+grammar doesn't seem to support these values.</p>
+
+<p>A <tdef>list</tdef> is a <tref>JSON object</tref> having only the <code>@list</code>
<tref>keyword</tref>. Its value MUST be an <tref>array</tref> of any value type
as defined in <a href="#grammar-subject-definition"></a>.</p>
-<p>A <tdef>Set</tdef> is a <tref>JSON object</tref> having only the <code>@set</code>
+<p>A <tdef>set</tdef> is a <tref>JSON object</tref> having only the <code>@set</code>
<tref>keyword</tref>. Its value MUST be an <tref>array</tref> of any value type
as defined in <a href="#grammar-subject-definition"></a>.</p>
<p>See <a href="#sets-and-lists"></a>
@@ -2730,32 +2750,31 @@
SHOULD NOT contain any keys having the lexical form of <tref>keyword</tref> other than
<code>@language</code> or <code>@vocab</code>.</p>
<p>If the <tref>context definition</tref> has a <code>@language</code> key,
- the value MUST have the lexical form described in [[!BCP47]] or <tref>null</tref>.</p>
+ the value MUST have the lexical form described in [[!BCP47]] or be <tref>null</tref>.</p>
<p>If the <tref>context definition</tref> has a <code>@vocab</code> key,
- the value MUST have the lexical form of <tref>absolute IRI</tref> or <tref>null</tref>.</p>
+ the value MUST have the lexical form of <tref>absolute IRI</tref> or be <tref>null</tref>.</p>
<p>Other keys are <tref>term</tref> definitions. Their values MUST be either a
<tref>string</tref>, or a <tref>JSON object</tref>. If the value is a
<tref>JSON object</tref>, the <tref>term</tref> has an <tdef>expanded term
- definition</tdef> (see <a href="#expanded-term-definition"></a>).</p>
+ definition</tdef> (see <a href="#expanded-term-definition"></a>)
+ <span class="issue">It is not clear what the last sentence is attempting to convey</span>.</p>
<p>An <tref>expanded term definition</tref> is composed of zero or more keys from <code>@id</code>,
<code>@type</code>, <code>@language</code> or <code>@container</code>. An
- <tref>expanded term definition</tref> SHOULD NOT contain any other keys.</p>
-<p>If the <tref>term</tref> does not have the form of <tref>Compact IRI</tref> or <tref>absolute IRI</tref>,
+ <tref>expanded term definition</tref> SHOULD NOT contain any other keys. <span class="issue">SHOULD NOT vs. MUST NOT - it should probably be MUST NOT</span></p>
+<p>If the <tref>term</tref> definition does not have the form of <tref>compact IRI</tref> or <tref>absolute IRI</tref>,
the <tref>JSON object</tref> MUST include the <code>@id</code> <tref>keyword</tref>.</p>
-<p>If the <tref>expanded term definition</tref> contains the <code>@id</code> <tref>keyword</tref>.
+<p>If the <tref>expanded term definition</tref> contains the <code>@id</code> <tref>keyword</tref>,
it MUST be a <tref>string</tref> having the lexical form of <tref>IRI</tref>,
- <tref>Compact IRI</tref>, or a term defined in the defining <tref>context
- definition</tref> or the <tref>active context</tref> expanding into an
- <tref>IRI</tref>.</p>
-<p>If the <tref>expanded term definition</tref> contains the <code>@type</code> <tref>keyword</tref>.
+ <tref>compact IRI</tref>, or a <tref>term</tref> defined in the defining <tref>context
+ definition</tref> or the <tref>active context</tref>.</p>
+<p>If the <tref>expanded term definition</tref> contains the <code>@type</code> <tref>keyword</tref>,
it MUST be a <tref>string</tref> having the lexical form of <tref>absolute IRI</tref>,
- <tref>Compact IRI</tref>, or a term defined in the defining <tref>context
- definition</tref> or the <tref>active context</tref> expanding into an
- <tref>absolute IRI</tref>.</p>
-<p>If the <tref>expanded term definition</tref> contains the <code>@language</code> <tref>keyword</tref>.
- the value MUST have the lexical form described in [[!BCP47]] or <tref>null</tref>.</p>
-<p>If the <tref>expanded term definition</tref> contains the <code>@container</code> <tref>keyword</tref>.
- the value MUST be either <code>@list</code>, <code>@set</code> or <tref>null</tref>.</p>
+ <tref>compact IRI</tref>, or a <tref>term</tref> defined in the defining <tref>context
+ definition</tref> or the <tref>active context</tref>.</p>
+<p>If the <tref>expanded term definition</tref> contains the <code>@language</code> <tref>keyword</tref>,
+ the value MUST have the lexical form described in [[!BCP47]] or be <tref>null</tref>.</p>
+<p>If the <tref>expanded term definition</tref> contains the <code>@container</code> <tref>keyword</tref>,
+ the value MUST be either <code>@list</code>, <code>@set</code> or be <tref>null</tref>.</p>
<p>See <a href="#the-context"></a> and <a href="#expanded-term-definition"></a>
for a further discussion of contexts.</p>
</section>
@@ -2768,7 +2787,7 @@
"foaf": "http://xmlns.com/foaf/0.1/",
"name": "foaf:name",
"depiction": {"@id": "foaf:depiction", "@type": "@id"},
- "modified": {"@id": "http://purl.org/dc/terms/modified", "@type": xsd:dateTime"},
+ "modified": {"@id": "http://purl.org/dc/terms/modified", "@type": "xsd:dateTime"},
"homepage": {"@id": "foaf:homepage", "@type": "@id", "@container": "@list"}
}
-->