Add section for @propagate and stub for @source.

For #174.

(cherry picked from commit f5b8a22)

Author: gkellogg

Gemfile

@@ -1,8 +1,10 @@
 source "https://rubygems.org"
 
 gem 'json-ld', github: 'ruby-rdf/json-ld', branch: 'develop'
+gem 'json-ld-preloaded'
 gem 'nokogiri'
 gem 'nokogumbo'
 gem 'linkeddata'
 gem 'colorize'
 gem 'rake'
+gem 'byebug'

Gemfile.lock

@@ -1,6 +1,6 @@
 GIT
   remote: git://github.com/ruby-rdf/json-ld.git
-  revision: 74a05a9f623c5a9e02cbe42f053f9d09181fee97
+  revision: 813e1ff914cc1a1025db14de392fd738b4cbb674
   branch: develop
   specs:
     json-ld (3.0.2)
@@ -18,6 +18,7 @@ GEM
     bcp47 (0.3.3)
       i18n
     builder (3.2.3)
+    byebug (11.0.1)
     colorize (0.8.1)
     concurrent-ruby (1.1.5)
     connection_pool (2.2.2)
@@ -26,7 +27,7 @@ GEM
       sxp (~> 1.0)
     equivalent-xml (0.6.0)
       nokogiri (>= 1.4.3)
-    haml (5.0.4)
+    haml (5.1.1)
       temple (>= 0.8.0)
       tilt
     hamster (3.0.0)
@@ -73,13 +74,13 @@ GEM
       sparql-client (~> 3.0)
     mini_portile2 (2.4.0)
     multi_json (1.13.1)
-    net-http-persistent (3.0.0)
+    net-http-persistent (3.0.1)
       connection_pool (~> 2.2)
     nokogiri (1.10.3)
       mini_portile2 (~> 2.4.0)
     nokogumbo (1.5.0)
       nokogiri
-    public_suffix (3.0.3)
+    public_suffix (3.1.1)
     rack (2.0.7)
     rake (12.3.2)
     rdf (3.0.12)
@@ -113,17 +114,17 @@ GEM
       rdf (>= 2.2, < 4.0)
       rdf-rdfa (>= 2.2, < 4.0)
       rdf-xsd (>= 2.2, < 4.0)
-    rdf-reasoner (0.5.1)
+    rdf-reasoner (0.5.2)
       rdf (~> 3.0)
       rdf-vocab (~> 3.0)
       rdf-xsd (~> 3.0)
-    rdf-tabular (2.2.1)
+    rdf-tabular (2.2.2)
       addressable (~> 2.3)
       bcp47 (~> 0.3, >= 0.3.3)
       json-ld (>= 2.1, < 4.0)
-      rdf (>= 2.2, < 4.0)
-      rdf-vocab (>= 2.2, < 4.0)
-      rdf-xsd (>= 2.2, < 4.0)
+      rdf (~> 3.0)
+      rdf-vocab (~> 3.0)
+      rdf-xsd (~> 3.0)
     rdf-trig (3.0.1)
       ebnf (~> 1.1)
       rdf (~> 3.0)
@@ -133,7 +134,7 @@ GEM
     rdf-turtle (3.0.6)
       ebnf (~> 1.1)
       rdf (~> 3.0)
-    rdf-vocab (3.0.5)
+    rdf-vocab (3.0.7)
       rdf (~> 3.0, >= 3.0.11)
     rdf-xsd (3.0.1)
       rdf (~> 3.0)
@@ -165,8 +166,10 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  byebug
   colorize
   json-ld!
+  json-ld-preloaded
   linkeddata
   nokogiri
   nokogumbo

common/extract-examples.rb

@@ -10,6 +10,7 @@
 # - @data-options indicates the comma-separated option/value pairs to pass to the processor
 require 'getoptlong'
 require 'json'
+require 'json/ld/preloaded'
 require 'nokogiri'
 require 'linkeddata'
 require 'fileutils'

index.html

@@ -596,9 +596,19 @@ <h2>Syntax Tokens and Keywords</h2>
         Used as the <code>@type</code> value of a <a>JSON literal</a>.
         This keyword is described in <a href="#json-literals" class="sectionRef"></a>.
       </dd>
-      <dt><code>:</code></dt>
-      <dd>The separator for JSON keys and values that use
-        <a>compact IRIs</a>.</dd>
+      <dt class="changed"><code>:</code></dt><dd class="changed">
+        The separator for JSON keys and values that use <a>compact IRIs</a>.</dd>
+      <dt class="changed">`@propagate`</dt><dd class="changed">
+        Used in a <a>context definition</a> to change the sccope of that context.
+        By default, it is `true`,
+        meaning that contexts propagate across <a>node objects</a>
+        (other than for type-<a>scoped contexts</a>, which default to `false`).
+        Setting this to `false` causes term definitions created within that context
+        to be removed when entering a new <a>node object</a>.</dd>
+      <dt class="changed">`@source`</dt><dd class="changed">
+        Used in a <a>context definition</a> to load an external context
+        within which the containing <a>context definition</a> is merged.
+        This can be useful to add JSON-LD 1.1 features to JSON-LD 1.0 contexts.</dd>
     </dl>
 
     <p>All keys, <a>keywords</a>, and values in JSON-LD are case-sensitive.</p>
