§ Wallet Rendering

Specification Status: Strawman

Latest Draft: identity.foundation/wallet-rendering

Editors:: Daniel Buchner (Microsoft); Brent Zundel (Evernym); Jace Hensley (Bloom); Daniel McGrogan (Workday)

Participate:: GitHub repo; File a bug; Commit history

§ Abstract

Styling the visual presentation of various entities types and data (e.g. credentials) is a common need that runs across many different use cases. In order to provide a predictable set of styling and data display hints to User Agents, Issuers, Verifiers, and other participants who render UI associated with entities and data, this specification endeavors to standardize a common data model to describe generic style and data display hints that can be used across any formulation of UI elements.

§ Terminology

Decentralized Identifiers: Unique ID URI string and PKI metadata document format for describing the cryptographic keys and other fundamental PKI values linked to a unique, user-controlled, self-sovereign identifier in a target system (i.e. blockchain, distributed ledger).
Claim: An assertion made about a Subject. Used as an umbrella term for Credential, Assertion, Attestation, etc.
Issuer: Issuers are entities that issue credentials to a Holder.
Holder: Holders are entities that recieve credentials from Issuers, possibly first submitting proofs the the Issuer to satisfy the requirements described in a Presentation Definition.
Display Mapping Object: Display Mapping Objects are used to render UI based on information from and about a Claim. See Display Mapping Object
Labeled Display Mapping Object: ref:Labeled Display Mapping Objects extend from Display Mapping Objects. See Labeled Display Mapping Object

§ Entity Styles

Entity Style Descriptors are a resource format that defines a set of suggested visual styling elements that a consuming party MAY apply to their presentation of associated entities.

EXAMPLE

{
  "thumbnail": {
    "uri": "https://dol.wa.com/logo.png",
    "alt": "Washington State Seal"
  },
  "hero": {
    "uri": "https://dol.wa.com/people-working.png",
    "alt": "People working on serious things"
  },
  "background": {
    "color": "#ff0000"
  },
  "text": {
    "color": "#d4d400"
  }
}

An Entity Style Descriptor must be an object composed of the following properties:

