Editorial issues

common/terms.html

@@ -112,6 +112,16 @@
     Whenever possible, an <a>edge</a> should be labeled with an <a>IRI</a>.
     <div class="issue atrisk">The use of <a>blank node identifiers</a> to label properties is obsolete,
       and may be removed in a future version of JSON-LD.</div></dd>
+  <dt><dfn>embedded context</dfn></dt><dd>
+    An embedded <a>context</a> is a <a>dictionary</a> composed of a combintation of
+    <a>term definitions</a>, a <a>vocabulary mapping</a>, a <a>base IRI</a> and <a>default language</a>.
+    An <a>embedded context</a> may appear as part of a <a>node object</a> or <a>value object</a> using the
+    <code>@context</code> <a>member</a>.
+  </dd>
+  <dt><dfn>scoped context</dfn></dt><dd>
+    A <a>scoped context</a> is part of an <a>expanded term definition</a> using the
+    <code>@context</code> <a>member</a>. It has the same form as an <a>embedded context</a>.
+  </dd>
   <dt><dfn>expanded term definition</dfn></dt><dd>
     An expanded term definition is a <a>term definition</a>
     where the value is a <a>dictionary</a>
@@ -212,7 +222,8 @@
     A <a>list</a> is an ordered sequence of <a>IRIs</a>, <a>blank nodes</a>, and <a>JSON-LD values</a>.
     See <dfn data-cite="RDF-SCHEMA#ch_collectionvocab" data-lt="collection" class="preserve">RDF collection</dfn> in [[RDF-SCHEMA]].</dd>
   <dt><dfn>list object</dfn></dt><dd>
-    A <a>list object</a> is a <a>dictionary</a> that has a <code>@list</code> key.</dd>
+    A <a>list object</a> is a <a>dictionary</a> that has a <code>@list</code> key.
+    It may also have an <a>@index</a> key, but no other members.</dd>
   <dt><dfn>literal</dfn></dt><dd>
     An <a>object</a> expressed as a value such as a string, number or in expanded form.</dd>
   <dt><dfn>local context</dfn></dt><dd>
@@ -294,7 +305,8 @@
     are resolved relative to the <a>vocabulary mapping</a>,
     not the <a>base IRI</a>.</dd>
   <dt><dfn>set object</dfn></dt><dd>
-    A <a>set object</a> is a <a>dictionary</a> that has an <code>@set</code> <a>member</a>.</dd>
+    A <a>set object</a> is a <a>dictionary</a> that has an <code>@set</code> <a>member</a>.
+    It may also have an <a>@index</a> key, but no other members.</dd>
   <dt><dfn>subject</dfn></dt><dd>
     A <a data-cite="RDF11-CONCEPTS#dfn-subject" class="externalDFN">subject</a>
     is a <a>node</a> in a <a>linked data graph</a>

index.html

@@ -569,11 +569,6 @@ <h2>Syntax Tokens and Keywords</h2>
 </section>
 
 <section id="conformance">
-  <p>Conformance criteria are relevant to authors and authoring tool implementers. As well
-    as sections marked as non-normative, all authoring guidelines, diagrams, examples,
-    and notes in this specification are non-normative. Everything else in this
-    specification is normative.</p>
-
   <p>A <a>JSON-LD document</a> complies with this specification if it follows
     the normative statements in appendix <a href="#json-ld-grammar"></a>. JSON documents
     can be interpreted as JSON-LD by following the normative statements in
@@ -687,8 +682,13 @@ <h1>Basic Concepts</h1>
     <!--
     {
       "****http://schema.org/name****": "Manu Sporny",
-      "****http://schema.org/url****": ****{ "@id": ****"http://manu.sporny.org/" ****}****,  ####← The '@id' keyword means 'This value is an identifier that is an IRI'####
-      "****http://schema.org/image****": ****{ "@id": ****"http://manu.sporny.org/images/manu.png" ****}****
+      "****http://schema.org/url****": ****{
+        "@id": ****"http://manu.sporny.org/"
+        ####↑ The '@id' keyword means 'This value is an identifier that is an IRI'####
+      ****}****,
+      "****http://schema.org/image****": ****{
+        "@id": ****"http://manu.sporny.org/images/manu.png"
+      ****}****
     }
     -->
     </pre>
