§ 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:

§ Data Display

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

§ 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"
}

§ 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.

§ Using text

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

§ 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

§ 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.

Table of Contents