The object MAY contain a thumbnail property, and if present, its value MUST be an object with the following optional properties:
- The object MUST contain a uri property, and if present its value MUST be a valid URI string to an image resource.
- The object MAY contain an alt property, and if present its value MUST be a string that describes the alternate text for the logo image.
The object MAY contain a hero property, and if present, its value MUST be an object with the following optional properties:
- The object MUST contain a uri property, and if present its value MUST be a valid URI string to an image resource.
- The object MAY contain an alt property, and if present its value MUST be a string that describes the alternate text for the logo image.
The object MAY contain a background property, and if present, its value MUST be an object with the following optional properties:
- The object MAY contain a color property, and if present its value MUST be a HEX string color value (e.g. #000000).
The object MAY contain a text property, and if present, its value MUST be an object with the following optional properties:
- The object MAY contain a color property, and if present its value MUST be a HEX string color value (e.g. #000000).

§ Data Display

A Data Display Descriptor must be an object composed of the following properties:

The object MAY contain a title property, and if present, its value MUST be a Display Mapping Object. User Agents SHOULD render the data in an area of UI that conveys the general title of the credential being rendered.
The object MAY contain a subtitle property, and if present, its value MUST be a Display Mapping Object. User Agents SHOULD render the data in close proximity to the title value and SHOULD display the information in a way that is noticably less pronounced than that of the title value.
The object MAY contain a description property, and if present, its value MUST be a Display Mapping Object. User Agents SHOULD render the data in an area of UI that is appropreate for verbose, descriptive textual data.
The object MAY contain a properties property, and if present, its value MUST be an array of Labeled Display Mapping Objects. User Agents SHOULD render the data specified by each Display Mapping Object in an area of UI that is appropreate for the rendering of a flat list of labeled values.

§ Display Mapping Object

Display Mapping Objects can be used to either pull data from the target Claim with the path property OR display infomation about the target Claim with the text property

§ Using `path`

EXAMPLE

{
  "path": ["$.name", "$.vc.name"],
  "schema": {
    "type": "string"
  },
  "fallback": "Washington State Driver License"
}

The object MUST contain a path property and its value must be an array of JSONPath string expressions.
The object MUST contain a schema property and its value must be an object that is composed as follows:
- The schema property MUST contain a type property and its value must be “string”, “boolean”, “number”, or “integer”. The type property MUST represent the type of the data found with the path property of the Display Mapping Object. See below for “type” specific configurations.
- The schema property MAY contain a format property IF the type property is "string" and its value must be “date-time”, “time”, “date”, “email”, “idn-email”, “hostname”, “idn-hostname”, “ipv4”, “ipv6”, “uri”, “uri-reference”, “iri”, or “iri-reference”. This property is to be used to transform the property in the rendered UI, for example tranforming an ISO Date string into a human readable string.
The object MAY contain a fallback property and its value MUST be a string value. This value is to be used to rendered into the UI if all the path property’s item’s value is undefined OR optionally if when the Holder processes the value and it does not comply with the type specific configuration below.
- If the path’s value does not comply with the type specific configuration below the Holder may use the raw value OR use the Claim itself to help figure out the type of the value.

§ Type specific configuration

§ “string”

When schema.type is set to "string" the object MAY contain an additional set of keywords to describe the string value.

§ Format Set

EXAMPLE

{
  "path": ["$.birthDate", "$.vc.birthDate"],
  "schema": {
    "type": "string",
    "format": "date"
  },
  "fallback": "Birth Date Unknown"
}

If you want to describe the format of the string you MAY specify a format property. It’s value can be one of the following:

Value	Description	Spec
“date-time”	Date and time together, for example, `2018-11-13T20:20:39+00:00`	[RFC3339]
“time”	Time, for example `20:20:39+00:00`	[RFC3339]
“date”	Date, for example `2018-11-13`	[RFC3339]
“email”	Internet email address	[RFC5322]
“idn-email”	The internationalized form of an Internet email address	[RFC6531]
“hostname”	Internet host name	[RFC1034]
“idn-hostname”	The internationalized form of an Internet host name	[RFC5890]
“ipv4”	IPv4 address	[RFC2673]
“ipv6”	IPv6 address	[RFC2373]
“uri”	A universal resource identifier	[RFC3986]
“uri-reference”	A URI reference	[RFC3986]
“iri”	The internationalized equivalent of a “uri”	[RFC3987]
“iri-reference”	The internationalized equivalent of a “uri-reference”	[RFC3987]

§ Encoding Set

EXAMPLE

{
  "path": ["$.frontImage", "$.vc.frontImage"],
  "schema": {
    "type": "string",
    "contentEncoding": "base64",
    "contentMediaType": "image/png"
  },
  "fallback": "No Front Image"
}

If you want to describe the encoding of the string you MAY specify a contentMediaType and contentEncoding properties.

The value of contentMediaType MUST adhere to [RFC2046]
The value of contentEncoding MUST adhere to [RFC2045]
- This property MAY be omitted if the encoding of the string is the same as the enclosing JSON document

§ Using `text`

EXAMPLE

{
  "text": "Washington State Driver License"
}

The object MUST contain a text property and its value MUST be a string value

§ Labeled Display Mapping Object

EXAMPLE

{
  "label": "License Name",
  "path": ["$.name", "$.vc.name"],
  "schema": {
    "type": "string"
  },
  "fallback": "Washington State Driver License"
}

EXAMPLE

{
  "label": "Description",
  "text": "Washington State Driver License"
}

Labeled Display Mapping Objects act the same and have the same requirements as Display Mapping Objects, with the addition of a label property

The object MUST contain a label property and its value must be string.

§ JSON Schemas

§ Vocabulary Definition

The Wallet Rendering specification adopts and defines the following JSON Schema data format and processing variant, which implementers MUST support for evaluation of the portions of the Wallet Rendering specification that call for JSON Schema validation: https://tools.ietf.org/html/draft-handrews-json-schema-02

§ Entity Styles

EXAMPLE

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Entity Styles",
  "type": "object",
  "definitions": {
    "image": {
      "type": "object",
      "properties": {
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "alt": {
          "type": "string"
        }
      },
      "required": ["uri", "alt"]
    },
    "color": {
      "type": "object",
      "properties": {
        "color": {
          "type": "string",
          "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
        }
      },
      "required": ["color"]
    }
  },
  "properties": {
    "thumbnail": {
      "$ref": "#/definitions/image"
    },
    "hero": {
      "$ref": "#/definitions/image"
    },
    "background": {
      "$ref": "#/definitions/color"
    },
    "text": {
      "$ref": "#/definitions/color"
    }
  }
}

§ Display Mapping Object

EXAMPLE

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Display Mapping Object",
  "oneOf": [
    {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "array",
          "items": {"type": "string"}
        },
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "type": {
                  "type": "string",
                  "enum": ["boolean", "number", "integer"]
                }
              },
              "required": ["type"]
            },
            {
              "anyOf": [
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": ["string"]
                    },
                    "format": {
                      "type": "string",
                      "enum": ["date-time", "time", "date", "email", "idn-email", "hostname", "idn-hostname", "ipv4", "ipv6", "uri", "uri-reference", "iri", "iri-reference"]
                    }
                  },
                  "required": ["type"]
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": ["string"]
                    },
                    "contentEncoding": {
                      "type": "string",
                      "enum": ["7bit", "8bit", "binary", "quoted-printable", "base16", "base32", "base64"]
                    },
                    "contentMediaType": {
                      "type": "string"
                    }
                  },
                  "required": ["type"]
                }
              ]
            }
          ]
        },
        "fallback": {
          "type": "string"
        }
      },
      "required": ["path", "schema"]
    },
    {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "text": {
          "type": "string"
        }
      },
      "required": ["text"]
    }
  ]
}