@@ -758,14 +758,21 @@ <h2>The Context</h2>
     <!--
     {
       ****"@context": {
-        "name": "http://schema.org/name",****  ####← This means that 'name' is shorthand for 'http://schema.org/name'#### ****
-        "image": {
-          "@id": "http://schema.org/image",****  ####← This means that 'image' is shorthand for 'http://schema.org/image'#### ****
-          "@type": "@id"****  ####← This means that a string value associated with 'image' should be interpreted as an identifier that is an IRI#### ****
-        },
+        "name": "http://schema.org/name",****
+        ####↑ This means that 'name' is shorthand for 'http://schema.org/name'####
+        ****"image": {
+          "@id": "http://schema.org/image",**** 
+          ####↑ This means that 'image' is shorthand for 'http://schema.org/image'####
+          ****"@type": "@id"****
+          ####↑ This means that a string value associated with 'image'
+            should be interpreted as an identifier that is an IRI####
+        ****},
         "homepage": {
-          "@id": "http://schema.org/url",****  ####← This means that 'homepage' is shorthand for 'http://schema.org/url'#### ****
-          "@type": "@id"****  ####← This means that a string value associated with 'homepage' should be interpreted as an identifier that is an IRI#### ****
+          "@id": "http://schema.org/url",****
+          ####↑ This means that 'homepage' is shorthand for 'http://schema.org/url'####
+          ****"@type": "@id"****
+          ####↑ This means that a string value associated with 'homepage'
+            should be interpreted as an identifier that is an IRI#### ****
         }
       }****
     }
@@ -776,6 +783,9 @@ <h2>The Context</h2>
       either be a simple string, mapping the <a>term</a> to an <a>IRI</a>,
       or a <a>dictionary</a>.</p>
 
+    <p>A <a>context</a> is introduced using a <a>member</a> with the key <code>@context</code> and may
+      appear within a <a>node object</a> or a <a>value object</a>.</p>
+
     <p>When a <a>member</a> with a <a>term</a> key has a <a>dictionary</a> value, the <a>dictionary</a> is called
       an <a>expanded term definition</a>. The example above specifies that
       the values of <code>image</code> and <code>homepage</code>, if they are
@@ -791,7 +801,8 @@ <h2>The Context</h2>
       <a data-lt="absolute IRI">absolute</a> or <a>compact IRI</a>.</p>
 
     <p><a>Contexts</a> can either be directly embedded
-      into the document or be referenced. Assuming the context document in the previous
+      into the document (an <a>embedded context</a>) or be referenced using a URL.
+      Assuming the context document in the previous
       example can be retrieved at <code>https://json-ld.org/contexts/person.jsonld</code>,
       it can be referenced by adding a single line and allows a JSON-LD document to
       be expressed much more concisely as shown in the example below:</p>
@@ -969,14 +980,22 @@ <h2>IRIs</h2>
     In JSON-LD, with exceptions are as described below, all <a>relative IRIs</a>
     are resolved relative to the <a>base IRI</a>.</p>
 
+  <p class="note">As noted in <a href="#how-to-read-this-document" class="sectionRef"></a>,
+    IRIs can often be confused with URLs (<a data-cite="ld-glossary#uniform-resource-locator">Uniform Resource Locators</a>),
+    the primary distinction is that a URL <em>locates</em> a resource on the web,
+    an IRI <em>identifies</em> a resource. While it is a good practice for resource identifiers
+    to be dereferencable, sometimes this is not practical. In particular, note the
+    [[URN]] scheme for Uniform Resource Names, such as <a data-cite="rfc4122">UUID</a>.
+    An example UUID is <code>urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6</code>.</p>
+
   <p class="note"><a>Properties</a>, values of <code>@type</code>,
     and values of <a>properties</a> with a <a>term definition</a>
     that defines them as being relative to the <a>vocabulary mapping</a>,
     may have the form of a <a>relative IRI</a>, but are resolved using the
     <a>vocabulary mapping</a>, and not the <a>base IRI</a>.</p>
 
   <p>A <a>string</a> is interpreted as an <a>IRI</a> when it is the
