+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.
+
+
+
+
Status of This Document
This section describes the status of this
+ document at the time of its publication. A list of current W3C
+ publications and the latest revision of this technical report can be found
+ in the
+ W3C standards and drafts index.
+
+This is an experimental specification and is undergoing regular revisions. It is
+not fit for production deployment.
+
Publication as a First Public Working Draft does not
+ imply endorsement by W3C and its Members.
+ This is a draft document and may be updated, replaced, or obsoleted by other
+ documents at any time. It is inappropriate to cite this document as other
+ than a work in progress.
+
+
+
+ This document was produced by a group
+ operating under the
+ W3C Patent
+ Policy.
+
+
+ W3C maintains a
+ public list of any patent disclosures
+ made in connection with the deliverables of
+ the group; that page also includes
+ instructions for disclosing a patent. An individual who has actual
+ knowledge of a patent that the individual believes contains
+ Essential Claim(s)
+ must disclose the information in accordance with
+ section 6 of the W3C Patent Policy.
+
+
+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.
+
+
+
1.1 Terminology
+
+
+
+The following terms are used to describe concepts in this specification.
+
+The act of limiting the amount of shared data strictly to the minimum
+necessary to successfully accomplish a task or goal.
+
+
decentralized identifier
+
+A portable URL-based identifier, also known as a DID,
+associated with an entity. These identifiers are most often used in a
+verifiable credential and are associated with subjects such that a
+verifiable credential itself can be easily ported from one
+credential repository to another without the need to reissue the credential.
+An example of a DID is did:example:123456abcdef.
+
+A verifiable, boolean assertion about the value of another attribute in a
+verifiable credential. These are useful in zero-knowledge-proof-style
+verifiable presentations because they can limit information disclosure.
+For example, if a verifiable credential contains an attribute
+for expressing a specific height in centimeters, a derived predicate
+might reference the height attribute in the verifiable credential
+demonstrating that the issuer attests to a height value meeting the
+minimum height requirement, without actually disclosing the specific height
+value. For example, the subject is taller than 150 centimeters.
+
+
digital signature
+
+A mathematical scheme for demonstrating the authenticity of a digital message.
+
+
entity
+
+Anything that can be referenced in statements as an abstract or concrete noun.
+Entities include but are not limited to people, organizations, physical things,
+documents, abstract concepts, fictional characters, and arbitrary text. Any
+entity might perform roles in the ecosystem, if it is capable of doing so. Note
+that some entities fundamentally cannot take actions, e.g., the string "abc"
+cannot issue credentials.
+
+
graph
+
+A set of claims, forming a network of information composed of subjects
+and their relationship to other subjects or data. Each claim is
+part of a graph; this is either explicit in the case of named graphs, or
+implicit for the default graph.
+
+The means for keeping track of entities across contexts. Digital
+identities enable tracking and customization of entity interactions
+across digital contexts, typically using identifiers and attributes. Unintended
+distribution or use of identity information can compromise privacy. Collection
+and use of such information should follow the principle of
+data minimization.
+
+
identity provider
+
+An identity provider, sometimes abbreviated as IdP, is a system
+for creating, maintaining, and managing identity information for
+holders, while providing authentication services to
+relying party applications within a federation or distributed network.
+In this case the holder is always the subject. Even if the
+verifiable credentials are bearer credentials, it is assumed the
+verifiable credentials remain with the subject, and if they are
+not, they were stolen by an attacker. This specification does not use this term
+unless comparing or mapping the concepts in this document to other
+specifications. This specification decouples the identity provider
+concept into two distinct concepts: the issuer and the holder.
+
+A graph associated with specific properties, such as
+verifiableCredential. These properties
+result in separate graphs that contain all claims defined in the
+corresponding JSON objects.
+
+A program, such as a browser or other Web client, that mediates the
+communication between holders, issuers, and verifiers.
+
+
validation
+
+The assurance that a claim from a specific issuer satisfies the
+business requirements of a verifier for a particular use. This
+specification defines how verifiers verify verifiable credentials and
+verifiable presentations.
+It also specifies that verifiers validate claims in verifiable
+credentials before relying on them. However, the means for such validation
+vary widely and are outside the scope of this specification. It is expected
+that verifiers will trust certain issuers for certain claims and
+apply their own rules to determine which claims in which credentials
+are suitable for use by their systems.
+
+
verifiable credential
+
+A verifiable credential is a tamper-evident credential that has authorship that
+can be cryptographically verified. Verifiable credentials can be used to build
+verifiable presentations, which can also be cryptographically verified.
+
+
verifiable data registry
+
+A role a system might perform by mediating the creation and verification
+of identifiers, keys, and other relevant data, such as
+verifiable credential schemas, revocation registries, issuer public keys,
+and so on, which might be required to use verifiable credentials. Some
+configurations might require correlatable identifiers for subjects. Some
+registries, such as ones for UUIDs and public keys, might just act as namespaces
+for identifiers.
+
+
verifiable presentation
+
+A verifiable presentation is a tamper-evident presentation encoded in such a way
+that authorship of the data can be trusted after a process of cryptographic
+verification. Certain types of verifiable presentations might contain data that
+is synthesized from, but do not contain, the original verifiable credentials
+(for example, zero-knowledge proofs).
+
+
verification
+
+The evaluation of whether a verifiable credential or verifiable
+presentation is an authentic and current statement of the issuer or
+presenter, respectively. This includes checking that: the credential (or
+presentation) conforms to the specification; the proof method is satisfied; and,
+if present, the status check succeeds. Verification of a credential does not
+imply evaluation of the truth of claims encoded in the credential.
+
+
verifier
+
+A role an entity performs by receiving one or more
+verifiable credentials, optionally inside a
+verifiable presentation for processing. Other specifications might refer
+to this concept as a relying party.
+
+
verification material
+
+ Information that could be a cryptographic public key or any other data
+ used to verify a proof.
+
+
URL
+
+A Uniform Resource Locator, as defined by [URL]. URLs can be dereferenced such
+that they result in a resource, such as a document. The rules for dereferencing,
+or fetching, a URL are defined by the URL scheme. This specification
+does not use the term URI or IRI because those terms have been deemed to be
+confusing to Web developers.
+
+
+
+
+
+
+
1.2 Conformance
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.
+
+
+
+
+
+
2. Data Model
+
+
+
+The following sections outline the data model that is used by this specification
+for rendering methods
+
+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 renderMethodtype
+definition.
+
+
+
+
+
2.2 TemplateRenderMethod
+
+
+
+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 OPTIONALstring that follows the URL Standard and, when fetched,
+dereferences to a render template.
+
+
+
+
type
+
+A REQUIREDstring that MUST be the value TemplateRenderMethod.
+
+
+
+
renderSuite
+
+A REQUIREDstring 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.
+
+An OPTIONALstring or 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 map, it MUST conform to the following
+rules:
+
+
+
+
Property
+
Description
+
+
+
+
+
id
+
+An REQUIREDstring that follows the URL Standard and, when fetched,
+dereferences to a template such as an SVG or PDF file.
+
+An OPTIONAL multibase-encoded Multihash of the template file. The multibase
+value MUST be u (base64url-nopad) and the multihash value MUST be SHA-2 with
+256-bits of output (0x12).
+
+
+
+
+
+
+
+
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.
+
+
+
+
+ Example 1: Usage of the render property by an issuer
+
+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.
+
+
+
2.2.1 The svg-mustache Render Suite
+
+
+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.
+
+
+
+
+ Example 2: Basic usage of the svg-mustache render suite
+
{
+ ...
+ "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.
+
+
+
+
+ Example 3: A remotely hosted SVG file for an SVG render template
+
{
+...
+"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:
+
+
+
+
+ Example 4: A remotely hosted SVG render method
+
{
+...
+"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"
+}
+
+
+
+
+
2.2.2 The pdf-mustache Render Suite
+
+
+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.
+
+
+
+
+ Example 5: Basic usage of the pdf-mustache render suite
+
{
+ ...
+ "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.
+
+
+
+
+ Example 6: Remotely hosted PDF file for a PDF rendering template
+
{
+...
+"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:
+
+
+
+
+ Example 7: Remotely hosted PDF rendering template
+
{
+...
+"renderMethod": {
+ // this render method is fetched from the Web
+ "id": "https://degrees.example/bachelors-pdf.jsonld",
+ "type": "TemplateRenderMethod",
+ "renderSuite": "pdf-mustache",
+ "digestMultibase": "zQmEu5h6JqWAPdhyxmz2dRerWC85Wg6wFl9znFCwYxApG270"
+}
+
+
+
+
+
2.2.3 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"]
+ }
+
+}
+
+
+
+
+
+
2.3 OpenAttestationEmbeddedRenderer
+
+
+
+ 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.
+
+
+
+
+ Example 9: Usage of the renderMethod property by an issuer
+
+ 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:
+
+
+
+ type indicates the kind of action being executed, for instance,
+ RENDER_DOCUMENT means rendering a document. The type of an action is
+ mandatory.
+
+
+ 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.
+
+ 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.
+
+ 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.
+
+ Notify the Host of the list of template names that are usable from
+ RENDER_METHOD, or GET_TEMPLATES calls.
+
+
+
+
+
+
+
+
+
+
3. Algorithms
+
+
+
+The following sections outline the algorithms that is used by this specification
+for rendering methods.
+
+
+
3.1 Render (TemplateRenderMethod)
+
+
+
+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.
+
+
+
+
+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:
+
+
+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.
+
+
+Set a key in replacementMap by using templateKey and associate it with
+templateValue.
+
+
+
+
+For every key in replacementMap, replace each corresponding
+string in svgImage that matches the key with the associated value in the
+replacementMap.
+
+
+
+
+
+
+
4. Security Considerations
+
+
+
Issue 1: Summary of Security Considerations
+The list of security considerations listed below need to be converted into
+sections:
+
+
+
+
+If a cryptographic hash for a display template isn't provided, you can't know
+if it has been tampered with since issuance. There are good reasons an issuer
+might allow for this, such as being able to update the look/feel of a
+long-lived credential over time.
+
+
+If a cryptographic hash for a display template is provided, implementations
+that don't check it run the risk of display attacks, which might sound benign,
+but they aren't; Verifiers might use verifiable displays to show what the
+issuer intended, and if those displays don't check the cryptographic hash,
+they might show the wrong info to an individual checking the credential on
+the verifiable display.
+
+
+Fetching resources from external locations can be used as a denial-of-service
+attack vector where the resource is never served, or served at a very slow pace.
+
+
+
+
+
+
5. Privacy Considerations
+
+
+
Issue 2: Summary of Privacy Considerations
+The list of privacy considerations listed below need to be converted into
+sections:
+
+
+
+
+An issuer could use a rendering method id to track individuals. These
+values should be aggressively cached client-side, or looked up using a
+mixnet or proxy service.
+
+
+
+
+
+
6. Internationalization Considerations
+
+
+
Issue 3: Summary of Internationalization Considerations
+The list of internationalization considerations listed below need to be
+converted into sections:
+
+
+
+
+Are we allowed to use media queries to detect language and provide different
+displays based on language?
+
+ 
+ 
+