§ Credential Manifest

Specification Status: Strawman

Latest Draft: identity.foundation/credential-manifest

Editors:
Daniel Buchner (Microsoft)
Brent Zundel (Evernym)
Jace Hensley (Bloom)
Daniel McGrogan (Workday)
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(s) 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(s) indicated in the Credential Manifest.

Credential Manifests do not themselves define the contents of the output credential(s), 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

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.
Output Descriptor
Output Descriptors are used by an Issuer to describe the credentials they are offering to a Holder. See Output Descriptor
Output Descriptor Object
Output Descriptor Objects are populated with properties describing the Claims the Issuer is offering the Holder
Output Descriptor Display Object
Output Descriptor Display Objects are populated with DIF Data Display properties
Credential Application
Credential Application are objects embedded within target claim negotiation formats that pass information from the Holder to the Issuer. See Credential Application
Credential Fulfillment
Credential Fulfillments are objects embedded within target claim negotiation formats that unify the presentation of Claims to a Holder in accordance with the output an Issuer specified in a Credential Manifest. See Credential Fulfillment.

§ Credential Manifest

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
{
  "id": "WA-DL-CLASS-A",
  "issuer": {
    "id": "did:example:123?linked-domains=3",
    "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"
      }
    }
  },
  "output_descriptors": [
    {
      "id": "driver_license_output",
      "schema": "https://schema.org/EducationalOccupationalCredential",
      "display": {
        "title": {
          "path": ["$.name", "$.vc.name"],
          "schema": {
            "type": "string"
          },
          "fallback": "Washington State Driver License"
        },
        "subtitle": {
          "path": ["$.class", "$.vc.class"],
          "schema": {
            "type": "string"
          },
          "fallback": "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"],
            "schema": {
              "type": "boolean"
            },
            "fallback": "Unknown",
            "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": {}
}

§ General Composition

Credential Manifests are JSON objects composed as follows:

{
  "credential_manifest": {
    "id": "WA-DL-CLASS-A",
    "output_descriptors": [],
    "format": {
      "jwt": {
        "alg": ["EdDSA", "ES256K", "ES384"]
      },
      "jwt_vc": {
        "alg": ["ES256K", "ES384"]
      },
      "jwt_vp": {
        "alg": ["EdDSA", "ES256K"]
      },
      "ldp_vc": {
        "proof_type": [
          "JsonWebSignature2020",
          "Ed25519Signature2018",
          "EcdsaSecp256k1Signature2019",
          "RsaSignature2018"
        ]
      },
      "ldp_vp": {
        "proof_type": ["Ed25519Signature2018"]
      },
      "ldp": {
        "proof_type": ["RsaSignature2018"]
      }
    }
  }
}

§ Output Descriptor

Output Descriptors are objects used to describe the Claims an Issuer is offering to a Holder.

Output Descriptor Objects contain type URI that links to the type of the offered output data, and information about how to display the output to the Holder.

EXAMPLE
{
  "output_descriptors": [
    {
      "id": "driver_license_output",
      "schema": "https://schema.org/EducationalOccupationalCredential",
      "display": {
        "title": {
          "path": ["$.name", "$.vc.name"],
          "schema": {
            "type": "string"
          },
          "fallback": "Washington State Driver License"
        },
        "subtitle": {
          "path": ["$.class", "$.vc.class"],
          "schema": {
            "type": "string"
          },
          "fallback": "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"],
            "schema": {
              "type": "boolean"
            },
            "fallback": "Unknown",
            "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"
        }
      }
    }
  ]
}

§ Output Descriptor Object

Output Descriptor Objects are composed as follows:

:::

§ JSON Schema

The JSON Schema Draft 7 definition that summarizes the rules above for Output Descriptors can be found after the appendix here.

§ JSON Schema

The JSON Schema Draft 7 definition that summarizes the rules above for Credential Manifest can be found after the appendix here.

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

§ Credential Application

Credential Application are objects embedded within target claim negotiation formats that pass information from the Holder to the Issuer

// NOTE: VP, OIDC, DIDComm, or CHAPI outer wrapper properties would be at outer layer
EXAMPLE
{
  "credential_application": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "manifest_id": "WA-DL-CLASS-A",
    "format": {
      "ldp_vc": {
        "proof_type": [
          "JsonWebSignature2020",
          "EcdsaSecp256k1Signature2019"
        ]
      }
    }
  },
  "presentation_submission": {
    "id": "a30e3b91-fb77-4d22-95fa-871689c322e2",
    "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "descriptor_map": [
      {
        "id": "input_1",
        "format": "jwt_vc",
        "path": "$.verifiableCredential[0]"
      },
      {
        "id": "input_2",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[1]"
      },
      {
        "id": "input_3",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[2]"
      }
    ]
  }
}

