Verifiable Credential Rendering Methods v1.0

The summary render suite uses the common render method properties as follows:

A summary object is a JSON object [ RFC8259 ] with the members defined below. The same definition applies to the template and to the rendered output. In a template, the value of any member defined as a string MAY instead be a JSON pointer string (starting with / , as specified in JavaScript Object Notation (JSON) Pointer ) that references a value in the verifiable credential , except where noted for the label and value members of field objects. In the rendered output, every JSON pointer has been replaced by its resolved value.

name

A REQUIRED string containing the display name for the credential summary.

description

A REQUIRED string containing the description text for the credential summary.

icon

An OPTIONAL string containing a URL or data: URL [ RFC2397 ] for an icon or image to display on the summary.

theme

An OPTIONAL color theme object with the following members:

primaryColor

An OPTIONAL string containing the primary color for backgrounds and highlights.

accentColor

An OPTIONAL string containing the accent color for highlights and emphasis.

fields

A REQUIRED array of custom data fields, in display order. Each field is an object with the following members:

label

A REQUIRED string containing the field label. In a template, the label MUST be a literal string; a JSON pointer is not allowed here.

value

A REQUIRED string containing the field value. In a template, the value MUST be a JSON pointer string (for example, "/issuer" ).

language

An OPTIONAL language tag (as specified in Tags for Identifying Languages ) indicating the language of the field's label and/or value.

direction

An OPTIONAL direction tag (as specified in Strings on the Web: Language and Direction Metadata ) indicating the text direction of the field's label and/or value.

validFrom

An OPTIONAL ISO 8601 date string indicating when the credential becomes valid.

validUntil

An OPTIONAL ISO 8601 date string indicating when the credential ceases to be valid.

A template SHOULD be validated against the summary object definition above before processing. A non-normative JSON Schema for summary templates is provided in C. Summary Template JSON Schema .

The following example shows a valid summary template with JSON pointer strings:

{
  "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"
}

The following example shows a valid summary output:

{
  "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, the JSON template is embedded directly in the verifiable credential as a data: URL [ RFC2397 ].

{
  ...
  "renderMethod": {
    "type": "SuiteRenderMethod",
    "renderSuite": "summary",
    // 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": "SuiteRenderMethod",
  "renderSuite": "summary",
  "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": "SuiteRenderMethod",
  "renderSuite": "summary",
  "digestMultibase": "zQmG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9znFCwYxAp"
}

The html render suite uses the common render method properties as follows:

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.

The environment MUST also expose to the template code all internationalization and accessibility settings that are available in the user's environment. This allows a template to honor the language, text size, contrast, and motion preferences that an individual has already expressed to their user agent or operating system. Examples of such settings include those reflected in CSS, such as the rem unit and media queries like prefers-contrast , prefers-reduced-motion , and forced-colors , as well as those available to JavaScript, such as the locale information provided by Intl and Navigator.language .

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 .

A sandboxed iframe meets the internationalization and accessibility requirements above by default. The sandbox and CSP restrictions described in this section do not interfere with CSS media queries or with JavaScript APIs such as Intl and Navigator.language . Alternate rendering environments for the html render suite are possible, such as a WebView on a mobile platform.

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.

<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}}));
};

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 static render suite uses the common render method properties as follows: