From fc58a8c0a0e59508dd1dfb8e31a0c96f5c0b8dda Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sat, 27 Oct 2018 12:30:56 -0400
Subject: [PATCH] Add section on Contexts. See #206.

---
 index.html | 55 ++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 49 insertions(+), 6 deletions(-)

diff --git a/index.html b/index.html
index 09c2bb49c..059437c27 100644
--- a/index.html
+++ b/index.html
@@ -651,6 +651,54 @@ <h1>Basic Concepts</h1>
 toward the end of the document.
       </p>
 
+      <section>
+        <h2>Contexts</h2>
+
+        <p>
+When two software systems need to exchange data, they must use terminology
+that both systems understand. A useful analogy is to think about how two
+people communicate; both people must use the same language and the words
+that each of them use must mean the same thing to the other party. This
+specification uses the <code>@context</code> property to express the context
+of the conversation.
+        </p>
+
+        <dl>
+          <dt><dfn>@context</dfn></dt>
+          <dd>
+The value of this property MUST be one or more URIs where first URI is the
+value <code>https://w3.org/2018/credentials/v1</code>.
+If more than one URI is provided, the URIs MUST be interpreted as an
+ordered set. It is RECOMMENDED that dereferencing the URI results in a
+document containing machine-readable information about the context.
+          </dd>
+        </dl>
+
+        <pre class="example nohighlight" title="Usage of the @context property">
+{
+  <span class="highlight">"@context": [
+    "https://w3.org/2018/credentials/v1",
+    ...
+  ]</span>,
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "proof": { ... }
+}
+        </pre>
+
+        <p>
+The data available at <code>https://w3.org/2018/credentials/v1</code>
+is a static document that is never updated and may thus be downloaded and
+cached client side. The associated vocabulary document for the
+Verifiable Credentials Data Model can be found at the following URL:
+<code>https://w3.org/2018/credentials</code>.
+        </p>
+      </section>
+
       <section>
         <h2>Types</h2>
 
@@ -2165,12 +2213,7 @@ <h2>JSON-LD</h2>
 processing a <a>verifiable credential</a> or <a>verifiable presentation</a>,
 and a <code>@context</code> property is not present at the top-level of the
 JSON-LD document, then a <code>@context</code> property with a value of
-<code>https://w3.org/2018/credentials/v1</code> MUST be assumed. The
-JSON-LD Context available at <code>https://w3.org/2018/credentials/v1</code>
-is a static document that is never updated and may thus be downloaded and
-cached client side. The associated vocabulary document for the
-Verifiable Credentials Data Model can be found at the following URL:
-<code>https://w3.org/2018/credentials</code>.
+<code>https://w3.org/2018/credentials/v1</code> MUST be assumed.
         </p>
 
       </section>