This specification describes mechanisms that can be used to represent a Verifiable Credential through a visual, auditory, or haptic medium. It covers rendering a Verifiable Credential to a physical document, digital image, screen reader, or braille output.
This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.
Rendering methods can be used when the [=issuer=] has a specific way that they want to express a [=verifiable credential=] to an observer through a visual, auditory, or haptic mechanism. For example, an [=issuer=] of an employee badge credential might want to include rich imagery of their corporate logo and specific placement of employee information in specific areas of the badge. They might also want to provide an audio read out of the important aspects of the badge for individuals that have accessibility needs related to their eyesight.
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 and 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 following sections outline the data model that is used by this specification for rendering methods
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.
When an [=issuer=] desires to specify template-based rendering instructions for a [=verifiable credential=], they MAY add a `render` property that uses the data model described below.
Property | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
id | An OPTIONAL [=string=] that follows the [[[URL]]] and, when fetched, dereferences to a render template. | ||||||||
type | A REQUIRED [=string=] that MUST be the value `TemplateRenderMethod`. | ||||||||
renderSuite | A REQUIRED [=string=] that identifies the algorithms that are used for generating the concrete rendering. | ||||||||
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 involved description than `name` of when the particular rendering 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 shared when the render method is used. | ||||||||
template |
An OPTIONAL [=string=] or [=ordered map|map=] that provides the template that
will be used to perform the rendering. If the value is a [=string=], it MUST be
a URL. If the value is a [=ordered map|map=], it MUST conform to the following
rules:
|
||||||||
digestMultibase | An OPTIONAL multibase-encoded Multihash of the 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"
],
"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`.
The `svg-mustache` render suite uses the Mustache templating language to modify an SVG file, which is then used to render a visual representation of the [=verifiable credential=].
In the example below, a fully embedded SVG file is used as the rendering template.
{ ... "renderMethod": { "type": "TemplateRenderMethod", "renderSuite": "svg-mustache", // the SVG file is embedded in the VC "template": "data:image/svg+xml;base64,Qjei89...3jZpW" } }
The next example links to the SVG file on the Web and secures it against modification by using the `digestMultibase` property.
{ ... "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" } }
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-svg.jsonld", "mediaType": "application/ld+json", "type": "TemplateRenderMethod", "renderSuite": "svg-mustache", "digestMultibase": "zQmG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9znFCwYxAp" }
The `pdf-mustache` render suite uses the Mustache templating language to modify a PDF file, which is then used to render a visual representation of the [=verifiable credential=].
In the example below, a fully embedded PDF file is used as the rendering template.
{ ... "renderMethod": { "type": "TemplateRenderMethod", "renderSuite": "pdf-mustache", // this PDF file is embedded in the VC "template": "data:application/pdf;base64,k309SK...pwK83b" } }
The next example links to the PDF file on the Web and secures it against modification by using the `digestMultibase` property.
{ ... "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" } }
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-pdf.jsonld", "type": "TemplateRenderMethod", "renderSuite": "pdf-mustache", "digestMultibase": "zQmEu5h6JqWAPdhyxmz2dRerWC85Wg6wFl9znFCwYxApG270" }
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"] } }
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.
Property | Description |
---|---|
id | A URL that locates a website that implements the OpenAttestationEmbeddedRenderer Action API. |
type | The `type` property MUST be `OpenAttestationEmbeddedRenderer`. |
renderName | Name of the template used by the website specified by `id` to render the document. A different template can be used for the decentralized renderer to present a different HTML view of the verifiable credential. |
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.
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`:
An open source reference implementation is available on GitHub.
The interaction between the Host and the Template Renderer is illustrated in the following diagram.
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. |
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 sections outline the algorithms that is used by this specification for rendering methods.
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.
The list of security considerations listed below need to be converted into sections:
The list of privacy considerations listed below need to be converted into sections:
The list of internationalization considerations listed below need to be converted into sections: