Verifiable Credential Rendering Methods

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, OPTIONAL, RECOMMENDED, and REQUIRED in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A conforming render method is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections 2. Data Model and 3. Algorithms of this document MUST be enforced.

A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming render method. Conforming processors MUST produce errors when non-conforming documents are consumed.

This document also contains examples that contain JSON and JSON-LD content. Some of these examples contain characters that are invalid JSON, such as inline comments (//) and the use of ellipsis (...) to denote information that adds little value to the example. Implementers are cautioned to remove this content if they desire to use the information as valid JSON or JSON-LD.

The renderMethod property is a reserved extension point in the Verifiable Credentials Data Model specification [VC-DATA-MODEL-2.0]. An issuer can utilize this property in a verifiable credential to express one or more preferred render methods.

renderMethod

The value of the renderMethod property MUST specify one or 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.

When an issuer desires to specify template-based rendering instructions for a verifiable credential, they MAY add a renderMethod property that uses the data model described below.

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"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "validFrom": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "svg-mustache",
    "template": {
      "id": "https://example.edu/credential-templates/BachelorDegree",
      "mediaType": "image/svg+xml",
      "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR",
      "renderProperty": [
        "/issuer", "/validFrom", "/credentialSubject/degree/name"
      ]
    }
  }
  
}

In the example above, the issuer has provided a Mustache-based SVG rendering template for a Bachelor's degree that will be filled in with specific information from the verifiable credential listed in renderProperty.

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "svg-mustache",
    // the SVG file is embedded in the VC
    "template": "data:image/svg+xml;base64,Qjei89...3jZpW"
  }
}

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "svg-mustache",
  "template": {
    // this SVG file is fetched from the Web
    "id": "https://degree.example/credential-templates/bachelors",
    "mediaType": "image/svg+xml",
    "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
  }
}

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

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "pdf-mustache",
    // this PDF file is embedded in the VC
    "template": "data:application/pdf;base64,k309SK...pwK83b"
  }
}

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "pdf-mustache",
  "template": {
    // this PDF file is fetched from the Web
    "id": "https://degree.example/bachelors.pdf",
    "mediaType": "application/pdf",
    "digestMultibase": "zQmznFCwYxApG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9"
  }
}

{
...
"renderMethod": {
  // this render method is fetched from the Web
  "id": "https://degrees.example/bachelors-pdf.jsonld",
  "type": "TemplateRenderMethod",
  "renderSuite": "pdf-mustache",
  "digestMultibase": "zQmEu5h6JqWAPdhyxmz2dRerWC85Wg6wFl9znFCwYxApG270"
}

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

OpenAttestationEmbeddedRenderer is used by an issuer to render a verifiable credential. The verifiable credential is rendered in HTML within an embedded <iframe> through a Template Renderer website referenced in the document. This arrangement allows for interactive selective disclosure using OpenAttestationMerkleProofSignature2018.

The Template Renderer is a web application embedded in an iframe. It renders verifiable credentials based on selected templates and must listen for specific messages from the Host application to facilitate the rendering process.

There currently exists a number of OpenAttestationEmbeddedRenderer issuers and decentralized renderer implementations.

When an issuer desires to specify an embedded rendering instructions for a verifiable credential, they MAY add a renderMethod property that uses the data model described below.

The data model shown above is expressed in a verifiable credential in the example below.

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://schemata.openattestation.com/com/openattestation/4.0/alpha-context.json"
  ],
  "type": ["VerifiableCredential", "OpenAttestationCredential"],
  "validFrom": "2021-03-08T12:00:00+08:00",
  "name": "Republic of Singapore Driving Licence",
  "issuer": {
    "id": "did:ethr:0xB26B4941941C51a4885E5B7D3A1B861E54405f90",
    "type": "OpenAttestationIssuer",
    "name": "Government Technology Agency of Singapore (GovTech)",
    "identityProof": { "identityProofType": "DNS-DID", "identifier": "example.openattestation.com" }
  },
  "credentialSubject": {
    "id": "urn:uuid:a013fb9d-bb03-4056-b696-05575eceaf42",
    "type": ["DriversLicense"],
    "name": "John Doe",
    "address": "123 Choa Chu Kang Road, Singapore 123456",
    "licenses": [
      {
        "class": "3",
        "description": "Motor cars with unladen weight <= 3000kg",
        "effectiveDate": "2013-05-16T00:00:00+08:00"
      },
      {
        "class": "3A",
        "description": "Motor cars with unladen weight <= 3000kg",
        "effectiveDate": "2013-05-16T00:00:00+08:00"
      }
    ]
  },
  "renderMethod": [{
    "id": "https://demo-renderer.opencerts.io",
    "type": "OpenAttestationEmbeddedRenderer",
    "rendererName": "GOVTECH_DEMO"
  }]
}

The verifiable credential specifies a decentralized renderer at https://demo-renderer.opencerts.io, using the template named GOVTECH_DEMO.

The decentralized renderer can support different templates that can provide different views of the verifiable credentials. Below are two renderings of the same verifiable credential using different templates.

2.3.1 Action API

The Host is the application that displays the document with the help of the Template Renderer. The Template Renderer MUST be a web application embedded within an iframe specified by renderMethod.id. It MUST communicate with the Host application using postMessage API to perform actions.

All actions follow the same structure. They are composed of type and payload:

1. type indicates the kind of action being executed, for instance, RENDER_DOCUMENT means rendering a document. The type of an action is mandatory.
2. payload indicates optional data associated to the type, for instance, the content of the document to render.

An open source reference implementation is available on GitHub.

The interaction between the Host and the Template Renderer is illustrated in the following diagram.

2.3.1.1 Host-to-Frame Actions

When the iframe is first displayed, the host sends commands to the iframe to render the document. The 4 types of actions supported are described below.

type	payload	action
GET_TEMPLATES	{ type: "GET_TEMPLATES" }	Obtain a list of templates supported by the renderer for the given document. The list of templates is returned from UPDATE_TEMPLATES call from the iframe.
SELECT_TEMPLATE	{ type: "SELECT_TEMPLATE", payload: "CUSTOM_TEMPLATE" }	Select the template to be used for rendering. It should be from the list returned by GET_TEMPLATES. If not found, a default template is used.
RENDER_DOCUMENT	{ type: "RENDER_DOCUMENT", payload: { document: { credentialSubject: ..., renderMethod: ... } } }	Render the verifiable credential inside the IFRAME using the selected template. Document is JSON object form of the verifiable credential.
PRINT	{ type: "PRINT" }	MUST show the print dialog so the contents of the IFRAME can be printed.

2.3.1.2 Frame-to-Host Actions

These are used by the iframe to update the host to make adjustments on formatting, or selective redaction.

type	payload	action
OBFUSCATE	{ type: "OBFUSCATE", payload: "a[0].b.c", }	This is used for selective redaction. The Host is informed of the path of the field that has been obfuscated so that the host can create an updated version of the document with the selected field obfuscated.
UPDATE_HEIGHT	{ type: "UPDATE_HEIGHT", payload: 150, }	Notify the Host of the height of the embedded iframe in pixels so the Host can adjust the size on the browser.
UPDATE_TEMPLATES	{ type: "UPDATE_TEMPLATES", payload: [ { id: "template1", label: "template1", }, { id: "template2", label: "template2", } ] }	Notify the Host of the list of template names that are usable from RENDER_METHOD, or GET_TEMPLATES calls.

The following algorithm is used to transform the SVG image template into the final SVG image that is displayed. The inputs to the algorithm are the verifiable credential (verifiableCredential) and the SVG image source code (svgImage). The output is a SVG image.

1. Generate a map, replacementMap, by finding all strings in svgImage that start with {{ (double open braces) and end with }} (double close braces). For each string, templateKey, that is found:
   1. Generate another string, templateValue, by evaluating the value of templateKey (without the opening or closing braces) using the JSON Pointer [RFC6901] algorithm with the verifiableCredential as input to the algorithm. If the evaluation is null, set templateValue to the empty string.
   2. Set a key in replacementMap by using templateKey and associate it with templateValue.
2. For every key in replacementMap, replace each corresponding string in svgImage that matches the key with the associated value in the replacementMap.