-When an [=issuer=] desires to specify template-based rendering instructions +When an [=issuer=] desires to specify rendering instructions for a [=verifiable credential=], they MAY add a `renderMethod` property that uses -the data model described below. +the data model described below. The concrete rendering behavior is determined +by the render suite named in the `renderSuite` property. +Each render suite defines which of the properties below it uses; see the +individual render suite sections.
| type | -A REQUIRED [=string=] that MUST be the value `TemplateRenderMethod`. +A REQUIRED [=string=] that MUST be the value `SuiteRenderMethod`. |
| renderSuite | -A REQUIRED [=string=] that identifies the algorithms that are used for -generating the concrete rendering. +A REQUIRED [=string=] that identifies the render suite, that is, the set of +algorithms used for generating the concrete rendering. The value is a plain +JSON string and is compared using exact, case-sensitive matching. This +specification defines the values `summary`, `html`, and `nfc`. Implementations +MUST ignore any `renderMethod` entry whose `renderSuite` value they do not +recognize or support. |
+Where render suite values are registered (a registry section in this +specification, the VC Specs Directory, or both), and whether extension +suite values are plain strings or URLs, is still under discussion. +
+-The `card` render suite uses JSON templates to transform a +The `summary` 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 +enables wallets to display credentials in a responsive 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 +this method can render the standardized JSON output in their own UI designs, allowing credentials to be displayed even when a wallet doesn't natively support a specific credential type.
The template and the rendered output are both JSON objects that share a -single definition, the card object, given below. String values in the +single definition, the summary object, given below. String values in the template can be JSON pointer strings (as specified in [[[RFC6901]]]) that reference values in the [=verifiable credential=]. When processing the template, JSON pointer strings are evaluated against the credential data and replaced with the resolved values. Both the template and the resulting -output MUST conform to the card object definition. Compound data across +output MUST conform to the summary object definition. Compound data across multiple fields is not supported; each field references a single JSON pointer.
-+The `summary` render suite uses the common render method properties as follows: +
+| Property | +Use in this suite | +
|---|---|
| template | ++Provides the summary template, either embedded as a `data:` URL or referenced as +a map. The value MUST be, or dereference to, a JSON document that conforms to +the summary object definition in [[[#summary-object]]]. + | +
| renderProperty | ++Not used by this suite. The JSON pointer strings in the summary template +determine which properties of the [=verifiable credential=] are exposed. + | +
| outputPreference | ++MAY be provided. The `accessMode` and `style` preferences apply to the +display of the rendered summary. + | +
-A card object is a JSON object [[RFC8259]] with the members defined below. +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 [[[RFC6901]]]) that @@ -464,16 +516,16 @@
namedescriptionicontheme-A template SHOULD be validated against the card object definition above -before processing. A non-normative JSON Schema for card templates is -provided in [[[#card-template-json-schema]]]. +A template SHOULD be validated against the summary object definition above +before processing. A non-normative JSON Schema for summary templates is +provided in [[[#summary-template-json-schema]]].
- The following example shows a valid `card` template with JSON pointer + The following example shows a valid summary template with JSON pointer strings:
+ title="Example summary template">
{
"name": "/credentialSubject/degree/name",
"description": "University Degree Credential",
@@ -573,11 +625,11 @@ Card Examples
- The following example shows a valid `card` output: + The following example shows a valid summary output:
+ title="Example summary output">
{
"name": "Bachelor of Science and Arts",
"description": "University Degree Credential",
@@ -611,12 +663,12 @@ Card Examples
+ title="Basic usage of the 'summary' render suite">
{
...
"renderMethod": {
- "type": "TemplateRenderMethod",
- "renderSuite": "card",
+ "type": "SuiteRenderMethod",
+ "renderSuite": "summary",
// the JSON template is embedded in the VC
"template": "data:application/json;base64,eyJuYW1lIjogIi9jcmVkZW50aWFsU3ViamVjdC9kZWdyZWUvbmFtZSIsICJkZXNjcmlwdGlvbiI6ICJVbml2ZXJzaXR5IERlZ3JlZSBDcmVkZW50aWFsIiwgImZpZWxkcyI6IFt7ImxhYmVsIjogIkluc3RpdHV0aW9uIiwgInZhbHVlIjogIi9pc3N1ZXIifV19"
}
@@ -629,12 +681,12 @@ Card Examples
+ title="A remotely hosted JSON template for a summary render template">
{
...
"renderMethod": {
- "type": "TemplateRenderMethod",
- "renderSuite": "card",
+ "type": "SuiteRenderMethod",
+ "renderSuite": "summary",
"template": {
// this JSON template is fetched from the Web
"id": "https://degree.example/credential-templates/bachelors.json",
@@ -650,15 +702,15 @@ Card Examples
+ title="A remotely hosted 'summary' render method">
{
...
"renderMethod": {
// this render method is fetched from the Web
"id": "https://degrees.example/bachelors-card.jsonld",
"mediaType": "application/ld+json",
- "type": "TemplateRenderMethod",
- "renderSuite": "card",
+ "type": "SuiteRenderMethod",
+ "renderSuite": "summary",
"digestMultibase": "zQmG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9znFCwYxAp"
}
@@ -700,7 +752,7 @@ The `html` Render Suite
"notRendered": "should not appear"
},
"renderMethod": {
- "type": "TemplateRenderMethod",
+ "type": "SuiteRenderMethod",
"renderSuite": "html",
"renderProperty": [
"/issuer/name",
@@ -725,6 +777,42 @@ The `html` Render Suite
}
+ Use of Common Properties
+
+The `html` render suite uses the common render method properties as follows:
+
+ | Property | +Use in this suite | +
|---|---|
| template | ++Provides the HTML fragment, either embedded as a `data:` URL or referenced as +a map whose `id` dereferences to the fragment. + | +
| renderProperty | ++MAY be provided to limit the [=verifiable credential=] data passed to the +template. If absent, the entire [=verifiable credential=] is provided. + | +
| outputPreference | ++MAY be provided. The `style` `width` and `height` preferences apply to the +`iframe` hosting the template. + | +
Implementations MUST provide an environment that allows for JavaScript to safely render the HTML template using the filtered [=verifiable credential=] data. @@ -1027,7 +1115,7 @@
+The `nfc` render suite uses the common render method properties as follows: +
+| Property | +Use in this suite | +
|---|---|
| template | ++Provides the binary NFC payload, typically embedded as a `data:` URL. + | +
| renderProperty | ++MAY be provided to limit which [=verifiable credential=] data is transmitted +over the NFC connection. + | +
| outputPreference | ++Not generally used by this suite. + | +
- When processing a `card` template, the following steps MUST be + When processing a summary template, the following steps MUST be performed:
-The following JSON Schema implements the card object rules defined in -[[[#card-object]]], as they apply to card templates. This schema is +The following JSON Schema implements the summary object rules defined in +[[[#summary-object]]], as they apply to summary templates. This schema is non-normative.
+ title="JSON Schema for summary templates">
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",