@@ -3413,7 +3423,9 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
     different things depending on the context.
     A <a>context</a> scoped on <code>@type</code> is only in effect for the <a>node object</a> on which
     the type is used; the previous in-scope <a>contexts</a> are placed back into
-    effect when traversing into another <a>node object</a>.</p>
+    effect when traversing into another <a>node object</a>.
+    As described further in <a href="#context-propagation" class="sectionRef"></a>,
+    this may be controlled using the `@propagate` keyword.</p>
 
   <p class="note">Any property-scoped or local contexts that were introduced in the <a>node object</a>
     would still be in effect when traversing into another <a>node object</a>.</p>
@@ -3525,6 +3537,103 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
     <a>processing mode</a> set to <code>json-ld-1.1</code>.</p>
 </section>
 
+<section class="informative changed"><h2>Context Propagation</h2>
+  <p>Once introduced, <a>contexts</a> remain in effect until a subsequent
+    <a>context</a> removes it by setting `@context` to `null`,
+    or by redefining terms,
+    with the exception of type-<a>scoped contexts</a>,
+    which limits the affect of that context until the next <a>node object</a> is entered.
+    This behavior can be changed using the `@propagate` keyword.</p>
+
+  <p>The following example illustrates how terms defined in a context with `@propagate` set to `false`
+    are effectively removed when descending into new <a>node object</a>.</p>
+
+  <aside class="example ds-selector-tabs"
+         title="Marking a context to not propagate">
+    <div class="selectors">
+      <button class="selected" data-selects="compacted">Compacted (Input)</button>
+      <button data-selects="expanded">Expanded (Result)</button>
+      <button data-selects="statements">Statements</button>
+      <button data-selects="turtle">Turtle</button>
+      <a class="playground" target="_blank"></a>
+    </div>
+    <pre class="compacted input selected nohighlight" data-transform="updateExample">
+    <!--
+    {
+      "@context": {
+        "@version": 1.1,
+        "term": {
+          "@id": "http://example.org/original",
+          "@context": {
+            "@propagate": false,
+            #### ↑ Scoped context only lasts in one node-object####
+            "term": "http://example.org/non-propagated-term"
+          }
+        }
+      },
+      "term": {
+      #### ↑ This term is the original####
+        "term": {
+        #### ↑ This term is from the scoped context####
+          "term": "This term is from the first context"
+          #### ↑ This term is the original again####
+        }
+      }
+    }
+    -->
+    </pre>
+    <pre class="expanded result result nohighlight"
+         data-transform="updateExample"
+         data-result-for="Marking a context to not propagate-compacted">
+    <!--
+    [{
+      "http://example.org/original": [{
+        "http://example.org/non-propagated-term": [{
+          "http://example.org/original": [
+            {"@value": "This term is from the first context"}
+          ]
+        }]
+      }]
+    }]
+    -->
+    </pre>
+    <table class="statements"
+           data-result-for="Marking a context to not propagate-expanded"
+           data-to-rdf
+           data-no-lint>
+      <thead><tr><th>Subject</th><th>Property</th><th>Value</th></tr></thead>
+      <tbody>
+        <tr><td>_:b2</td><td>http://example.org/original</td><td>This term is from the first context</td></tr>
+        <tr><td>_:b1</td><td>http://example.org/non-propagated-term</td><td>_:b2</td></tr>
+        <tr><td>_:b0</td><td>http://example.org/original</td><td>_:b1</td></tr>
+      </tbody>
+    </table>
+    <pre class="turtle"
+         data-content-type="text/turtle"
+         data-result-for="Marking a context to not propagate-expanded"
+         data-transform="updateExample"
+         data-to-rdf
+         data-no-lint>
+    <!--
+    @prefix ex: <http://example.org/> .
+    [
+      ex:original [
+        ex:non-propagated-term [
+          ex:original "This term is from the first context"
+        ]
+      ]
+    ] .
+    -->
+    </pre>
+  </aside>
+
+  <p class="note">Contexts included within an array must all have the same value for `@propagate`
+    due to the way that rollback is defined in [[[JSON-LD11-API]]].</p>
+</section>
+
+<section class="informative changed"><h2>Sourced Contexts</h2>
+</section>
+
 <section class="informative changed"><h2>Protected Term Definitions</h2>
   <p>JSON-LD is used in many specifications as the specified data format.
     However, there is also a desire to allow some JSON-LD contents to be processed as plain JSON,
