Add OverlayRenderMethod with oca-bundle-v2 render suite

index.html

@@ -118,9 +118,12 @@
         alternateFormats: [ {uri: "diff-20111214.html", label: "diff to previous version"} ],
         */
         localBiblio: {
-          ENTRY: {
-            title: "Example Title",
-            href: "https://website.example/document",
+          OCA: {
+            title: "Overlays Capture Architecture Specification",
+            href: "https://oca.colossi.network/specification/",
+            authors: ["Human Colossus Foundation"],
+            status: "Living Specification",
+            date: "2024"
           },
         },
         lint: {"no-unused-dfns": false},
@@ -297,9 +300,9 @@ <h3>The `renderMethod` Property</h3>
 more rendering methods that can be used by software to express the
 [=verifiable credential=] using a visual, auditory, or haptic mechanism. Each
 `renderMethod` value MUST specify its `type`, for example,
-`TemplateRenderMethod`. The precise contents of each rendering
-hint is determined by the specific `renderMethod` `type`
-definition.
+`TemplateRenderMethod`, `OverlayRenderMethod`, or `EmbeddedRenderer`.
+The precise contents of each rendering hint is determined by the specific
+`renderMethod` `type` definition.
           </dd>
         </dl>
       </section>
@@ -1025,10 +1028,294 @@ <h4>Wrapper Code</h4>
       </section>
     </section>
 
+      <section>
+        <h4>OverlayRenderMethod</h4>
 
+        <p>
+OverlayRenderMethod is used by an [=issuer=] to link a [=verifiable credential=]
+to an external package of presentation metadata&mdash;such as an Overlays Capture
+Architecture (OCA) Bundle [[[OCA]]]&mdash;without prescribing a single visual
+template. A capture base describes credential attributes as JSON Pointer
+[[RFC6901]] paths from the root of the [=verifiable credential=] document, and
+overlays supply labels, formats,
+sensitive-data flags, and related presentation rules. Renderers use this
+information to build user interfaces, select locales, and display fields
+consistently across applications.
+        </p>
 
+        <p>
+When an [=issuer=] desires to specify overlay-based rendering instructions
+for a [=verifiable credential=], they MAY add a `renderMethod` property that uses
+the data model described below.
+        </p>
 
+        <table class="simple">
+          <thead>
+            <tr>
+              <th style="white-space: nowrap">Property</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>id</td>
+              <td>
+An OPTIONAL [=string=] that follows the [[[URL]]] specification and, when
+fetched, dereferences to a complete `OverlayRenderMethod` value. When `bundle`
+is present, this property MAY be omitted.
+              </td>
+            </tr>
+            <tr>
+              <td>type</td>
+              <td>
+A REQUIRED [=string=] that MUST be the value `OverlayRenderMethod`.
+              </td>
+            </tr>
+            <tr>
+              <td>renderSuite</td>
+              <td>
+A REQUIRED [=string=] that identifies the overlay package format and processing
+algorithm. The `oca-bundle-v2` render suite (OCA v2.0.0) is defined in this
+specification.
+              </td>
+            </tr>
+            <tr>
+              <td>name</td>
+              <td>
+An OPTIONAL human-readable [=string=] that can be displayed to provide a hint to
+the type of rendering that will be performed. This property might be used in a
+graphical interface that enables an individual to select between multiple
+presentation modes.
+              </td>
+            </tr>
+            <tr>
+              <td>description</td>
+              <td>
+An OPTIONAL human-readable [=string=] that provides a more detailed description
+of the overlay-based rendering method and when it might be useful.
+              </td>
+            </tr>
+            <tr>
+              <td>renderProperty</td>
+              <td>
+An OPTIONAL [=list=] of [=string=] values that each conform to the
+[[[RFC6901]]] syntax that specifies which properties from the [=verifiable
+credential=] are exposed when using this specific render method. If
+`renderProperty` is not provided, the entire [=verifiable credential=] is
+presumed to be available to the overlay renderer.
+              </td>
+            </tr>
+            <tr>
+              <td>bundle</td>
+              <td>
+An OPTIONAL [=URL=] or [=ordered map|map=] that provides or refers to the
+overlay package used for rendering. If the value is a [=URL=], it MUST
+dereference to an overlay bundle document (for the `oca-bundle-v2` render suite,
+an OCA Bundle in JSON format with media type `application/json`). If the value
+is a [=ordered map|map=], it MUST conform to the following rules:
+                <table class="simple">
+                  <thead>
+                    <tr>
+                      <th style="white-space: nowrap">Property</th>
+                      <th>Description</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    <tr>
+                      <td>id</td>
+                      <td>
+A REQUIRED [=string=] that follows the [[[URL]]] specification and, when
+fetched, dereferences to the overlay bundle.
+                      </td>
+                    </tr>
+                    <tr>
+                      <td>mediaType</td>
+                      <td>
+A RECOMMENDED [=string=] that identifies the media type for the `id` value
+as specified in [[[RFC6838]]]. For the `oca-bundle-v2` render suite, the value
+SHOULD be `application/json`.
+                      </td>
+                    </tr>
+                    <tr>
+                      <td>digestMultibase</td>
+                      <td>
+An OPTIONAL multibase-encoded Multihash of the overlay bundle. The multibase
+value MUST be `u` (base64url-nopad) and the multihash value MUST be SHA-2 with
+256-bits of output (`0x12`).
+                      </td>
+                    </tr>
+                  </tbody>
+                </table>
+              </td>
+            </tr>
+            <tr>
+              <td>digestMultibase</td>
+              <td>
+An OPTIONAL multibase-encoded Multihash of the overlay render method referenced
+if `id` is specified. The multibase value MUST be `u` (base64url-nopad) and the
+multihash value MUST be SHA-2 with 256-bits of output (`0x12`).
+              </td>
+            </tr>
+          </tbody>
+        </table>
+
+        <p>
+The data model shown above is expressed in a [=verifiable credential=] in the
+example below.
+        </p>
+
+        <pre
+          class="example nohighlight"
+          title="Usage of OverlayRenderMethod with the oca-bundle-v2 render suite"
+        >
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2",
+    "https://w3id.org/vc/render-method/v1"
+  ],
+  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
+  "issuer": {
+    "id": "https://example.edu/issuers/565049",
+    "name": "Example University"
+  },
+  "validFrom": "2024-01-01T00:00:00Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "degree": {
+      "type": "BachelorDegree",
+      "name": "Bachelor of Science and Arts",
+      "degreeType": "Undergraduate",
+      "major": "Computer Science"
+    }
+  },
+  <span class="highlight">"renderMethod": [{
+    "type": "OverlayRenderMethod",
+    "renderSuite": "oca-bundle-v2",
+    "bundle": {
+      "id": "https://example.edu/oca-bundles/degree-2024.json",
+      "mediaType": "application/json",
+      "digestMultibase": "uEiC96D8xPcVfm...WNcMF4Kc-Yw"
+    },
+    "name": "University Degree Display",
+    "description": "Renders the degree credential with multi-language support"
+  }]</span>
+}
+        </pre>
+
+        <section>
+          <h3>The `oca-bundle-v2` Render Suite</h3>
+
+          <p>
+The `oca-bundle-v2` render suite refers to the Overlays Capture Architecture
+(OCA) <a href="https://oca.colossi.network/specification/">v2.0.0</a>
+specification [[[OCA]]]. It uses an OCA Bundle containing a capture base and
+overlays. For this render suite, `renderSuite` MUST be the value
+`oca-bundle-v2`, and `bundle` MUST be present either as a URL or as a map with
+an `id` that dereferences to the bundle.
+          </p>
+
+          <p>
+When processing this render suite, attribute names in the capture base MUST be
+interpreted as JSON Pointer paths [[RFC6901]] from the root of the
+[=verifiable credential=] document. Attribute names in overlays that reference
+capture base attributes MUST use the same JSON Pointer paths.
+For example, an attribute named `/credentialSubject/degree/name` references
+the `name` property within the `degree` object of `credentialSubject`. Overlays
+in the bundle provide presentation metadata such as human-readable labels in
+multiple languages, formatting rules, and sensitive-data flags for those
+attributes.
+          </p>
+
+          <p>
+An example OCA Bundle structure for the credential above might look like:
+          </p>
+
+          <pre
+            class="example nohighlight"
+            title="Example OCA Bundle structure with JSON path attributes"
+          >
+{
+  "bundle": {
+    "v": "OCAS11JSON000646_",
+    "digest": "EBfdlu8R27Fbx-ehrqwIxQ-na4B7A4LqidzXqj8gkzHp",
+    "capture_base": {
+      "digest": "ECui6bAv2zzW2gMVQbKT3M7g2q4r6yWKf2Y2k9CDa8Nq",
+      "type": "spec/capture_base/2.0.0",
+      "attributes": {
+        "/credentialSubject/degree/type": "Text",
+        "/credentialSubject/degree/name": "Text",
+        "/credentialSubject/degree/degreeType": "Text",
+        "/credentialSubject/degree/major": "Text"
+      },
+      "classification": ""
+    },
+    "overlays": [
+      {
+        "digest": "EMzAk6N2iI1K5EpS9YqU7WxTc8BvPq1RgFn0D4XyJwLz",
+        "type": "spec/overlays/meta/2.0.0",
+        "capture_base": "ECui6bAv2zzW2gMVQbKT3M7g2q4r6yWKf2Y2k9CDa8Nq",
+        "name": "University Degree Credential",
+        "description": "Academic degree credential issued by universities"
+      },
+      {
+        "digest": "EJqWh3K9fF8H2BmP6VnR4TxQz5YsLm8NcDk7A1UvGtIw",
+        "type": "spec/overlays/label/2.0.0",
+        "capture_base": "ECui6bAv2zzW2gMVQbKT3M7g2q4r6yWKf2Y2k9CDa8Nq",
+        "language": "en",
+        "attribute_labels": {
+          "/credentialSubject/degree/type": "Degree Type",
+          "/credentialSubject/degree/name": "Degree Name",
+          "/credentialSubject/degree/degreeType": "Degree Classification",
+          "/credentialSubject/degree/major": "Major"
+        }
+      },
+      {
+        "digest": "EKpXi4L0gG9I3CnQ7WoS5UyRa6ZtNo9OdEl8B2VwHuJx",
+        "type": "spec/overlays/label/2.0.0",
+        "capture_base": "ECui6bAv2zzW2gMVQbKT3M7g2q4r6yWKf2Y2k9CDa8Nq",
+        "language": "fr",
+        "attribute_labels": {
+          "/credentialSubject/degree/type": "Type de diplôme",
+          "/credentialSubject/degree/name": "Nom du diplôme",
+          "/credentialSubject/degree/degreeType": "Classification du diplôme",
+          "/credentialSubject/degree/major": "Spécialisation"
+        }
+      },
+      {
+        "digest": "ELrYj5M1hH0J4DoR8XpT6VzSb7AuOp0QeFm9C3WxIvKy",
+        "type": "spec/overlays/information/2.0.0",
+        "capture_base": "ECui6bAv2zzW2gMVQbKT3M7g2q4r6yWKf2Y2k9CDa8Nq",
+        "language": "en",
+        "attribute_information": {
+          "/credentialSubject/degree/type": "The type of academic degree awarded",
+          "/credentialSubject/degree/name": "The full official name of the degree",
+          "/credentialSubject/degree/degreeType": "Classification level (e.g., Undergraduate, Graduate)",
+          "/credentialSubject/degree/major": "The primary field of study"
+        }
+      },
+      {
+        "digest": "ENaZl7O3jJ2L6FqT0ZrV8XyUd9CwRs2ShGo1E5YzKxMa",
+        "type": "spec/overlays/sensitive/2.0.0",
+        "capture_base": "ECui6bAv2zzW2gMVQbKT3M7g2q4r6yWKf2Y2k9CDa8Nq",
+        "attributes": [
+          "/credentialSubject/degree/name"
+        ]
+      }
+    ]
+  }
+}
+          </pre>
 