§ Embed Targets

The following section details where the Credential Application is to be embedded within a target data structure.

§ Embed Locations

The following are the locations at which the credential_application and, conditionally, the presentation_submission objects MUST be embedded for known target formats. For any location besides the top level of the embed target, the location is described in JSONPath syntax.

Target Location
OpenID top-level
DIDComms $.presentations~attach.data.json
VP top-level
CHAPI $.data

§ JSON Schema

The JSON Schema Draft 7 definition that summarizes the rules above for Credential Application can be found after the appendix here.

§ Credential Fulfillment

Credential Fulfillments are objects embedded within target Claim negotiation formats that express how the outputs presented as proofs to a Holder are provided in accordance with the outpus specified in a Credential Manifest. Embedded Credential Fulfillment objects MUST be located within target data format as the value of a credential_fulfillment property, which is composed and embedded as follows:

// NOTE: VP, OIDC, DIDComm, or CHAPI outer wrapper properties would be at outer layer
EXAMPLE
{  
  "credential_fulfillment": {
    "id": "a30e3b91-fb77-4d22-95fa-871689c322e2",
    "manifest_id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "descriptor_map": [
      {
        "id": "banking_output_2",
        "format": "jwt_vc",
        "path": "$.verifiableCredential[0]"
      },
      {
        "id": "employment_output",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[1]"
      },
      {
        "id": "citizenship_output_1",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[2]"
      }
    ]
  }
}

§ Embed Targets

The following section details where the Credential Fulfillment is to be embedded within a target data structure, as well as how to formulate the JSONPath expressions to select the Claims within the target data structure.

§ Embed Locations

The following are the locations at which the credential_fulfillment object MUST be embedded for known target formats. For any location besides the top level of the embed target, the location is described in JSONPath syntax.

Target Location
OpenID top-level
DIDComms $.presentations~attach.data.json
VP top-level
CHAPI $.data

§ JSON Schema

The JSON Schema Draft 7 definition that summarizes the rules above for Credential Fulfillment can be found after the appendix here.

§ Appendix

§ Embed Target Examples

§ Credential Fulfillment

EXAMPLE
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://identity.foundation/credential-manifest/fulfillment/v1"
  ],
  "type": [
    "VerifiablePresentation",
    "CredentialFulfillment"
  ],
  "credential_fulfillment": {
    "id": "a30e3b91-fb77-4d22-95fa-871689c322e2",
    "manifest_id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "descriptor_map": [
      {
        "id": "banking_output_2",
        "format": "jwt_vc",
        "path": "$.verifiableCredential[0]"
      },
      {
        "id": "employment_output",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[1]"
      },
      {
        "id": "citizenship_output_1",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[2]"
      }
    ]
  },
  "verifiableCredential": [
    {
      "comment": "IN REALWORLD VPs, THIS WILL BE A BIG UGLY OBJECT INSTEAD OF THE DECODED JWT PAYLOAD THAT FOLLOWS",
      "vc": {
        "@context": "https://www.w3.org/2018/credentials/v1",
        "id": "https://eu.com/claims/DriversLicense",
        "type": ["EUDriversLicense"],
        "issuer": "did:example:123",
        "issuanceDate": "2010-01-01T19:73:24Z",
        "credentialSubject": {
          "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
          "accounts": [
            {
              "id": "1234567890",
              "route": "DE-9876543210"
            },
            {
              "id": "2457913570",
              "route": "DE-0753197542"
            }
          ]
        }
      }
    },
    {
      "@context": "https://www.w3.org/2018/credentials/v1",
      "id": "https://business-standards.org/schemas/employment-history.json",
      "type": ["VerifiableCredential", "GenericEmploymentCredential"],
      "issuer": "did:foo:123",
      "issuanceDate": "2010-01-01T19:73:24Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "active": true
      },
      "proof": {
        "type": "EcdsaSecp256k1VerificationKey2019",
        "created": "2017-06-18T21:19:10Z",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "https://example.edu/issuers/keys/1",
        "jws": "..."
      }
    },
    {
      "@context": "https://www.w3.org/2018/credentials/v1",
      "id": "https://eu.com/claims/DriversLicense",
      "type": ["EUDriversLicense"],
      "issuer": "did:foo:123",
      "issuanceDate": "2010-01-01T19:73:24Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "license": {
          "number": "34DGE352",
          "dob": "07/13/80"
        }
      },
      "proof": {
        "type": "RsaSignature2018",
        "created": "2017-06-18T21:19:10Z",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "https://example.edu/issuers/keys/1",
        "jws": "..."
      }
    }
  ],
  "proof": {
    "type": "RsaSignature2018",
    "created": "2018-09-14T21:19:10Z",
    "proofPurpose": "authentication",
    "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1",
    "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
    "domain": "4jt78h47fh47",
    "jws": "..."
  }
}

