+OverlayRenderMethod is used by an [=issuer=] to link a [=verifiable credential=] +to an external package of presentation metadata—such as an Overlays Capture +Architecture (OCA) Bundle [[[OCA]]]—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. +
++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. +
+| Property | +Description | +||||||||
|---|---|---|---|---|---|---|---|---|---|
| id | ++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. + | +||||||||
| type | ++A REQUIRED [=string=] that MUST be the value `OverlayRenderMethod`. + | +||||||||
| renderSuite | ++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. + | +||||||||
| name | ++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. + | +||||||||
| description | ++An OPTIONAL human-readable [=string=] that provides a more detailed description +of the overlay-based rendering method and when it might be useful. + | +||||||||
| renderProperty | ++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. + | +||||||||
| bundle | +
+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:
+
|
+ ||||||||
| digestMultibase | ++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`). + | +
+The data model shown above is expressed in a [=verifiable credential=] in the +example below. +
+ +
+{
+ "@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"
+ }
+ },
+ "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"
+ }]
+}
+
+
+ +The `oca-bundle-v2` render suite refers to the Overlays Capture Architecture +(OCA) v2.0.0 +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. +
+ ++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. +
+ ++An example OCA Bundle structure for the credential above might look like: +
+ +
+{
+ "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"
+ ]
+ }
+ ]
+ }
+}
+
+ +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. +
++The following algorithm applies when `renderMethod.type` is +`OverlayRenderMethod` and `renderMethod.renderSuite` is `oca-bundle-v2`. +
+ +