@@ -11718,10 +11827,12 @@ <h2>Context Definitions</h2>
     <code>@reverse</code>,
     <code>@type</code>,
     <code>@language</code>,
+    <code>@container</code>,
     <code class="changed">@context</code>,
-    <code class="changed">@prefix</code>, or
-    <code>@container</code>. An
-    <a>expanded term definition</a> SHOULD NOT contain any other keys.</p>
+    <code class="changed">@prefix</code>,
+    <code class="changed">@propagate</code>, or
+    <code class="changed">@source</code>.
+    An <a>expanded term definition</a> SHOULD NOT contain any other keys.</p>
 
   <p>If the term being defined is not a <a>compact IRI</a> or
     <a>absolute IRI</a> and the <a>active context</a> does not have an
@@ -11787,14 +11898,20 @@ <h2>Context Definitions</h2>
   <p class="changed">If the <a>expanded term definition</a> contains the <code>@prefix</code>
     <a>keyword</a>, its value MUST be <code>true</code> or <code>false</code>.</p>
 
+  <p class="changed">If the <a>expanded term definition</a> contains the <code>@propagate</code>
+    <a>keyword</a>, its value MUST be <code>true</code> or <code>false</code>.</p>
+
+  <p class="changed">If the <a>expanded term definition</a> contains the <code>@source</code>
+    <a>keyword</a>, its value MUST be an <a>absolute IRI</a> or <a>relative IRI</a>.</p>
+
   <p><a>Terms</a> MUST NOT be used in a circular manner. That is,
     the definition of a term cannot depend on the definition of another term if that other
     term also depends on the first term.</p>
 
   <p>See <a class="sectionRef" href="#the-context"></a> for further discussion on contexts.</p>
 </section>
 
-<section class="normative changed">
+<section class="normative">
   <h2>Keywords</h2>
   <p>JSON-LD <a>keywords</a> are described in <a class="sectionRef" href="#syntax-tokens-and-keywords"></a>,
     this section describes where each <a>keyword</a> may appear within different JSON-LD structures.</p>
@@ -11811,17 +11928,17 @@ <h2>Keywords</h2>
       <code>@set</code>,
       <code>@language</code>,
       <code>@index</code>,
-      <span><code>@id</code></span>,
-      <span><code>@graph</code></span>,
-      <span><code>@type</code></span>, or be
+      <code class="changed">@id</code>,
+      <code class="changed">@graph</code>,
+      <code class="changed">@type</code>, or be
       <a>null</a>,
-      or an <a>array</a> containing exactly any one of those keywords, or a
-      combination of <code>@set</code> and any of <code>@index</code>,
-      <code>@id</code>, <code>@graph</code>, <code>@type</code>,
-      <code>@language</code> in any order.
-      The value may also be an array
-      containing <code>@graph</code> along with either <code>@id</code> or
-      <code>@index</code> and also optionally including <code>@set</code>.
+      <span class="changed">or an <a>array</a> containing exactly any one of those keywords, or a
+        combination of <code>@set</code> and any of <code>@index</code>,
+        <code>@id</code>, <code>@graph</code>, <code>@type</code>,
+        <code>@language</code> in any order.
+        The value may also be an array
+        containing <code>@graph</code> along with either <code>@id</code> or
+        <code>@index</code> and also optionally including <code>@set</code></span>.
     </dd>
     <dt><code>@context</code></dt><dd>
       The <code>@context</code> keyword MUST NOT be aliased, and MAY be used as a key in the following objects:
@@ -11841,6 +11958,12 @@ <h2>Keywords</h2>
       a <a>context definition</a>, or
       an <a>array</a> composed of any of these.
     </dd>
+    <dt>`@graph`</dt><dd>
+      The `@graph` keyword MAY be aliased and MAY be used as a key in a <a>node object</a> or a <a>graph object</a>.
+      The unaliased `@graph` MAY be used as the value of the <code>@container</code> key within an <a>expanded term definition</a>.
+      The value of the `@graph` key MUST be a <a>value object</a>, <a>node object</a>, or an array of either <a>value objects</a> or <a>node objects</a>.
+      See <a class="sectionRef" href="#named-graphs"></a>.
+    </dd>
     <dt><code>@id</code></dt><dd>
       The <code>@id</code> keyword MAY be aliased and MAY be used as a key in a <a>node object</a> or a <a>graph object</a>.
       The unaliased <code>@id</code> MAY be used as a key in an <a>expanded term definition</a>,
@@ -11883,7 +12006,7 @@ <h2>Keywords</h2>
 
       <p>See <a class="sectionRef" href="#sets-and-lists"></a> for further discussion on sets and lists.</p>
     </dd>