§ Credential Application

EXAMPLE
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://identity.foundation/credential-manifest/application/v1"
  ],
  "type": [
    "VerifiablePresentation",
    "CredentialApplication"
  ],
  "credential_application": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "manifest_id": "WA-DL-CLASS-A",
    "format": {
      "ldp_vc": {
        "proof_type": [
          "JsonWebSignature2020",
          "EcdsaSecp256k1Signature2019"
        ]
      }
    }
  },
  "presentation_submission": {
    "id": "a30e3b91-fb77-4d22-95fa-871689c322e2",
    "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "descriptor_map": [
      {
        "id": "input_1",
        "format": "jwt_vc",
        "path": "$.verifiableCredential[0]"
      },
      {
        "id": "input_2",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[1]"
      },
      {
        "id": "input_3",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[2]"
      }
    ]
  },
  "verifiableCredential": [
    {
      "comment": "IN REALWORLD VPs, THIS WILL BE A BIG UGLY OBJECT INSTEAD OF THE DECODED JWT PAYLOAD THAT FOLLOWS",
      "vc": {
        "@context": "https://www.w3.org/2018/credentials/v1",
        "id": "https://eu.com/claims/DriversLicense",
        "type": ["EUDriversLicense"],
        "issuer": "did:example:123",
        "issuanceDate": "2010-01-01T19:73:24Z",
        "credentialSubject": {
          "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
          "accounts": [
            {
              "id": "1234567890",
              "route": "DE-9876543210"
            },
            {
              "id": "2457913570",
              "route": "DE-0753197542"
            }
          ]
        }
      }
    },
    {
      "@context": "https://www.w3.org/2018/credentials/v1",
      "id": "https://business-standards.org/schemas/employment-history.json",
      "type": ["VerifiableCredential", "GenericEmploymentCredential"],
      "issuer": "did:foo:123",
      "issuanceDate": "2010-01-01T19:73:24Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "active": true
      },
      "proof": {
        "type": "EcdsaSecp256k1VerificationKey2019",
        "created": "2017-06-18T21:19:10Z",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "https://example.edu/issuers/keys/1",
        "jws": "..."
      }
    },
    {
      "@context": "https://www.w3.org/2018/credentials/v1",
      "id": "https://eu.com/claims/DriversLicense",
      "type": ["EUDriversLicense"],
      "issuer": "did:foo:123",
      "issuanceDate": "2010-01-01T19:73:24Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "license": {
          "number": "34DGE352",
          "dob": "07/13/80"
        }
      },
      "proof": {
        "type": "RsaSignature2018",
        "created": "2017-06-18T21:19:10Z",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "https://example.edu/issuers/keys/1",
        "jws": "..."
      }
    }
  ],
  "proof": {
    "type": "RsaSignature2018",
    "created": "2018-09-14T21:19:10Z",
    "proofPurpose": "authentication",
    "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1",
    "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
    "domain": "4jt78h47fh47",
    "jws": "..."
  }
}

§ 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

§ Credential Manifest

