Verifiable Credential Rendering Methods v1.0

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 JavaScript Object Notation (JSON) Pointer) 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 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.

<html>
  <head>
    <meta http-equiv="content-security-policy" content="frame-src 'none'">
  </head>
  <body>
    <iframe id="renderer" sandbox="allow-scripts allow-modals" srcdoc=""></iframe>
  </body>
</html>

<div>
  <script>
    document.addEventListener('DOMContentLoaded', (event) => {
      console.log('running template render script');

      // display credential as JSON as an example renderer; anything
      // could be done here instead, including mustache/other-style
      // template processing to generate the HTML for display

      // FIXME: determine best name/location for the datablock/script tag
      const credential = JSON.parse(document.querySelector(
        'head > script[name="credential"]').innerHTML);

      document.querySelector('#credentialSubject-name').innerText =
        credential.credentialSubject.name;
      document.querySelector('#issuer-name').innerText =
        credential.issuer.name;

      // TBD: signal to host that rendering is complete
      window.renderMethodReady();
    });
  </script>
  <style>
    h1 {
      color: blue;
    }
  </style>

  <h1 id="credentialSubject-name"></h1>
  <p>Issued by: <span id="issuer-name"></span></p>
</div>

<html>
  <head>
    <meta http-equiv="content-security-policy" content="default-src data: 'unsafe-inline'">
    <script name="credential" type="application/vc">${JSON.stringify(credential)}</script>
  </head>
  <body>${template}</body>
</html>

<html>
  <head>
    <meta http-equiv="content-security-policy" content="default-src 'none' data: 'unsafe-inline'">

<!-- The credential data block injected into the Wrapper Code. -->
<script name="credential" type="application/vc">{
  "@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"
  }
}</script>
<!-- End credential data block -->

</head>
<body>

<!-- The template HTML injected into the Wrapper Code. -->
<div>
  <script>
    console.log('running template render script');

    // display credential as JSON as an example renderer; anything
    // could be done here instead, including mustache/other-style
    // template processing to generate the HTML for display

    // FIXME: determine best name/location for the datablock/script tag
    const credential = JSON.parse(document.querySelector(
      'head > script[name="credential"]').innerHTML);

    document.querySelector('#credentialSubject-name').innerText =
      credential.credentialSubject.name;
    document.querySelector('#issuer-name').innerText =
      credential.issuer.name;

    // TBD: signal to host that rendering is complete
    window.renderMethodReady()
  </script>
  <style>
    h1 {
      color: blue;
    }
  </style>

  <h1 id="credentialSubject-name"></h1>
  <p>Issued by: <span id="issuer-name"></span></p>
</div>
<!-- End template HTML -->

  </body>
</html>

// a promise that resolves when the rendering is ready (or rejects if it
// fails); can be used to show the display or an error instead
let resolveRender;
let rejectRender;
const readyPromise = new Promise((resolve, reject) => {
  resolveRender = resolve;
  rejectRender = reject;
});

// Setup communication channel for use by the template code in the iframe
renderer.onload = () => {
  // create a MessageChannel; transfer one port to the iframe
  const channel = new MessageChannel();
  // start message queue so messages won't be lost while iframe loads
  channel.port1.start();
  // handle `ready` message
  channel.port1.onmessage = function ready(event) {
    if(event.data === 'ready') {
      // unhide the iframe because it's ready
      resolveRender();
    } else {
      rejectRender(new Error(event.data?.error?.message));
    }
    channel.port1.onmessage = undefined;
  };
  // send "start" message; send `port2` to iframe for return communication
  renderer.contentWindow.postMessage('start', '*', [channel.port2]);
};

// setup event responses to ready or error
// NOTE: this section is idiosyncratic to the Wallet/Renderer's UX needs
readyPromise.then(() => {
  console.log('rendering ready');
  const renderer = document.getElementById('renderer');
  renderer.hidden = false;
}).catch(err => {
  const errorMessage = document.getElementById('error-message');
  errorMessage.style.display = 'block';
  errorMessage.innerText = 'Rendering failed: ' + err.message;
  console.error('rendering failed', err);
});

// add promise that will resolve to the communication port from
// the parent window
const portPromise = new Promise(resolve => {
  window.addEventListener('message', function start(event) {
    if(event.data === 'start' && event.ports?.[0]) {
      window.removeEventListener('message', start);
      resolve(event.ports[0]);
    }
  });
});

// attach a function to the window for the template to call when
// it's "ready" (or that an error occurred) that will send a message
// to the parent so the parent can decide whether to show the iframe
window.renderMethodReady = function(err) {
  portPromise.then(port => port.postMessage(
    !err ? 'ready' : {error: {message: err.message}}));
};

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"]
}
...
}

The host page MUST create an iframe element to host the HTML template. The host page MUST set the sandbox attribute on the iframe to allow-scripts to prevent navigation and top-level access.

1. Let vc be the verifiable credential to be rendered.
2. Let renderMethod be the chosen renderMethod property in vc where renderMethod.type is TemplateRenderMethod and renderMethod.renderSuite is html.
3. If renderMethod.template is a string, then let template be the value of renderMethod.template.
4. If renderMethod.template is a map, then let template be the result of fetching the URL in renderMethod.template.id.

The host page MUST filter the verifiable credential vc to only include the properties specified in renderMethod.renderProperty, if it is present. If renderMethod.renderProperty is not present, the entire verifiable credential is used.

This filtering MUST be done by applying the selectJsonLd algorithm defined in Section 3.4.13 selectJsonLd of the Data Integrity ECDSA Cryptosuites v1.0 specification [VC-DI-ECDSA] to the JSON Pointer [RFC6901] values present in renderMethod.renderProperty.

The host page MUST create the wrapper code by embedding the filtered verifiable credential and the HTML template into the wrapper code template defined above.

1. Let wrapperCode be an HTML Document with <meta http-equiv="Content-Security-Policy" content="default-src data: 'unsafe-inline'"> in the <head>.
2. Let datablock be an HTML Data Block with a type of application/vc.
3. Set the contents of datablock to be the filtered verifiable credential in stringified JSON format.
4. Insert datablock into the <head> of wrapperCode.
5. Insert the value of template into the <body> of wrapperCode.

The host page MUST set the srcdoc attribute of the iframe to the resulting wrapper code.

1. Set the srcdoc attribute of the iframe to the stringified HTML of wrapperCode.

The host page MUST setup a communication channel with the wrapper code to receive ready and error messages as described above.

1. Let renderPromise be a new Promise that:
   1. On resolve, can be used to display the iframe to the user.
   2. On reject, display the error message to the user.
2. In the onload event of the iframe:
   1. Let channel be a new MessageChannel.
   2. Create and start a new port1 listener on channel that listens for a ready message from the code in template now injected into the iframe via wrapperCode.
   3. In the port1 listener, if a ready message is received, resolve renderPromise. If an error message is received, reject renderPromise with the error message.
   4. Use postMessage to send port2 of channel to the iframe content window.

The host page SHOULD use the renderPromise to determine when rendering is complete or if there was an error during rendering.

The wrapper code MUST setup to receive communication from the host page via the MessageChannel and provide the window.renderMethodReady method for use by the template code.

1. In the window.onload event...
   1. Let port be the MessagePort received from the host page via the message event.
   2. Create window.renderMethodReady function that...
      1. If called with no arguments, sends a ready message to the host page via port.
      2. If called with an Error argument, sends an error message to the host page via port with the error message.