add section to differentiate between contexts and credential Schemas

Author: kdenhartog

index.html

@@ -5247,15 +5247,24 @@ <h3>Fitness for Purpose</h3>
   </section>
 
   <section class="appendix informative">
-      <h2>Base Context</h2>
+      <h2>Contexts and Credential Schemas</h2>
+      <section class="informative">
 
-      <p>
+        <p>
+The <a>verifiable credential</a> and <a>verifiable presentation</a> data models
+leverage a variety of underlying technologies including [[JSON-LD]] and
+[[JSON-SCHEMA-2018]]. This section will cover some of the more specific use
+cases where it's suggested to utilize these features of the data model.
+        </p>
+        
+        <h3>Base Context</h3>
+        <p>
 The base context, located at
 <code>https://www.w3.org/2018/credentials/v1</code> with a SHA-256 digest of
 <strong><code>ab4ddd9a531758807a79a5b450510d61ae8d147eab966cc9a200c07095b0cdcc</code></strong>,
 can be used to implement a local cached copy. For convenience, the base context
 is also provided in this section.
-      </p>
+        </p>
 
 <pre class="informative">
 {
@@ -5497,6 +5506,44 @@ <h2>Base Context</h2>
 }
 </pre>
 
+      </section>
+      <section class="informative appendix">
+        <h2>Differences between Contexts and CredentialSchemas</h2>
+        <p>
+The primary purpose of a <code>credentialSchema</code> is different from the
+primary purpose of <code>@context</code>. A <code>credentialSchema</code> is
+useful for defining the data shape and type of a <code>Verifiable
+Credential</code>, whereas [[JSON-LD]] and a <code>@context</code> in a
+verifiable credential are best used only for conveying the semantics and term 
+definitions of the data.
+        </p>
+
+        <p>
+A <code>@context</code> can help you define [[JSON-LD]] semantics and term
+definitions. A <code>credentialSchema</code> is much more flexible and can help
+you define [[JSON-SCHEMA-2018]], [[SHACL]], or any other schema technology you
+want to use to further constrain the shape of the data.
+        </p>
+
+        <p>
+While it is possible to use some of [[JSON-LD]] features to allude to the
+shape of the data, it's not generally suggested to use <code>@context</code> for
+schemas related to the shape of the data model. For example, <code>"@type":
+"@json"</code> is useful for leaving the semantics open ended and not strictly
+defined. This can be very useful when your JSON data has no well defined
+semantics, or where its semantics are rapidly changing, or externally set.
+        </p>
+
+        <p>
+When the <code>credentialSchema</code> and <code>@context</code> are used
+in combination together, these tools can help both producers and consumers
+agree to establish a rigid data shape with strong semantics that make it much
+easier for an <a>issuer</a> to be more explicit about the <a>claims</a> being
+signed so that the <a>verifier</a> is able to clearly interoperate at the data
+layer without further agreement other than what's been conveyed in the data
+model.
+        </p>
+      </section>
   </section>
 
     <section class="informative appendix">