EXAMPLE
{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "required": [
    "id",
    "issuer",
    "output_descriptors"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "issuer": {
      "type": "object",
      "required": [
        "id",
        "name",
        "styles"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "styles": {
          "$ref": "https://identity.foundation/wallet-rendering/schemas/entity-styles.json"
        }
      },
      "additionalProperties": false
    },
    "output_descriptors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "schema"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "schema": {
            "type": "string",
            "format": "uri"
          },
          "display": {
            "type": "object",
            "properties": {
              "title": {
                "$ref": "https://identity.foundation/wallet-rendering/schemas/display-mapping-object.json"
              },
              "subtitle": {
                "$ref": "https://identity.foundation/wallet-rendering/schemas/display-mapping-object.json"
              },
              "description": {
                "$ref": "https://identity.foundation/wallet-rendering/schemas/display-mapping-object.json"
              },
              "properties": {
                "type": "array",
                "items": {
                  "$ref": "https://identity.foundation/wallet-rendering/schemas/labeled-display-mapping-object.json"
                }
              }
            },
            "additionalProperties": false
          },
          "styles": {
            "$ref": "https://identity.foundation/wallet-rendering/schemas/entity-styles.json"
          }
        },
        "additionalProperties": false
      }
    },
    "presentation_definition": {
      "type": "object",
      "required": [],
      "additionalProperties": false
    },
    "format": {}
  },
  "additionalProperties": false
}

§ Output Descriptors

EXAMPLE
{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {
    "output_descriptors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "schema"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "schema": {
            "type": "string",
            "format": "uri"
          },
          "display": {
            "type": "object",
            "properties": {
              "title": {
                "$ref": "https://identity.foundation/wallet-rendering/schemas/display-mapping-object.json"
              },
              "subtitle": {
                "$ref": "https://identity.foundation/wallet-rendering/schemas/display-mapping-object.json"
              },
              "description": {
                "$ref": "https://identity.foundation/wallet-rendering/schemas/display-mapping-object.json"
              },
              "properties": {
                "type": "array",
                "items": {
                  "$ref": "https://identity.foundation/wallet-rendering/schemas/labeled-display-mapping-object.json"
                }
              }
            },
            "additionalProperties": false
          },
          "styles": {
            "$ref": "https://identity.foundation/wallet-rendering/schemas/entity-styles.json"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "required": [
    "output_descriptors"
  ],
  "additionalProperties": false
}

§ Credential Application

EXAMPLE
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Credential Submission",
  "type": "object",
  "properties": {
    "credential_application": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "manifest_id": { "type": "string" },
        "format": {
          "type": "object",
          "patternProperties": {
            "^jwt$|^jwt_vc$|^jwt_vp$": {
              "type": "object",
              "properties": {
                "alg": {
                  "type": "array",
                  "minItems": 1,
                  "items": { "type": "string" }
                }
              },
              "required": ["alg"],
              "additionalProperties": false
            },
            "^ldp_vc$|^ldp_vp$|^ldp$": {
              "type": "object",
              "properties": {
                "proof_type": {
                  "type": "array",
                  "minItems": 1,
                  "items": { "type": "string" }
                }
              },
              "required": ["proof_type"],
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      },
      "required": ["id", "manifest_id", "format"],
      "additionalProperties": false
    },
    "presentation_submission": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "definition_id": { "type": "string" },
        "descriptor_map": {
          "type": "array",
          "items": { "$ref": "#/definitions/descriptor" }
        }
      },
      "required": ["id", "definition_id", "descriptor_map"],
      "additionalProperties": false
    }
  },
  "definitions": {
    "descriptor": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "path": { "type": "string" },
        "path_nested": {
          "type": "object",
          "$ref": "#/definitions/descriptor"
        },
        "format": {
          "type": "string",
          "enum": ["jwt", "jwt_vc", "jwt_vp", "ldp", "ldp_vc", "ldp_vp"]
        }
      },
      "required": ["id", "path", "format"],
      "additionalProperties": false
    }
  },
  "required": ["credential_application"],
  "additionalProperties": false
}

§ Credential Fulfillment

EXAMPLE
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Credential Fulfillment",
  "type": "object",
  "properties": {
    "credential_fulfillment": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "manifest_id": { "type": "string" },
        "descriptor_map": {
          "type": "array",
          "items": { "$ref": "#/definitions/descriptor" }
        }
      },
      "required": ["id", "manifest_id", "descriptor_map"],
      "additionalProperties": false
    }
  },
  "definitions": {
    "descriptor": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "path": { "type": "string" },
        "path_nested": {
          "type": "object",
            "$ref": "#/definitions/descriptor"
        },
        "format": {
          "type": "string",
          "enum": ["jwt", "jwt_vc", "jwt_vp", "ldp", "ldp_vc", "ldp_vp"]
        }
      },
      "required": ["id", "path", "format"],
      "additionalProperties": false
    }
  },
  "required": ["credential_fulfillment"],
  "additionalProperties": false
}


§ References

[[spec]]

Table of Contents