The `card` Render Suite

The `card` render suite uses JSON templates to transform a [=verifiable credential=] into a standardized data display format. This format enables wallets to display credentials in a responsive card layout with key data highlighted and configurable additional fields. Wallets that implement this method can render the standardized JSON output in their own card UI designs, allowing credentials to be displayed even when a wallet doesn't natively support a specific credential type.

The template is a JSON object that matches the `card` output structure. String values in the template can be JSON pointer strings (as specified in [[[RFC6901]]]) that reference fields in the [=verifiable credential=]. When processing the template, JSON pointer strings are evaluated against the credential data and replaced with the resolved values. The template MUST conform to the JSON template schema defined below, and the resulting output MUST conform to the `card` output schema. Compound data across multiple fields is not supported; each field references a single JSON pointer.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "description", "fields"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Display name as a literal string or JSON pointer (e.g., \"/credentialSubject/degree/name\")"
    },
    "description": {
      "type": "string",
      "description": "Description as a literal string or JSON pointer"
    },
    "icon": {
      "type": "string",
      "description": "Icon URL/data URI as a literal string or JSON pointer"
    },
    "theme": {
      "type": "object",
      "properties": {
        "primaryColor": {
          "type": "string",
          "description": "Primary color as a literal string or JSON pointer"
        },
        "accentColor": {
          "type": "string",
          "description": "Accent color as a literal string or JSON pointer"
        }
      },
      "additionalProperties": false
    },
    "fields": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["label", "value"],
        "properties": {
          "label": {
            "type": "string",
            "description": "Field label (MUST be a literal string, not a JSON pointer)"
          },
          "value": {
            "type": "string",
            "pattern": "^/",
            "description": "Field value as a JSON pointer string (MUST start with \"/\")"
          },
          "language": {
            "type": "string",
            "description": "Optional BCP 47 language tag for the field"
          }
        },
        "additionalProperties": false
      }
    },
    "validFrom": {
      "type": "string",
      "description": "Validity start date as a literal ISO 8601 date string or JSON pointer"
    },
    "validUntil": {
      "type": "string",
      "description": "Validity end date as a literal ISO 8601 date string or JSON pointer"
    }
  },
  "additionalProperties": false
}
            

{
  "name": "/credentialSubject/degree/name",
  "description": "University Degree Credential",
  "icon": "/credentialSubject/icon",
  "theme": {
    "primaryColor": "#1a5490",
    "accentColor": "/credentialSubject/theme/accentColor"
  },
  "fields": [
    {
      "label": "Institution",
      "value": "/issuer"
    },
    {
      "label": "Degree Type",
      "value": "/credentialSubject/degree/type"
    },
    {
      "label": "Issue Date",
      "value": "/validFrom"
    }
  ],
  "validFrom": "/validFrom",
  "validUntil": "/validUntil"
}
            

{
  "name": "Bachelor of Science and Arts",
  "description": "University Degree Credential",
  "icon": "https://example.edu/icons/degree.svg",
  "theme": {
    "primaryColor": "#1a5490",
    "accentColor": "#4a90e2"
  },
  "fields": [
    {
      "label": "Institution",
      "value": "Example University"
    },
    {
      "label": "Degree Type",
      "value": "BachelorDegree"
    },
    {
      "label": "Graduation Date",
      "value": "2010-05-15"
    }
  ],
  "validFrom": "2010-01-01T19:23:24Z",
  "validUntil": null
}
            

In the example below, a fully embedded JSON template is used as the rendering template. The template uses JSON pointer strings to reference credential data.

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "card",
    // the JSON template is embedded in the VC
    "template": "data:application/json;base64,eyJuYW1lIjogIi9jcmVkZW50aWFsU3ViamVjdC9kZWdyZWUvbmFtZSIsICJkZXNjcmlwdGlvbiI6ICJVbml2ZXJzaXR5IERlZ3JlZSBDcmVkZW50aWFsIiwgImZpZWxkcyI6IFt7ImxhYmVsIjogIkluc3RpdHV0aW9uIiwgInZhbHVlIjogIi9pc3N1ZXIifV19"
  }
}
          

The next example links to the JSON template on the Web and secures it against modification by using the `digestMultibase` property.

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "card",
  "template": {
    // this JSON template is fetched from the Web
    "id": "https://degree.example/credential-templates/bachelors.json",
    "mediaType": "application/json",
    "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
  }
}
          

The next example links to the rendering template on the Web and secures it using the `digestMultibase` property:

{
...
"renderMethod": {
  // this render method is fetched from the Web
  "id": "https://degrees.example/bachelors-card.jsonld",
  "mediaType": "application/ld+json",
  "type": "TemplateRenderMethod",
  "renderSuite": "card",
  "digestMultibase": "zQmG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9znFCwYxAp"
}
          

The `html` Render Suite

The `html` render suite allows template authors to provide an HTML template to render a [=verifiable credential=]. The HTML can be referenced remotely or via a `data:` URL as the value of either `template` or `template.id` (when the value of `template` is an object). JavaScript within the HTML fragment is responsible for rendering the filtered [=verifiable credential=] data provided via an HTML data block (i.e. `<script type="application/vc"></script>`) hosted in a sandboxed iframe alongside the HTML template.

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "type": [
    "VerifiableCredential",
    "NameCredential"
  ],
  "issuer": {
    "id": "did:example:1234",
    "name": "The Issuer"
  },
  "credentialSubject": {
    "name": "Example Name",
    "notRendered": "should not appear"
  },
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "html",
    "renderProperty": [
      "/issuer/name",
      "/credentialSubject/name"
    ],
    "template": {
      "id": "https://test.example/credential-templates/NameCredential.html",
      "mediaType": "text/html",
      "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
    },
    "outputPreference": {
      "accessMode": [
        "visual"
      ],
      "mediaType": "application/html",
      "style": {
        "width": "800px",
        "height": "800px"
      }
    }
  }
}
        