-    <dt><code>@nest</code></dt><dd>
+    <dt class="changed"><code>@nest</code></dt><dd class="changed">
       The <code>@nest</code> keyword MAY be aliased and MAY be used as a key in a <a>node object</a>.
       The unaliased <code>@nest</code> MAY be used as the value of a <a>simple term definition</a>,
       or as a key in an <a>expanded term definition</a>.
@@ -11892,7 +12015,7 @@ <h2>Keywords</h2>
       Its value MUST be a <a>string</a>.
       See <a class="sectionRef" href="#property-nesting"></a> for a further discussion.
     </dd>
-    <dt><code>@none</code></dt><dd>
+    <dt class="changed"><code>@none</code></dt><dd class="changed">
       The <code>@none</code> keyword MAY be aliased and MAY be used as a key in an
       <a>index map</a>, <a>id map</a>, <a>language map</a>, <a>type map</a>.
       See <a class="sectionRef" href="#data-indexing"></a>,
@@ -11902,13 +12025,18 @@ <h2>Keywords</h2>
       <a class="sectionRef" href="#named-graph-indexing"></a>, or
       <a class="sectionRef" href="#named-graph-data-indexing"></a>
       for a further discussion.</dd>
-    <dt><code>@prefix</code></dt><dd>
+    <dt class="changed"><code>@prefix</code></dt><dd class="changed">
       The <code>@prefix</code> keyword MUST NOT be aliased, and MAY be used as a key in an <a>expanded term definition</a>.
       Its value MUST be <code>true</code> or <code>false</code>.
       See <a class="sectionRef" href="#compact-iris"></a>
       and <a class="sectionRef" href="#context-definitions"></a>
       for a further discussion.
     </dd>
+    <dt class="changed">`@propagate`</dt><dd class="changed">
+      The `@propagate` keyword MUST NOT be aliased, and MAY be used in a <a>context definition</a>.
+      Its value MUST be <code>true</code> or <code>false</code>.
+      See <a class="sectionRef" href="#context-propagation"></a> for a further discussion.
+    </dd>
     <dt><code>@reverse</code></dt><dd>
       The <code>@reverse</code> keyword MAY be aliased and MAY be used as a key in a <a>node object</a>.
       The unaliased <code>@reverse</code> MAY be used as a key in an <a>expanded term definition</a>.
@@ -11934,6 +12062,11 @@ <h2>Keywords</h2>
 
       <p>See <a class="sectionRef" href="#sets-and-lists"></a> for further discussion on sets and lists.</p>
     </dd>
+    <dt class="changed">`@source`</dt><dd class="changed">
+      The `@source` keyword MUST NOT be aliased, and MAY be used in a <a>context definition</a>.
+      Its value MUST be an <a>absolute IRI</a> or <a>relative IRI</a>.
+      See <a class="sectionRef" href="#sourced-contexts"></a> for a further discussion.
+    </dd>
     <dt><code>@type</code></dt><dd>
       The <code>@type</code> keyword MAY be aliased and MAY be used as a key in a <a>node object</a> or a <a>value object</a>.
       The unaliased <code>@type</code> MAY be used as a key in an <a>expanded term definition</a>,
@@ -11949,7 +12082,7 @@ <h2>Keywords</h2>
       Its value key MUST be either a <a>string</a>, a <a>number</a>, <code>true</code>, <code>false</code> or <a>null</a>.
       This keyword is described further in <a class="sectionRef" href="#value-objects"></a>.
     </dd>
-    <dt><code>@version</code></dt><dd>
+    <dt class="changed"><code>@version</code></dt><dd class="changed">
       The <code>@version</code> keyword MUST NOT be aliased and MAY be used as a key in a <a>context definition</a>.
       Its value MUST be a <a>number</a> with the value <code>1.1</code>.
       This keyword is described further in <a class="sectionRef" href="#context-definitions"></a>.
@@ -12880,6 +13013,12 @@ <h2>Changes since JSON-LD Community Group Final Report</h2>
       to limit the ability of other contexts to override them.</li>
     <li>A <a>context</a> defined in an <a>expanded term definition</a> may also be used for values
       of <code>@type</code>, which defines a <a>context</a> to use for <a>node objects</a> including the associated type.</li>
+    <li>By default, all contexts are propagated when traversing <a>node objects</a>, other than
+      type-scoped contexts. This can be controlled using the <code>@propagate</code>
+      <a>entry</a> in a <a>local context</a>.</li>
+    <li>A context may contain a <code>@source</code> <a>entry</a> used to reference a remote context
+      within a context, allowing <code>JSON-LD 1.1</code> features to be added to contexts originally
+      authored for <code>JSON-LD 1.0</code>.</li>
   </ul>
 </section>