+          <p>
+Implementers use the bundle to generate appropriate user interfaces, select
+language-specific labels, apply format specifications, and ensure consistent
+rendering across applications. A [=verifiable credential=] MAY include both an
+`OverlayRenderMethod` and a `TemplateRenderMethod`; in that case, the overlay
+package can supply labels and metadata while a template supplies layout.
+          </p>
+        </section>
+      </section>
 
     <!-- OpenAttestationEmbeddedRenderer -->
     <section>
@@ -1370,6 +1657,53 @@ <h3>Render (TemplateRenderMethod)</h3>
       </p>
     </section>
 
+    <section>
+      <h3>Render (OverlayRenderMethod)</h3>
+
+      <p>
+The following algorithm applies when `renderMethod.type` is
+`OverlayRenderMethod` and `renderMethod.renderSuite` is `oca-bundle-v2`.
+      </p>
+
+      <ol class="algorithm">
+        <li>
+Let `vc` be the [=verifiable credential=] to render.
+        </li>
+        <li>
+Let `renderMethod` be the chosen `renderMethod` entry where
+`renderMethod.type` is `OverlayRenderMethod` and
+`renderMethod.renderSuite` is `oca-bundle-v2`.
+        </li>
+        <li>
+If `renderMethod.bundle` is a [=string=], let `bundleUrl` be its value.
+Otherwise, if `renderMethod.bundle` is a [=map=], let `bundleUrl` be the value
+of `renderMethod.bundle.id`. Otherwise, if `renderMethod.id` is present, fetch
+it and let the result be the `renderMethod` value; then repeat this step.
+        </li>
+        <li>
+Fetch `bundleUrl` and parse the response as JSON. If
+`renderMethod.bundle.digestMultibase` is present, verify the response against
+that digest prior to use.
+        </li>
+        <li>
+If `renderMethod.renderProperty` is present, let `vcData` be the result of
+applying the `selectJsonLd` algorithm [[VC-DI-ECDSA]] to `vc` using the JSON
+Pointer values in `renderMethod.renderProperty`. Otherwise, let `vcData` be
+`vc`.
+        </li>
+        <li>
+For each attribute name in the OCA capture base, resolve the name as a JSON
+Pointer against `vcData` from the document root. If a pointer does not resolve,
+the processor MAY ignore that attribute or report an error.
+        </li>
+        <li>
+Apply overlays from the bundle (for example, label, information, format, and
+sensitive overlays) to produce presentation metadata for rendering `vcData`.
+The specifics of each overlay type are defined in [[[OCA]]].
+        </li>
+      </ol>
+    </section>
+
   </section>
 
     <section class="appendix informative">