Implementations MUST provide an environment that allows for JavaScript to safely render the HTML template using the filtered [=verifiable credential=] data. Additionally, a [=host page=] SHOULD protect the privacy of any request made (for example, dereferencing `template.id`) by using Oblivious HTTP [[?RFC9458]] or other means of disassociating the requesting client from the requested origin by using a protecting relay.

The following terminology is used to describe this environment:

host page

Provides the secure environment for rendering the HTML template.

template code

The HTML fragment provided within or remotely referenced by the Render Method.

wrapper code

Code that wraps the HTML template to provide additional security restrictions and communication with the [=host page=].

At minimum, the environment MUST prevent navigation, loading of external content, and access to the [=host page=] in order to prevent tracking and other privacy harms.

Browser based implementations, for example, can provide such an environment using a combination of Content Security Policy [[CSP3]] restrictions on a [=host page=], sandboxing of an `iframe` hosting the HTML template, and wrapper code that wraps the HTML template to add additional CSP restrictions and provides ready and error event communication with the [=host page=].

graph TD
    subgraph Wallet's VC Rendering HTML
        direction LR
        A(VC) -- selectively disclosed --> B{VC subset datablock}
        subgraph "iframe[srcdoc] wrapper code"
            B{VC subset datablock}
            C[HTML/CSS/JS template from renderMethod]
        end
        C[HTML/CSS/JS template from renderMethod] --> D[renderMethodReady]
    end
          

Host Page

The [=host page=] (typically a Wallet or [=verifiable credential=] renderer) MUST prevent the HTML template from navigating the top-level browsing context, accessing external content, accessing the [=host page=], and loading any remote content.

If a [=host page=] is used, the following rules apply:

• The Content Security Policy (CSP) restrictions MUST include `frame-src 'none'`. This forces the use of `srcdoc` instead of `src` for iframes, which prevents the browser from loading the HTML template. In turn, this forces the [=host page=] code to preload remotely referenced template code and check the response against the related `digestMultibase` value prior to injecting the template into the [=wrapper code=].
• `sandbox="allow-scripts"` MUST be set on the `iframe` hosting the HTML template to prevent navigation and top-level access.

Template Code

The HTML [=template code=] referenced by the `template` property in the `renderMethod` MUST be an HTML fragment that contains the HTML, CSS, and JavaScript necessary to render the [=verifiable credential=]. The [=template code=] MUST NOT include any `<html>`, `<head>`, or `<body>` tags, as these will be provided by the [=wrapper code=].

Wrapper Code

The template HTML fragment MUST be wrapped in [=wrapper code=] that provides the data block containing the partial [=verifiable credential=] and adds an additional CSP policies to prevent navigation and external content loading. Specifically, the [=wrapper code=] MUST add the following CSP restrictions of `default-src data: 'unsafe-inline'` to prevent any network requests from being made by the [=template code=].

To complete the setup, the [=host page=] MUST inject the [=wrapper code=] (once populated with the [=verifiable credential=] and the [=template code=]) into the iframe's `srcdoc` attribute which will run any JavaScript contained in the [=wrapper code=] and [=template code=].

Ready and Error Events

The iframe created in the [=wrapper code=] MUST provide a communication channel to allow the template to notify the [=host page=] when rendering is complete or if there was an error during rendering. This can be accomplished using the `postMessage` API with a `MessageChannel` setup by the [=wrapper code=].

The JavaScript shown below would be added to the above [=host page=] to add an `onload` event to the iframe which sets up the `MessageChannel`. The [=host page=] also creates a `Promise` that resolves when a `ready` message is received from the [=wrapper code=] or rejects when an `error` message is received. The [=wrapper code=] also provides a `window.renderMethodReady` method for use by the template to notify the [=host page=] that rendering is complete or send back an error message.

With this setup, the template JavaScript can call `window.renderMethodReady()` to notify the [=host page=] that rendering is complete or call `window.renderMethodReady(new Error("error message"))` to notify the [=host page=] of an error.

Output Preferences

Rendering environment preferences MAY be provided within the Render Method. The purpose of this object is to provide suggested use, display, and intended access mode when rendering the provided template. An implementation SHOULD follow these preferences when provided.

The `outputPreference` object MAY contain any of the following properties:

The `style` object MAY contain any of the following properties:

The `nfc` Render Suite

The `nfc` render suite transmits a binary payload representing the [=verifiable credential=] over a wireless NFC connection.

In the example below, a fully embedded NFC payload is used as the rendering template, which only discloses the barcode identifier associated with the credential.

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "nfc",
  "name": "Tap to send",
  // the NFC payload is embedded
  "template": "data:application/octet-stream;base64,2QZkpQGDG...G8XJWnROcY4Biw",
  // only the barcode is transmitted over NFC
  "renderProperty": ["/credentialSubject/barcode"]
}
...
}