Add warnings related to @vocab usage

index.html

@@ -1172,9 +1172,9 @@ <h3>Getting Started</h3>
 
         <p>
 This specification is designed to ease the prototyping of new types of
-[=verifiable credentials=]. Developers can copy the
-template below and paste it into common [=verifiable credential=]
-tooling to start issuing, holding, and verifying prototype credentials.
+[=verifiable credentials=]. Developers can copy the template below and paste it
+into common [=verifiable credential=] tooling to start issuing, holding, and
+verifying prototype credentials.
         </p>
 
         <p>
@@ -1183,14 +1183,18 @@ <h3>Getting Started</h3>
 each property-value pair in the `credentialSubject` object expresses a
 particular property of the credential subject. Once a developer has added a
 number of these property-value combinations, the modified object can be sent to
-the [=verifiable credential=] issuer software and a [=verifiable credential=] will
-be created for the developer. From a prototyping standpoint, that is all a
+the [=verifiable credential=] issuer software and a [=verifiable credential=]
+will be created for the developer. From a prototyping standpoint, that is all a
 developer needs to do.
         </p>
 
-        <pre class="example nohighlight" title="A template for creating prototype verifiable credentials">
+        <pre class="example nohighlight"
+             title="A template for creating prototype verifiable credentials">
 {
-  "@context": ["https://www.w3.org/ns/credentials/v2"],
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
   "type": ["VerifiableCredential", "MyPrototypeCredential"],
   "credentialSubject": {
     "mySubjectProperty": "mySubjectValue"
@@ -1201,12 +1205,14 @@ <h3>Getting Started</h3>
         <p>
 Once a developer has prototyped their credential to a point where they believe
 all of the credential properties are stable, it is advised that they generate
-vocabulary and context files for their application and publish them at stable URLs
-so that other developers can use the same vocabulary and context to achieve
-interoperability. This process is covered in Section
-<a href="#extensibility"></a>. Alternatively, developers can reuse existing vocabulary
-and context files that happen to fit their use case. They can explore the
-[[[VC-SPECS]]] [[VC-SPECS]] for reusable resources.
+vocabulary and context files for their application and publish them at stable
+URLs so that other developers can use the same vocabulary and context to achieve
+interoperability. The `https://www.w3.org/ns/credentials/examples/v2` URL above
+will then be replaced with the URL to an application-specific context. This
+process is covered in Section <a href="#extensibility"></a>. Alternatively,
+developers can reuse existing vocabulary and context files that happen to fit
+their use case. They can explore the [[[VC-SPECS]]] [[VC-SPECS]] for reusable
+resources.
         </p>
 
       </section>
@@ -4400,11 +4406,11 @@ <h3>JSON-LD</h3>
 documents=] are advised that interoperability might be reduced if JSON-LD
 keywords in the `@context` value are used to globally affect values in a
 [=verifiable credential=] or [=verifiable presentation=], such as by
-globally setting the `@base` keyword. For example, globally setting these values
+setting the `@base` or `@vocab` keyword. For example, setting these values
 might trigger a failure in a mis-implemented JSON Schema check on the `@context`
 value in an implementation that is performing [=type-specific credential
-processing=] and not expecting the `@base` value to be expressed in the
-`@context` value.
+processing=] and not expecting the `@base` value or `@vocab` value to be
+expressed in the `@context` value.
         </p>
 
         <p>
@@ -4415,22 +4421,39 @@ <h3>JSON-LD</h3>
 
         <ul>
           <li>
-Use of JSON-LD keywords in the `@context` value that globally modify document
-value processing, such as global settings of `@base`
+In-line declaration of JSON-LD keywords in the `@context` value that globally
+modify document term and value processing, such as setting `@base` or `@vocab`,
           </li>
           <li>
-In-line declaration of JSON-LD contexts in the `@context` property.
+Use of JSON-LD contexts that override declarations in previous contexts, such as
+resetting `@vocab`,
+          </li>
+          <li>
+In-line declaration of JSON-LD contexts in the `@context` property, and
           </li>
           <li>
 Use of full URLs for JSON-LD terms and types (e.g.,
 `https://www.w3.org/2018/credentials#VerifiableCredential` or
 `https://vocab.example/myvocab#SomeNewType`) instead of the short forms of
 any such values (e.g., `VerifiableCredential` or `SomeNewType`) that are
-either explicitly defined as JSON-LD `@context` mappings (e.g.,
-`https://www.w3.org/ns/credentials/v2`) or are implicitly defined via the
-`@vocab` feature that applies to all undefined terms.
+explicitly defined as JSON-LD `@context` mappings (e.g.,
+`https://www.w3.org/ns/credentials/v2`).
           </li>
-       </ul>
+        </ul>
+
+        <p>
+While this specification warns against the usage of `@vocab`, there are
+legitimate usages of the feature, such as to ease experimentation, development,
+and localized deployment. If an application developer desires to use `@vocab` in
+production, which is strongly advised against, they are urged to understand that
+any usage of `@vocab` will disable undefined term error reporting, and
+subsequent usage will override previous `@vocab` declarations. Subsequent usage
+of `@vocab` changes the semantics of the information contained in the document
+and so it is important to understand how these changes will affect the
+application being developed. Application developers MUST understand every
+JSON-LD context used by their application to the extent that it affects
+the semantics of the terms that are used by their application.
+        </p>
 
         <section>
           <h3>Syntactic Sugar</h3>