-    value of an <a>dictionary member</a> with the key<code>@id</code>:</p>
+    value of an <a>dictionary member</a> with the key <code>@id</code>:</p>
 
   <pre class="example nohighlight" data-transform="updateExample"
        title="Values of @id are interpreted as IRI">
@@ -1524,10 +1543,10 @@ <h2>Specifying the Type</h2>
     to create a <a>typed value</a>.
     This use of <code>@type</code> is similar to that used to define the type of a <a>node object</a>,
     but value objects are restricted to having just a single type.
-    The use of @type to create typed values is discussed more fully in <a class="sectionRef" href="#typed-values"></a>.</p>
+    The use of <code>@type</code> to create typed values is discussed more fully in <a class="sectionRef" href="#typed-values"></a>.</p>
 
   <p class="changed">Typed values can also be defined implicitly, by specifying
-    @type in an expanded term definition.
+    <code>@type</code> in an expanded term definition.
     This is covered more fully in <a class="sectionRef" href="#type-coercion"></a>.</p>
 
   <p class="note">The ability coerce a value using a <a>term definition</a> is distinct
@@ -1847,7 +1866,7 @@ <h1>Advanced Concepts</h1>
     most-recently-defined-wins mechanism.</p>
 
   <aside class="example ds-selector-tabs"
-         title="Scoped contexts within node objects">
+         title="Embedded contexts within node objects">
     <div class="selectors">
       <button class="selected" data-selects="original">Original</button>
       <button data-selects="expanded">Expanded</button>
@@ -1874,7 +1893,7 @@ <h1>Advanced Concepts</h1>
     -->
     </pre>
     <pre class="expanded nohighlight" data-transform="updateExample"
