§ Credential Manifest

Specification Status: Strawman

Latest Draft: identity.foundation/credential-manifest

Editors:
Daniel Buchner (Microsoft)
Brent Zundel (Evernym)
Participate:
GitHub repo
File a bug
Commit history

§ Abstract

For User Agents (e.g. wallets) and other service that wish to engage with Issuers to acquire credentials, there must exist a mechanism for assessing what inputs are required from a Subject to process a request for credential issuance. The Credential Manifest is a common data format for describing the inputs a Subject must provide to an Issuer for subsequent evaluation and issuance of the credential indicated in the Credential Manifest.

Credential Manifests do not themselves define the contents of the output credential, the process the Issuer uses to evaluate the submitted inputs, or the protocol Issuers, Subjects, and their User Agents rely on to negotiate credential issuance.

§ Status of This Document

Credential Manifest is a draft specification being developed within the Decentralized Identity Foundation (DIF), and intended for ratification as a DIF recommended data format. This spec will be updated to reflect relevant changes, and participants are encouraged to contribute at the following repository location: https://github.com/decentralized-identity/credential-manifest

§ Terminology

Term Definition
Decentralized Identifier (DID) Unique ID 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).
Issuer An entity that issues a credential to a Subject.
Holder The entity that submits proofs to a Verifier to satisfy the requirements described in a Proof Definition
Verifier The entity that defines what proofs they require from a Subject (via a Proof Definition) in order to proceed with an interaction.

§ Resource Definition

Credential Manifests are a resource format that defines preconditional requirements, Issuer style preferences, and other facets User Agents utilize to help articulate and select the inputs necessary for processing and issuance of a specified credential.

EXAMPLE
{
  "locale": "en-US",
  "issuer": {
    "id": "did:example:123",
    "name": "Washington State Government",
    "styles": {
      "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"
      }
    }
  },
  "credential": {
    "schema": "https://schema.org/EducationalOccupationalCredential",
    "display": {
      "title": {
        "path": ["$.name", "$.vc.name"],
        "text": "Washington State Driver License"
      },
      "subtitle": {
        "path": ["$.class", "$.vc.class"],
        "text": "Class A, Commercial"
      },
      "description": {
        "text": "License to operate a vehicle with a gross combined weight rating (GCWR) of 26,001 or more pounds, as long as the GVWR of the vehicle(s) being towed is over 10,000 pounds."
      },
      "properties": [
        {
          "path": ["$.donor", "$.vc.donor"],
          "label": "Organ Donor"
        }
      ]
    },
    "styles": {
      "thumbnail": {
        "uri": "https://dol.wa.com/logo.png",
        "alt": "Washington State Seal"
      },
      "hero": {
        "uri": "https://dol.wa.com/happy-people-driving.png",
        "alt": "Happy people driving"
      },
      "background": {
        "color": "#ff0000"
      },
      "text": {
        "color": "#d4d400"
      }
    }
  },
  "presentation_definition": {
    // As defined in the Presentation Exchange specification
  }
}

§ General Composition

Credential Manifests are JSON objects composed as follows:

§ styles properties

Within a Credential Manifest, there are two areas where styling affordances are provided: under the issuer property, where the Issuer expresses information about themselves - including how a User Agent should style UI that represents the Issuer, and under the credential property, where the Issuer expresses information about the credntial itself - including how a User Agent should style UI for the credential itself. Under each of these areas an implementer MAY include a styles property, and if present, its value must be an object composed of the following properties:

§ display properties

The credential property of a Credential Manifest is an object that MAY contain a display property defining various content and data pointers for representation of a credential in UI. The properties in the object use Display Mapping Objects to assign text and data about the credential to common UI presentation elements, either by selecting data from the credential itself or providing it directly. The display object is constructed as follows

§ Display Mapping Objects

EXAMPLE
{
  "display": {
    "title": {
      "path": ["$.name", "$.vc.name"],
      "text": "Washington State Driver License"
    },
    "properties": [
      {
        "path": ["$.vision_aid", "$.vc.vision_aid"],
        "label": "Vision aid required"
      },
      {
        "path": ["$.donor", "$.vc.donor"],
        "label": "Organ Donor"
      }
    ]
  }
}

The Display Mapping Objects are JSON objects constructed as follows:

§ Resource Location

Credential Manifests should be retrievable at known, semantic locations that are generalized across all entities, protocols, and transports. This specification does not stipulate how Credential Manifests must be located, hosted, or retrieved, but does advise that Issuers SHOULD make their Credential Manifests available via an instance of the forthcoming semantic personal datastore standard being developed by DIF, W3C, and other groups (e.g. Identity Hubs).

Table of Contents