Add definition of Verifiable Credential Graph and why it exists

index.html

@@ -2178,9 +2178,10 @@ <h3>Presentations</h3>
           <dt><var id="defn-verifiableCredential">verifiableCredential</var></dt>
           <dd>
 The <code>verifiableCredential</code> <a>property</a> MAY be present. The value
-MUST be an array of one or more <a>verifiable credentials</a>, or of data
-derived from <a>verifiable credentials</a> in a cryptographically
-<a>verifiable</a> format.
+MUST be an array of one or more <a href="#verifiable-credential-graphs">
+verifiable credential graphs</a> in a cryptographically <a>verifiable</a> format.
+See Section <a href="#verifiable-credential-graphs"></a> for further details on
+this topic.
           </dd>
           <dt><var id="defn-holder">holder</var></dt>
           <dd>
@@ -2223,14 +2224,49 @@ <h3>Presentations</h3>
 
         <p>
 The contents of the <code>verifiableCredential</code> <a>property</a> shown
-above are <a>verifiable credentials</a>, as described by this specification. The
-contents of the <code>proof</code> <a>property</a> are proofs, as described by
-the Data Integrity [[VC-DATA-INTEGRITY]] specification. An example of a
-<a>verifiable presentation</a> using the JWT proof mechanism is
+above are <a href="#verifiable-credential-graphs">verifiable credential graphs</a>, as described by this
+specification. The contents of the <code>proof</code> <a>property</a> are proof
+graphs, as described by the Data Integrity [[VC-DATA-INTEGRITY]] specification.
+An example of a <a>verifiable presentation</a> using the JWT proof mechanism is
 provided in the Securing Verifiable Credentials using JOSE and COSE
 [[?VC-JOSE-COSE]] specification.
         </p>
 
+        <section>
+          <h4>Verifiable Credential Graphs</h4>
+
+          <p>
+When expressing <a>verifiable credentials</a> in a <a>presentation</a>, it is
+important to ensure that data in one <a>verifiable credential</a> is not
+mistaken to be the same data in another <a>verifiable credential</a>. For
+example, if one has two <a>verifiable credentials</a>, each containing an
+object of the following form: `{"type": "Person", "name": "Jane Doe"}`, it is
+not possible to tell if one object is describing the same person as the other
+object. In other words, merging data between two <a>verifiable credentials</a>
+without confirming that they are discussing the same entities and/or properties,
+can lead to a corrupted data set.
+          </p>
+
+          <p>
+To ensure that data from different <a>verifiable credentials</a> are not
+accidentally co-mingled, the concept of a
+<dfn class="lint-ignore">verifiable credential graph</dfn> is used to
+encapsulate each <a>verifiable credential</a>. Each value associated with the
+`verifiableCredential` property of a <a>presentation</a> is of type
+<dfn class="lint-ignore">VerifiableCredentialGraph</dfn> and contains a single
+<a>verifiable credential</a>. Using this type has a concrete effect on full
+JSON-LD processing, which properly separates graph node identifiers in one graph
+from those in another graph. Implementers that do not fully process JSON-LD will
+need to keep this in mind if they merge data from one <a>verifiable
+credential</a> with data from another, such as when the `credentialSubject.id`
+is the same in both <a>verifiable credentials</a>, but the object might contain
+objects of the "Jane Doe" form described in the previous paragraph. It is
+important to not merge objects that seem to have similar properties but do not
+contain an `id` property that uses a global identifier, such
+as a URL.
+          </p>
+        </section>
+
         <section>
           <h4>Presentations Using Derived Credentials</h4>
 
@@ -5646,7 +5682,7 @@ <h4>Holder</h4>
 publish information containing the verification material used to secure
 <a>verifiable presentations</a>. This metadata is expected to be used when
 checking proofs on <a>verifiable presentations</a>. Some cryptographic
-identifiers contain all necessary metadata in the identifier itself. In those 
+identifiers contain all necessary metadata in the identifier itself. In those
 cases, no additional metadata is required. Other identifiers use verifiable
 data registries where such metadata is automatically published for use
 by <a>verifiers</a>, without any additional action by the <a>holder</a>.
@@ -5657,7 +5693,7 @@ <h4>Holder</h4>
         </p>
 
         <p class="note">
-Validation is the process by which verifiers apply business rules to 
+Validation is the process by which verifiers apply business rules to
 evaluate the propriety of a particular use of a <a>verifiable credential</a>.
         </p>
         <ul>
@@ -5675,11 +5711,11 @@ <h4>Holder</h4>
         </p>
         <ul>
           <li>
-The <a>verifiable presentation</a> is secured, 
+The <a>verifiable presentation</a> is secured,
 using a mechanism the <a>verifier</a> trusts to protect the integrity of the content.
           </li>
           <li>
-The <a>verifiable presentation</a> includes one or more <a>verifiable credentials</a> that are secured, 
+The <a>verifiable presentation</a> includes one or more <a>verifiable credentials</a> that are secured,
 using a mechanism the <a>verifier</a> trusts to protect the integrity of the content.
           </li>
           <li>

vocab/credentials/v2/vocabulary.yml

@@ -66,7 +66,8 @@ class:
 
   - id: VerifiableCredentialGraph
     label: Verifiable credential graph
-    comment: Instances of this class are <a href="https://www.w3.org/TR/rdf12-concepts/#section-rdf-graph">RDF Graphs</a> [[RDF12-CONCEPTS]], where each of these graphs must include exactly one <a href="#VerifiableCredential">Verifiable Credential</a>.
+    defined_by: https://www.w3.org/TR/vc-data-model-2.0/#dfn-verifiablecredentialgraph
+    comment: Instances of this class are <a href="https://www.w3.org/TR/rdf12-concepts/#section-rdf-graph">RDF Graphs</a> [[RDF12-CONCEPTS]].
 
   - id: VerifiablePresentation
     defined_by: https://www.w3.org/TR/vc-data-model-2.0/#presentations