add section to differentiate between contexts and credential Schemas (#847)

Co-authored-by: David Chadwick <[email protected]>
Co-authored-by: Manu Sporny <[email protected]>
Co-authored-by: Ted Thibodeau Jr <[email protected]>

Author: 4 people

index.html

@@ -5256,15 +5256,17 @@ <h3>Fitness for Purpose</h3>
     </section>
 
     <section class="appendix informative">
-      <h2>Base Context</h2>
+      <h2>Contexts, Types, and Credential Schemas</h2>
 
-      <p>
+      <section class="informative">
+        <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">
 {
@@ -5505,7 +5507,108 @@ <h2>Base Context</h2>
   }
 }
 </pre>
+      </section>
+
+      <section class="informative">
+        <h3>Differences between Contexts, Types, and CredentialSchemas</h3>
+
+        <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 provide a comparison of the
+<code>@context</code>, <code>type</code>, and <code>credentialSchema</code>
+properties, and cover some of the more specific use cases where it is possible
+to use these features of the data model.
+        </p>
+        
+        <p>
+The <code>type</code> property is used to uniquely identify
+the type of the <a>verifiable credential</a> in which it appears, i.e., to
+indicate which set of claims the <a>verifiable credential</a> contains.
+This property, and the value <code>VerifiableCredential</code> within the set of
+its values, are mandatory. Whilst it is good practice to include one additional
+value depicting the unique subtype of this <a>verifiable credential</a>, it is permitted
+to either omit or include additional type values in the array. Many
+verifiers will request a <a>verifiable credential</a> of a specific subtype, then
+omitting the subtype value could make it more difficult for verifiers to inform
+the holder which <a>verifiable credential</a> they require. When a <a>verifiable
+credential</a> has multiple subtypes, listing all of them in the <code>type</code>
+property is sensible. While the semantics are the same in both a [[JSON]] and
+[[JSON-LD]] representation, the usage of the <code>type</code> property in a
+[[JSON-LD]] representation of a <a>verifiable credential</a> is able to enforce the semantics of the
+<a>verifiable credential</a> better than a [[JSON]] representation of the same
+credential because the machine is able to check the semantics. With [[JSON-LD]],
+the technology is not only describing the categorization of the set of claims,
+the technology is also conveying the structure and semantics of the sub-graph of
+the properties in the graph. In [[JSON-LD]], this represents the type of the node
+in the graph which is why some [[JSON-LD]] representations of a <a>verifiable
+credential</a> will use the <code>type</code> property on many objects in the
+<a>verifiable credential</a>.
+        </p>
+
+        <p>
+The primary purpose of the <code>@context</code> property, from a [[JSON-LD]]
+perspective, is to convey the meaning of the data and term definitions of the
+data in a <a>verifiable credential</a>, in a machine readable way. When encoding a pure
+[[JSON]] representation, the <code>@context</code> property remains mandatory and
+provides some basic support for global semantics. The <code>@context</code>
+property is used to map the globally unique URIs for properties in <a>verifiable
+credentials</a> and <a>verifiable presentations</a> into short-form alias names,
+making both the [[JSON]] and [[JSON-LD]] representations more human-friendly
+to read. From a [[JSON-LD]] perspective, this mapping also allows the data in
+a <a>credential</a> to be modeled in a network of machine-readable data, by
+enhancing how the data in the <a>verifiable credential</a> or <a>verifiable
+presentation</a> relates to a larger machine-readable data graph. This is
+useful for telling machines how to relate the meaning of data to
+other data in an ecosystem where parties are unable to coordinate. This
+property, with the first value in the set being
+<code>https://www.w3.org/2018/credentials/v1</code>, is mandatory.
+        </p>
+
+        <p>
+Since the <code>@context</code> property is used to map data to a graph
+data model, and the <code>type</code> property in [[JSON-LD]] is used to
+describe nodes within the graph, the <code>type</code> property becomes
+even more important when using the two properties in combination. For example,
+if the <code>type</code> property is not included within the resolved
+<code>@context</code> resource using [[JSON-LD]], it could lead to claims being
+dropped and/or their integrity no longer being protected during production and
+consumption of the <a>verifiable credential</a>. Alternatively, it could lead to
+errors being raised during production or consumption of a <a>verifiable
+credential</a>. This will depend on the design choices of the implementation and
+both paths are used in implementations today, so it's important to pay attention
+to these properties when using a [[JSON-LD]] representation of a <a>verifiable
+credential</a> or <a>verifiable presentation</a>.
+        </p>
+
+        <p>
+The primary purpose of the <code>credentialSchema</code> property is to
+define the structure of the <a>verifiable credential</a>, and the datatypes for
+the values of each property that appears. A <code>credentialSchema</code> is useful
+for defining the contents and structure of a set of claims in a <a>verifiable
+credential</a>, whereas [[JSON-LD]] and a <code>@context</code> in a <a>verifiable
+credential</a> are best used only for conveying the semantics and term
+definitions of the data, and can be used to define the structure of the
+<a>verifiable credential</a> as well.
+        </p>
+
+        <p>
+While it is possible to use some [[JSON-LD]] features to allude to the
+contents of the <a>verifiable credential</a>, it's not generally
+suggested to use <code>@context</code> to constrain the data types 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 dangerous if
+the implementer is looking to constrain the data type of the claims in the
+<a>credential</a>, and is expected not to be used.
+          </p>
 
+        <p>
+When the <code>credentialSchema</code> and <code>@context</code> properties
+are used in combination, both producers and consumers can be more confident
+about the expected contents and data types of the <a>verifiable credential</a>
+and <a>verifiable presentation</a>.
+        </p>
+      </section>
     </section>
 
     <section class="informative appendix">