-         data-result-for="Scoped contexts within node objects-original">
+         data-result-for="Embedded contexts within node objects-original">
     <!--
     [{
       "http://example.com/person#details": [{
@@ -1887,7 +1906,7 @@ <h1>Advanced Concepts</h1>
     -->
     </pre>
     <table class="statements"
-           data-result-for="Scoped contexts within node objects-expanded"
+           data-result-for="Embedded contexts within node objects-expanded"
            data-to-rdf>
       <thead><tr><th>Subject</th><th>Property</th><th>Value</th></tr></thead>
       <tbody>
@@ -1898,7 +1917,7 @@ <h1>Advanced Concepts</h1>
     </table>
     <pre class="turtle"
          data-content-type="text/turtle"
-         data-result-for="Scoped contexts within node objects-expanded"
+         data-result-for="Embedded contexts within node objects-expanded"
          data-transform="updateExample"
          data-to-rdf>
     <!--
@@ -1933,7 +1952,7 @@ <h1>Advanced Concepts</h1>
     to an empty context, without <a>term definitions</a>, <a>default language</a>,
     or other things defined within previous contexts.
     The following example specifies an external context
-    and then layers an embedded context on top of the external context:</p>
+    and then layers an <a>embedded context</a> on top of the external context:</p>
 
   <aside class="example ds-selector-tabs"
          title="Combining external and local contexts">
@@ -2731,7 +2750,7 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
   <p class="changed">When <a>processing mode</a> is set to <code>json-ld-1.1</code>,
     <code>@type</code> may be used with an <a>expanded term definition</a> with <code>@container</code> set
     to <code>@set</code>; no other members may be set within such an <a>expanded term definition</a>.
-    This is used by the <a data-cite="JSON-LD11-API#compaction-algorithm">Compaction algorithm</a> to ensure that the values of @type (or an alias)
+    This is used by the <a data-cite="JSON-LD11-API#compaction-algorithm">Compaction algorithm</a> to ensure that the values of <code>@type</code> (or an alias)
     are always represented in an <a>array</a>.</p>
 
   <pre class="example" data-transform="updateExample" title="Setting @container: @set on @type">
@@ -2910,7 +2929,7 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
 <section class="informative changed"><h2>Scoped Contexts</h2>
 
   <p>An <a>expanded term definition</a> can include a <code>@context</code>
-    property, which defines a <a>context</a> (an <dfn>embedded context</dfn>) for
+    property, which defines a <a>context</a> (an <a>scoped context</a>) for
     <a data-lt="JSON-LD value">values</a> of properties defined using that <a>term</a>. This allows
     values to use <a>term definitions</a>, <a>base IRI</a>,
     <a>vocabulary mapping</a> or <a>default language</a> which is different from the
@@ -2993,7 +3012,7 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
 
   <p>In this case, the social profile is defined using the schema.org vocabulary, but interest is imported from FOAF, and is used to define a node describing one of Manu's interests where those properties now come from the FOAF vocabulary.</p>
 
-  <p>Expanding this document, uses a combination of terms defined in the outer context, and those defined specifically for that term in an <a>embedded context</a>.</p>
+  <p>Expanding this document, uses a combination of terms defined in the outer context, and those defined specifically for that term in an <a>scoped context</a>.</p>
 
   <p>Scoping can also be performed using a term used as a value of <code>@type</code>:</p>
 
@@ -3090,25 +3109,26 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
 
   <p>When expanding, each value of <code>@type</code> is considered
     (ordering them lexographically) where that value is also a <a>term</a> in
-    the <a>active context</a> having its own <a>embedded context</a>. If so, that
-    <a>embedded context</a> is applied to the <a>active context</a>. When compacting, if
+    the <a>active context</a> having its own <a>scoped context</a>. If so, that
+    <a>scoped context</a> is applied to the <a>active context</a>. When compacting, if
     a <a>term</a> is chosen to represent an IRI used as a value of <code>@type</code> where that
-    <a>term definition</a> also has an <a>embedded context</a>, it is then applied to the
+    <a>term definition</a> also has an <a>scoped context</a>, it is then applied to the
     <a>active context</a> to affect further compaction.</p>
 
   <p class="note">The values of <code>@type</code> are unordered, so if multiple
-    types are listed, the order that scoped contexts are applied is based on
+    types are listed, the order that <a>scoped contexts</a> are applied is based on
     lexicographical ordering.</p>
 
-  <p class="note">If a <a>term</a> defines a scoped context, and then that term
-    is later re-defined, the association of the context defined in the earlier
+  <p class="note">If a <a>term</a> defines a <a>scoped context</a>,
+    and then that term is later re-defined,
+    the association of the context defined in the earlier
     <a>expanded term definition</a> is lost
     within the scope of that re-definition. This is consistent with
     <a>term definitions</a> of a term overriding previous term definitions from
     earlier less deeply nested definitions, as discussed in
     <a href="#advanced-context-usage" class="sectionRef"></a>.</p>
 
-  <p class="note">Scoped Contexts are a new feature in JSON-LD 1.1, requiring
+  <p class="note"><a>Scoped Contexts</a> are a new feature in JSON-LD 1.1, requiring
     <a>processing mode</a> set to <code>json-ld-1.1</code>.</p>
 </section>
 
@@ -9853,11 +9873,11 @@ <h2>Lists and Sets</h2>
 
     <p>A <a>list object</a> MUST be a <a>dictionary</a> that contains no
       keys that expand to an <a>absolute IRI</a> or <a>keyword</a> other
-      than <code>@list</code>, <code>@context</code>, and <code>@index</code>.</p>
+      than <code>@list</code> and <code>@index</code>.</p>
 
     <p>A <a>set object</a> MUST be a <a>dictionary</a> that contains no
       keys that expand to an <a>absolute IRI</a> or <a>keyword</a> other
-      than <code>@set</code>, <code>@context</code>, and <code>@index</code>.
+      than <code>@set</code> and <code>@index</code>.
       Please note that the <code>@index</code> key will be ignored when being processed.</p>
 
     <p>In both cases, the value associated with the keys <code>@list</code> and <code>@set</code>
@@ -11067,7 +11087,7 @@ <h2>Changes since JSON-LD Community Group Final Report</h2>
       with <code>@container</code> set to <code>@set</code>.</li>
     <li>The use of <a>blank node identifiers</a> to label properties is obsolete,
       and may be removed in a future version of JSON-LD, as is the support for <a>generalized RDF Datasets</a>.</li>
-    <li>The <a>default vocabulary</a> can be a relative IRI, which is evaluated
+    <li>The <a>vocabulary mapping</a> can be a relative IRI, which is evaluated
       either against an existing default vocabulary, or against the document base.
       This allows vocabulary-relative IRIs, such as the
       keys of <a>node objects</a>, are expanded or compacted relative