§ Labeled Display Mapping Object

EXAMPLE

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Labeled Display Mapping Object",
  "oneOf": [
    {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "array",
          "items": {"type": "string"}
        },
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "type": {
                  "type": "string",
                  "enum": ["boolean", "number", "integer"]
                }
              },
              "required": ["type"]
            },
            {
              "anyOf": [
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": ["string"]
                    },
                    "format": {
                      "type": "string",
                      "enum": ["date-time", "time", "date", "email", "idn-email", "hostname", "idn-hostname", "ipv4", "ipv6", "uri", "uri-reference", "iri", "iri-reference"]
                    }
                  },
                  "required": ["type"]
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": ["string"]
                    },
                    "contentEncoding": {
                      "type": "string",
                      "enum": ["7bit", "8bit", "binary", "quoted-printable", "base16", "base32", "base64"]
                    },
                    "contentMediaType": {
                      "type": "string"
                    }
                  },
                  "required": ["type"]
                }
              ]
            }
          ]
        },
        "fallback": {
          "type": "string"
        },
        "label": {
          "type": "string"
        }
      },
      "required": ["path", "schema", "label"]
    },
    {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "text": {
          "type": "string"
        },
        "label": {
          "type": "string"
        }
      },
      "required": ["text", "label"]
    }
  ]
}

§ References

RFC1034: Domain names - concepts and facilities. P.V. Mockapetris; 1987-11. Status: Internet Standard.
RFC2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed; N. Borenstein; 1996-11. Status: Draft Standard.
RFC2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. N. Freed; N. Borenstein; 1996-11. Status: Draft Standard.
RFC2373: IP Version 6 Addressing Architecture. R. Hinden; S. Deering; 1998-07. Status: Proposed Standard.
RFC2673: Binary Labels in the Domain Name System. M. Crawford; 1999-08. Status: Historic.
RFC3339: Date and Time on the Internet: Timestamps. G. Klyne; C. Newman; 2002-07. Status: Proposed Standard.
RFC3986: Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter; 2005-01. Status: Internet Standard.
RFC3987: Internationalized Resource Identifiers (IRIs). M. Duerst; M. Suignard; 2005-01. Status: Proposed Standard.
RFC5322: Internet Message Format. P. Resnick, Ed.; 2008-10. Status: Draft Standard.
RFC5890: Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework. J. Klensin; 2010-08. Status: Proposed Standard.
RFC6531: SMTP Extension for Internationalized Email. J. Yao; W. Mao; 2012-02. Status: Proposed Standard.

§ Wallet Rendering

§ Abstract

§ Terminology

§ Entity Styles

§ Data Display

§ Display Mapping Object

§ Using path

§ Type specific configuration

§ “string”

§ Format Set

§ Encoding Set

§ Using text

§ Labeled Display Mapping Object

§ JSON Schemas

§ Vocabulary Definition

§ Entity Styles

§ Display Mapping Object

§ Labeled Display Mapping Object

§ References

§ Using `path`

§ Using `text`