§ Presentation Exchange

Specification Status: Latest Draft

Latest Draft: identity.foundation/presentation-exchange

Ratified Versions:
v1.0.0 - https://identity.foundation/presentation-exchange/spec/v1.0.0
Editors:
Daniel Buchner (Microsoft)
Brent Zundel (Evernym)
Martin Riedel (Consensys Mesh)
Contributors:
Gabe Cohen (Workday)
Orie Steele (Transmute)
Wayne Chang (Spruce)
Participate:
GitHub repo
File a bug
Commit history

§ Abstract

A common activity between peers in identity systems that feature the ability to generate self-asserted and third-party issued Claims is the demand and submission of proofs from a Holder to a Verifier. This flow implicitly requires the Holder and Verifier have a mechanism to facilitate the two primary steps in a proving exchange: a way for Verifiers to describe proof requirements, and for Holders to describe submissions of proof which align with those requirements.

To address these needs, this Presentation Exchange specification codifies a Presentation Definition data format Verifiers can use to articulate proof requirements, and a Presentation Submission data format Holders can use to describe proofs submitted in accordance with them.

This specification is designed to be both Claim format and transport envelope agnostic, meaning an implementer can use JSON Web Tokens (JWTs), Verifiable Credentials (VCs), JWT-VCs, or any other Claim format, and convey them via Open ID Connect, DIDComm, Credential Handler API, or any other transport envelope. The goal of this flexible format- and transport-agnostic mechanism is to nullify the redundant handling, code, and hassle involved in presenting and satisfying logical requirements across formats and transport envelopes.

This specification does not define transport protocols, specific endpoints, or other means for conveying the formatted objects it codifies, but encourages other specifications and projects that do define such mechanisms to utilize these data formats within their flows.

§ Status of This Document

Presentation Exchange v1.0 is a DRAFT specification under development within the Decentralized Identity Foundation (DIF). It incorporates requirements and learnings from related work of many active industry players into a shared specification that meets the collective needs of the community.

This specification is ready for feedback from other decentralized identity-related and -adjacent communities. It will be updated to incorporate that feedback, then implementations will be sought so that the specification can move to Working Group Approved status. We encourage reviewers to submit issues on GitHub.

§ Terminology

Claim
An assertion made about a Subject. Used as an umbrella term for Credential, Assertion, Attestation, etc.
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).
Embed Locations
Embed Locations are the specific paths and indexes per Embed Target where the Verifier can expect to find the Presentation. See Embed Locations.
Embed Target
Embed Targets are data formats used in messaging protocols that may be used to transport a Presentation Submission. See Embed Targets.
Holder
Holders are entities that submit proofs to Verifiers to satisfy the requirements described in a Presentation Definition.
Holder Binding
Holder Bindings are requirements of a certain type of relationship between the Holder and the Claims within the Presentation. See Holder Binding.
Identity Hub
Some examples refer to an unfamiliar query protocol, hub:// , as a way of storing and querying schemata and other resources. While orthogonal to this specification and not yet on a standards track, the concept of “identity hubs” proposes an architecture that may be of interest or utility to implementers of this specification. For more information, see the pre-draft specification hosted at the decentralized identity foundation here
Input Descriptor
Input Descriptors are used by a Verifier to describe the information required of a Holder before an interaction can proceed. See Input Descriptor.
Input Descriptor Object
Input Descriptors Objects are populated with properties describing what type of input data/Claim, or sub-fields thereof, are required for submission to the Verifier. See Input Descriptor Object.
Link Secrets
Link Secrets are values held by the Holder but hidden from other parties. They are typically incorporated into cryptographic signatures used in claims to demonstrate correlation while preventing replay attacks. An Issuer may ascertain that a Holder possesses a link secret without its disclosure. See Link Secrets.
Presentation Definition
Presentation Definitions are objects that articulate what proofs a Verifier requires. These help the Verifier to decide how or whether to interact with a Holder. Presentation Definitions are composed of inputs, which describe the forms and details of the proofs they require, and optional sets of selection rules, to allow Holders flexibility in cases where many different types of proofs may satisfy an input requirement. See Presentation Definition.
Presentation Request
Presentation Requests are transport mechanisms for Presentation. Presentation Requests can take multiple shapes, using a variety of protocols and signature schemes not refined in this specification. They are sent by a Verifier to a Holder. Defining Presentation Requests is outside the scope of this specification. See Presentation Request.
Presentation Submission
Presentation Submissions are objects embedded within target claim negotiation formats that unify the presentation of proofs to a Verifier in accordance with the requirements a Verifier specified in a Presentation Definition. See Presentation Submission.
Subject
Subjects are the entities about which [[r:Claims]] are made. The Subject may not be the same entity as the Holder
Submission Requirement
Submission Requirements are objects that define what combinations of inputs must be submitted to comply with the requirements a Verifier has for proceeding in a flow (e.g. credential issuance, allowing entry, accepting an application). See Submission Requirements.
Submission Requirement Object
Submission Requirement Objects describe valid combinations of inputs in a Presentation Submission. See Submission Requirement Objects.
Submission Requirement Rule
Submission Requirement Rules describe combinatorical rules within a Submission Requirement Object when processing inputs. They may be nested. See Submission Requirement Rules.
Verifier
Verifiers are entities that define what proofs they require from a Holder (via a Presentation Definition) in order to proceed with an interaction.

§ Presentation Definition

Presentation Definitions are objects that articulate what proofs a Verifier requires. These help the Verifier to decide how or whether to interact with a Holder. Presentation Definitions are composed of inputs, which describe the forms and details of the proofs they require, and optional sets of selection rules, to allow Holders flexibility in cases where different types of proofs may satisfy an input requirement.

EXAMPLE
{
  "comment": "Note: VP, OIDC, DIDComm, or CHAPI outer wrapper would be here.",
  "presentation_definition": {
    "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "input_descriptors": [
      {
        "id": "wa_driver_license",
        "name": "Washington State Business License",
        "purpose": "We can only allow licensed Washington State business representatives into the WA Business Conference",
        "schema": [{
            "uri": "https://licenses.example.com/business-license.json"
        }]
      }
    ]
  }
}

EXAMPLE
{
  "comment": "Note: VP, OIDC, DIDComm, or CHAPI outer wrapper would be here.",
  "presentation_definition": {
    "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "input_descriptors": [
      {
        "id": "bankaccount_input",
        "name": "Full Bank Account Routing Information",
        "purpose": "We can only remit payment to a currently-valid bank account, submitted as an ABA RTN + Acct # or IBAN.",
        "schema": [{
            "uri": "https://bank-standards.example.com/fullaccountroute.json"
        }],
        "constraints": {
          "limit_disclosure": "required",
          "fields": [
            {
              "path": [
                  "$.issuer", 
                  "$.vc.issuer", 
                  "$.iss"
              ],
              "purpose": "We can only verify bank accounts if they are attested by a trusted bank, auditor, or regulatory authority.",
              "filter": {
                "type": "string",
                "pattern": "did:example:123|did:example:456"
              }
            }
          ]
        }
      },
      {
        "id": "us_passport_input",
        "name": "US Passport",
        "schema": [
          {
            "uri": "hub://did:foo:123/Collections/schema.us.gov/passport.json"
          }
        ],
        "constraints": {
          "fields": [
            {
              "path": ["$.credentialSubject.birth_date", "$.vc.credentialSubject.birth_date", "$.birth_date"],
              "filter": {
                "type": "string",
                "format": "date",
                "minimum": "1999-05-16"
              }
            }
          ]
        }

      }
    ]
  }
}

EXAMPLE
{
  "comment": "VP, OIDC, DIDComm, or CHAPI outer wrapper here",
  "presentation_definition": {
    "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "submission_requirements": [{
      "name": "Citizenship Information",
      "rule": "pick",
      "count": 1,
      "from": "A"
    }],
    "input_descriptors": [
      {
        "id": "citizenship_input_1",
        "name": "EU Driver's License",
        "group": ["A"],
        "schema": [
          {
            "uri": "https://eu.com/claims/DriversLicense.json"
          }
        ],
        "constraints": {
          "fields": [
            {
              "path": ["$.issuer", "$.vc.issuer", "$.iss"],
              "purpose": "We can only accept digital driver's licenses issued by national authorities of member states or trusted notarial auditors.",
              "filter": {
                "type": "string",
                "pattern": "did:example:gov1|did:example:gov2"
              }
            },
            {
              "path": ["$.credentialSubject.dob", "$.vc.credentialSubject.dob", "$.dob"],
              "filter": {
                "type": "string",
                "format": "date",
                "maximum": "1999-06-15"
              }
            }
          ]
        }
      },
      {
        "id": "citizenship_input_2",
        "name": "US Passport",
        "group": ["A"],
        "schema": [
          {
            "uri": "hub://did:foo:123/Collections/schema.us.gov/passport.json"
          }
        ],
        "constraints": {
          "fields": [
            {
              "path": ["$.credentialSubject.birth_date", "$.vc.credentialSubject.birth_date", "$.birth_date"],
              "filter": {
                "type": "string",
                "format": "date",
                "maximum": "1999-05-16"
              }
            }
          ]
        }
      }
    ]
  }
}

EXAMPLE
{
  "comment": "VP, OIDC, DIDComm, or CHAPI outer wrapper here",
  "presentation_definition": {
    "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "submission_requirements": [
      {
        "name": "Banking Information",
        "purpose": "We can only remit payment to a currently-valid bank account in the US, Germany or France.",
        "rule": "pick",
        "count": 1,
        "from": "A"
      },
      {
        "name": "Employment Information",
        "purpose": "We are only verifying one current employment relationship, not any other information about employment.",
        "rule": "all",
        "from": "B"
      },
      {
        "name": "Eligibility to Drive on US Roads",
        "purpose": "We need to verify eligibility to drive on US roads via US or EU driver's license, but no biometric or identifying information contained there.",
        "rule": "pick",
        "count": 1,
        "from": "C"
      }
    ],
    "input_descriptors": [
      {
        "id": "banking_input_1",
        "name": "Bank Account Information",
        "purpose": "Bank Account required to remit payment.",
        "group": ["A"],
        "schema": [
          {
            "uri": "https://bank-standards.example.com#accounts",
            "required": true
          },
          {
            "uri": "https://bank-standards.example.com#investments",
            "required": true
          }
        ],
        "constraints": {
          "limit_disclosure": "required",
          "fields": [
            {
              "path": ["$.issuer", "$.vc.issuer", "$.iss"],
              "purpose": "We can only verify bank accounts if they are attested by a trusted bank, auditor or regulatory authority.",
              "filter": {
                "type": "string",
                "pattern": "did:example:123|did:example:456"
              }
            },
            {
              "path": [
                "$.credentialSubject.account[*].account_number", 
                "$.vc.credentialSubject.account[*].account_number", 
                "$.account[*].account_number"
              ],
              "purpose": "We can only remit payment to a currently-valid bank account in the US, France, or Germany, submitted as an ABA Acct # or IBAN.",
              "filter": {
                "type": "string",
                "pattern": "^[0-9]{10-12}|^(DE|FR)[0-9]{2}\\s?([0-9a-zA-Z]{4}\\s?){4}[0-9a-zA-Z]{2}$"
              }
            },
            {
              "path": ["$.credentialSubject.portfolio_value", "$.vc.credentialSubject.portfolio_value", "$.portfolio_value"],
              "purpose": "A current portfolio value of at least one million dollars is required to insure your application",
              "filter": {
                "type": "number",
                "minimum": 1000000
              }
            }
          ]
        }
      },
      {
        "id": "banking_input_2",
        "name": "Bank Account Information",
        "purpose": "We can only remit payment to a currently-valid bank account.",
        "group": ["A"],
        "schema": [
          {
            "uri": "https://bank-schemas.org/1.0.0/accounts.json"
          },
          {
            "uri": "https://bank-schemas.org/2.0.0/accounts.json"
          }
        ],
        "constraints": {
          "fields": [
            {
              "path": [
                "$.issuer", 
                "$.vc.issuer", 
                "$.iss"
              ],
              "purpose": "We can only verify bank accounts if they are attested by a trusted bank, auditor or regulatory authority.",
              "filter": {
                "type": "string",
                "pattern": "did:example:123|did:example:456"
              }
            },
            { 
              "path": [
                "$.credentialSubject.account[*].id", 
                "$.vc.credentialSubject.account[*].id", 
                "$.account[*].id"
              ],
              "purpose": "We can only remit payment to a currently-valid bank account in the US, France, or Germany, submitted as an ABA Acct # or IBAN.",
              "filter": {
                "type": "string",
                "pattern": "^[0-9]{10-12}|^(DE|FR)[0-9]{2}\\s?([0-9a-zA-Z]{4}\\s?){4}[0-9a-zA-Z]{2}$"
              }
            },
            {
              "path": [
                "$.credentialSubject.account[*].route", 
                "$.vc.credentialSubject.account[*].route", 
                "$.account[*].route"
              ],
              "purpose": "We can only remit payment to a currently-valid account at a US, Japanese, or German federally-accredited bank, submitted as an ABA RTN or SWIFT code.",
              "filter": {
                "type": "string",
                "pattern": "^[0-9]{9}|^([a-zA-Z]){4}([a-zA-Z]){2}([0-9a-zA-Z]){2}([0-9a-zA-Z]{3})?$"
              }
            }
          ]
        }
      },
      {
        "id": "employment_input",
        "name": "Employment History",
        "purpose": "We are only verifying one current employment relationship, not any other information about employment.",
        "group": ["B"],
        "schema": [
          {
            "uri": "https://business-standards.org/schemas/employment-history.json"
          }
        ],
        "constraints": {
          "limit_disclosure": "required",
          "fields": [
            {
              "path": ["$.jobs[*].active"],
              "filter": {
                "type": "boolean",
                "pattern": "true"
              }
            }
          ]
        }
      },
      {
        "id": "drivers_license_input_1",
        "name": "EU Driver's License",
        "group": ["C"],
        "schema": [
          {
            "uri": "https://schema.eu/claims/DriversLicense.json"
          }
        ],
        "constraints": {
          "fields": [
            {
              "path": ["$.issuer", "$.vc.issuer", "$.iss"],
              "purpose": "We can only accept digital driver's licenses issued by national authorities of EU member states or trusted notarial auditors.",
              "filter": {
                "type": "string",
                "pattern": "did:example:gov1|did:example:gov2"
              }
            },
            {
              "path": ["$.credentialSubject.dob", "$.vc.credentialSubject.dob", "$.dob"],
              "purpose": "We must confirm that the driver was at least 21 years old on April 16, 2020.",
              "filter": {
                "type": "string",
                "format": "date",
                "maximum": "1999-05-16"
              }
            }
          ]
        }
      },
      {
        "id": "drivers_license_input_2",
        "name": "Driver's License from one of 50 US States",
        "group": ["C"],
        "schema": [
          {
            "uri": "hub://did:foo:123/Collections/schema.us.gov/american_drivers_license.json"
          }
        ],
        "constraints": {
          "fields": [
            {
              "path": ["$.issuer", "$.vc.issuer", "$.iss"],
              "purpose": "We can only accept digital driver's licenses issued by the 50 US states' automative affairs agencies.",
              "filter": {
                "type": "string",
                "pattern": "did:example:gov1|did:web:dmv.ca.gov|did:example:oregonDMV"
              }
            },
            {
              "path": ["$.credentialSubject.birth_date", "$.vc.credentialSubject.birth_date", "$.birth_date"],
              "purpose": "We must confirm that the driver was at least 21 years old on April 16, 2020.",
              "filter": {
                "type": "string",
                "format": "date",
                "maximum": "1999-05-16"
              }
            }
          ]
        }
      }
    ]
  }
}

The following properties are for use at the top-level of a Presentation Definition. Any properties that are not defined below MUST be ignored:

{
  "presentation_definition": {
    "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "input_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"]
      }
    }
  }
}

§ Input Descriptor

Input Descriptors are objects used to describe the information a Verifier requires of a Holder. If no Submission Requirements are present, all Input Descriptors MUST be satisfied.

Input Descriptor Objects contain an identifier, a schema URI that links to the schema of the requested input data, and may contain constraints on data values, and an explanation why a certain item or set of data is being requested:

EXAMPLE
{
  "presentation_definition": {
    "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "input_descriptors": [
      {
        "id": "banking_input_1",
        "name": "Bank Account Information",
        "purpose": "We can only remit payment to a currently-valid bank account.",
        "group": [
          "A"
        ],
        "schema": [
          {
            "uri": "https://bank-schemas.org/1.0.0/accounts.json"
          },
          {
            "uri": "https://bank-schemas.org/2.0.0/accounts.json"
          }
        ],
        "constraints": {
          "fields": [
            {
              "path": [
                "$.issuer",
                "$.vc.issuer",
                "$.iss"
              ],
              "purpose": "We can only verify bank accounts if they are attested by a trusted bank, auditor or regulatory authority.",
              "filter": {
                "type": "string",
                "pattern": "did:example:123|did:example:456"
              }
            },
            {
              "path": [
                "$.credentialSubject.account[*].id",
                "$.vc.credentialSubject.account[*].id",
                "$.account[*].id"
              ],
              "purpose": "We can only remit payment to a currently-valid bank account in the US, France, or Germany, submitted as an ABA Acct # or IBAN.",
              "filter": {
                "type": "string",
                "pattern": "^[0-9]{10-12}|^(DE|FR)[0-9]{2}\\s?([0-9a-zA-Z]{4}\\s?){4}[0-9a-zA-Z]{2}$"
              }
            },
            {
              "path": [
                "$.credentialSubject.account[*].route",
                "$.vc.credentialSubject.account[*].route",
                "$.account[*].route"
              ],
              "purpose": "We can only remit payment to a currently-valid account at a US, Japanese, or German federally-accredited bank, submitted as an ABA RTN or SWIFT code.",
              "filter": {
                "type": "string",
                "pattern": "^[0-9]{9}|^([a-zA-Z]){4}([a-zA-Z]){2}([0-9a-zA-Z]){2}([0-9a-zA-Z]{3})?$"
              }
            }
          ]
        }
      }
    ]
  }
}

EXAMPLE
{
  "presentation_definition": {
    "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "input_descriptors": [
      {
        "id": "employment_input_xyz_gov",
        "group": ["B"],
        "schema": [
          {
            "uri": "https://login.idp.com/xyz.gov/.well-known/openid-configuration",
            "required": true
          }
        ],
        "name": "Verify XYZ Government Employment",
        "purpose": "Verifying current employment at XYZ Government agency as proxy for permission to access this resource",
        "constraints": {
          "fields": [
            {
              "path": ["$.status"],
              "filter": {
                "type": "string",
                "pattern": "active"
              }
            }
          ]
        }
      }
    ]
  }
}

§ Input Descriptor Object

Input Descriptor Objects are composed as follows:

§ Submission Requirements

Presentation Definitions MAY include Submission Requirements which define what combinations of inputs a processing entity must submit to comply with the requirements of a Verifier.

Submission Requirements introduce a set of rule types and mapping instructions a processing entity can ingest to present requirement optionality to the user, and subsequently submit inputs in a way that maps back to the rules the Verifier has asserted.

The following section defines the format for Submission Requirements and the selection syntax Verifiers can use to specify which combinations of inputs are acceptable.

If present, all Submission Requirements MUST be satisfied, and all input_descriptors MUST be grouped. Any unused [ref:Input Descriptors]] that remain after satisfying all Submission Requirements MUST be ignored.

EXAMPLE
{
  "submission_requirements": [
    {
      "name": "Banking Information",
      "purpose": "We need you to prove you currently hold a bank account older than 12months.",
      "rule": "pick",
      "count": 1,
      "from": "A"
    },
    {
      "name": "Employment Information",
      "purpose": "We are only verifying one current employment relationship, not any other information about employment.",
      "rule": "all",
      "from": "B"
    },
    {
      "name": "Citizenship Information",
      "rule": "pick",
      "count": 1,
      "from_nested": [
        {
          "name": "United States Citizenship Proofs",
          "purpose": "We need you to prove your US citizenship.",
          "rule": "all",
          "from": "C"
        },
        {
          "name": "European Union Citizenship Proofs",
          "purpose": "We need you to prove you are a citizen of an EU member state.",
          "rule": "all",
          "from": "D"
        }
      ]
    }
  ]
}

§ Submission Requirement Objects

Submission Requirement Objects are JSON objects constructed as follows:

§ Submission Requirement Rules

Submission Requirement Rules are used within Submission Requirement Objects to describe the specific combinatorial rules that must be applied to submit a particular subset of reqested inputs. The specified Submission Requirement Rule determines the behavior of the corresponding from or from_nested property, as described below. A conformant implementation MUST support the following rules:

§ all rule

For an all rule Submission Requirement Object:

EXAMPLE
{
  "submission_requirements": [
    {
      "name": "Submission of educational transcripts",
      "purpose": "We need your complete educational transcripts to process your application",
      "rule": "all",
      "from": "A"
    }
  ]
}

§ pick rule

For a pick rule Submission Requirement Object:

If Submission Requirement Object has a from property, this directs the processing entity to submit inputs from the set of Input Descriptors with a matching group string. In the first example that follows, the Submission Requirement requests a single input from Input Descriptor group "B". In the second example, the Submission Requirement requests from 2 to 4 inputs from Input Descriptor group "B".

EXAMPLE
{
  "submission_requirements": [
    {
      "name": "Citizenship Proof",
      "purpose": "We need to confirm you are a citizen of one of the following countries before accepting your application",
      "rule": "pick",
      "count": 1,
      "from": "B"
    }
  ]
}
EXAMPLE
{
  "submission_requirements": [
    {
      "name": "Eligibility to Work Proof",
      "purpose": "We need to prove you are eligible for full-time employment in 2 or more of the following countries",
      "rule": "pick",
      "min": 2,
      "from": "B"
    }
  ]
}

If the Submission Requirement Object has a from_nested property, this directs the processing entity to submit inputs such that the number of satisfied Submission Requirement Objects matches the number requested. In the following example, the from_nested property contains an array of Submission Requirement Objects which requests either all members from group "A" or two members from group "B":

EXAMPLE
{
  "submission_requirements": [
    {
      "name": "Confirm banking relationship or employment and residence proofs",
      "purpose": "Recent bank statements or proofs of both employment and residence will be validated to initiate your loan application but not stored",
      "rule": "pick",
      "count": 1,
      "from_nested": [
        { "rule": "all", "from": "A" },
        { "rule": "pick", "count": 2, "from": "B" }
      ]
    }
  ]
}

§ JSON Schema

The following JSON Schema Draft 7 definition summarizes many of the format-related rules above:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "submission_requirements": {
      "type": "object",
      "oneOf": [
        {
          "properties": {
            "name": { "type": "string" },
            "purpose": { "type": "string" },
            "rule": {
              "type": "string",
              "enum": ["all", "pick"]
            },
            "count": { "type": "integer", "minimum": 1 },
            "min": { "type": "integer", "minimum": 0 },
            "max": { "type": "integer", "minimum": 0 },
            "from": { "type": "string" }
          },
          "required": ["rule", "from"],
          "additionalProperties": false
        },
        {
          "properties": {
            "name": { "type": "string" },
            "purpose": { "type": "string" },
            "rule": {
              "type": "string",
              "enum": ["all", "pick"]
            },
            "count": { "type": "integer", "minimum": 1 },
            "min": { "type": "integer", "minimum": 0 },
            "max": { "type": "integer", "minimum": 0 },
            "from_nested": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/definitions/submission_requirements"
              }
            }
          },
          "required": ["rule", "from_nested"],
          "additionalProperties": false
        }
      ]
    }
  },
  "type": "object",
  "properties": {
    "submission_requirements": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/submission_requirements"
      }
    }
  },
  "required": ["submission_requirements"],
  "additionalProperties": false
}

§ Property Values and Evaluation

The following property value and evaluation guidelines summarize many of the processing-related rules above:

§ Input Evaluation

A processing entity of a Presentation Definition must filter inputs they hold (signed Claims, raw data, etc.) to determine whether they possess the inputs requested by the Verifier. A processing entity of a Presentation Definition SHOULD use the following process to validate whether or not its candidate inputs meet the requirements it describes:

For each Input Descriptor in the input_descriptors array of a Presentation Definition, a processing entity SHOULD compare each candidate input (JWT, Verifiable Credential, etc.) it holds to determine whether there is a match.

For each candidate input:

  1. The URI for the schema of the candidate input MUST match one of the Input Descriptor schema object uri values exactly.

    If the Input Descriptor schema object uri is a hashlink or similar value that points to immutable content, then the content of the retrieved schema must also match.

    If one of the values is an exact match, proceed, if there are no exact matches, skip to the next candidate input.

  2. If the constraints property of the Input Descriptor is present, and it contains a fields property with one or more field objects, evaluate each against the candidate input as follows:

    1. Iterate the Input Descriptor path array of JSONPath string expressions from 0-index, executing each expression against the candidate input. Cease iteration at the first expression that returns a matching Field Query Result and use the result for the rest of the field’s evaluation. If no result is returned for any of the expressions, skip to the next candidate input.
    2. If the filter property of the field entry is present, validate the Field Query Result from the step above against the JSON Schema descriptor value.
    3. If the predicate property of the field entry is present, a boolean value should be returned rather than the value of the Field Query Result. Calculate this boolean value by evaluating the Field Query Result against the JSON Schema descriptor value of the filter property.
    4. If the result is valid, proceed iterating the rest of the fields entries.
  3. If all of the previous validation steps are successful, mark the candidate input as a match for use in a Presentation Submission.

    If present at the top level of the Input Descriptor, keep a relative reference to the group values the input is designated for.

  4. If the constraints property of the Input Descriptor is present, and it contains a limit_disclosure property set to the string value required, ensure that any subsequent submission of data in relation to the candidate input is limited to the entries specified in the fields property. If the fields property is not present, or contains zero field objects, submission SHOULD NOT include any Claim data from the Claim. For example, a Verifier may simply want to know a Holder has a valid, signed Claims of a particular type, without disclosing any of the data it contains.

  5. If the constraints property of the Input Descriptor is present, and it contains a subject_is_issuer property set to the value required, ensure that any submission of data in relation to the candidate input is fulfilled using a self_attested Claim.

  6. If the constraints property of the Input Descriptor is present, and it contains an is_holder property, ensure that for each object in the array, any submission of data in relation to the candidate input is fulfilled by the Subject of the attributes so identified by the strings in the field_id array.

  7. If the constraints property of the Input Descriptor is present, and it contains a same_subject property, ensure that for each object in the array, all of the attributes so identified by the strings in the field_id array are about the same Subject.

NOTE

The above evaluation process assumes the processing entity will test each candidate input (JWT, Verifiable Credential, etc.) it holds to determine if it meets the criteria for inclusion in submission. Any additional testing of a candidate input for a schema match beyond comparison of the schema uri is at the discretion of the implementer.

§ Expired and Revoked Data

Certain types of Claims have concepts of expiration and revocation. Expiration is mechanism used to communicate a time after which a Claim will no longer be valid. Revocation is a mechanism used by an issuer to express the status of a Claim after issuance. Different Claim specifications handle these concepts in different ways.

Presentation Definitions have a need to specify whether expired, revoked, or Claims of other statuses can be accepted. For Claims that have simple status properties, Input Descriptor Filters JSON Schema can be used to specify acceptable criteria.

The first example below demonstrates expiry using the VC Data Model’s expirationDate property. The second example below demonstrates revocation, or more generally, credential status using the VC Data Model’s credentialStatus property. Using the syntax provided in the example, a Verifier will have all requisite information to resolve the status of a Claim.

EXAMPLE
{
  "id": "drivers_license_information",
  "name": "Verify Valid License",
  "purpose": "We need you to show that your driver's license will be valid through December of this year.",
  "schema": [
    {
      "uri": "https://yourwatchful.gov/drivers-license-schema.json",
      "required": true
    }
  ],
  "constraints": {
    "fields": [
      {
        "path": ["$.expirationDate"],
        "filter": {
          "type": "string",
          "format": "date-time",
          "minimum": "2020-12-31T23:59:59.000Z"
        }
      }
    ]
  }
}
EXAMPLE
{
  "id": "drivers_license_information",
  "name": "Verify Valid License",
  "purpose": "We need to know that your license has not been revoked.",
  "schema": [
    {
      "uri": "https://yourwatchful.gov/drivers-license-schema.json"
    }
  ],
  "constraints": {
    "fields": [
      {
        "path": ["$.credentialStatus"]
      }
    ]
  }
}

§ Holder and Subject Binding

Claims often rely on proofs of Holder or Subject binding for their validity. A Verifier may wish to determine that a particular Claim, or set of Claims is bound to a particular Holder or Subject. This can help the Verifier to determine the legitimacy of the presented proofs.

Some mechanisms which enable proof of Holder binding are described below. These include proof of identifier control, proof the Holder knows a secret value, and biometrics. An Issuer can make proofs of Holder binding possible by including Holder information either in the Claim or the Claim signature.

Some examples of Subject binding include matching the Subject of one Claim with that of another, or matching the Subject of a Claim with the Holder.

§ Proof of Identifier Control

A number of Claim types include an identifier for the Claim Subject. A Verifier may wish to ascertain that one of the Subject identified in the Claim is the one submitting the proof, or has consented to the proof submission. A Claim may also include an identifier for the Holder, independent of the Subject identifiers.

One mechanism for providing such proofs is the use of a DID as the identifier for the Claim Subject or Holder. DIDs enable an entity to provide a cryptographic proof of control of the identifier, usually through a demonstration that the DID Controller knows some secret value, such as a private key.

The Holder or Subject can demonstrate this proof of control when the Claim is presented. In addition to verifying the authenticity and origin of the Claim itself, a Verifier can verify that the Holder or Subject of the Claim still controls the identifier.

Some Claim signatures support the inclusion of Holder-provided secrets that become incorporated into the signature, but remain hidden from the Claim issuer. One common use of this capability is to bind the Claim to the Holder. This is sometimes called a link secret.

Just as with proof of control of an identifier, link secret proofs demonstrate that the Holder knows some secret value. Upon presentation to a Verifier, the Holder demonstrates knowledge of the secret without revealing it. The Verifier can verify that the Holder knows the link secret, and that the link secret is contained in the Claim signature. The Holder can provide this proof for each presented Claim, thereby linking them together.

§ Biometrics

This type of Holder binding, instead of relying on demonstrating knowledge of some secret value, relies on the evaluation of biometric data. There are a number of mechanisms for safely embedding biometric information in a Claim such that only a person who can confirm the biometric may present the Claim.

§ JSON Schema

The following JSON Schema Draft 7 definition summarizes the format-related rules above:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Presentation Definition",
  "definitions": {
    "schema": {
      "type": "object",
      "properties": {
        "uri": { "type": "string" },
        "required": { "type": "boolean" }
      },
      "required": ["uri"],
      "additionalProperties": false
    },
    "filter": {
      "type": "object",
      "properties": {
        "type": { "type": "string" },
        "format": { "type": "string" },
        "pattern": { "type": "string" },
        "minimum": { "type": ["number", "string"] },
        "minLength": { "type": "integer" },
        "maxLength": { "type": "integer" },
        "exclusiveMinimum": { "type": ["number", "string"] },
        "exclusiveMaximum": { "type": ["number", "string"] },
        "maximum": { "type": ["number", "string"] },
        "const": { "type": ["number", "string"] },
        "enum": {
          "type": "array",
          "items": { "type": ["number", "string"] }
        },
        "not": {
          "type": "object",
          "minProperties": 1
        }
      },
      "required": ["type"],
      "additionalProperties": false
    },
    "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
      },
      "additionalProperties": false
    },
    "submission_requirements": {
      "type": "object",
      "oneOf": [
        {
          "properties": {
            "name": { "type": "string" },
            "purpose": { "type": "string" },
            "rule": {
              "type": "string",
              "enum": ["all", "pick"]
            },
            "count": { "type": "integer", "minimum": 1 },
            "min": { "type": "integer", "minimum": 0 },
            "max": { "type": "integer", "minimum": 0 },
            "from": { "type": "string" }
          },
          "required": ["rule", "from"],
          "additionalProperties": false
        },
        {
          "properties": {
            "name": { "type": "string" },
            "purpose": { "type": "string" },
            "rule": {
              "type": "string",
              "enum": ["all", "pick"]
            },
            "count": { "type": "integer", "minimum": 1 },
            "min": { "type": "integer", "minimum": 0 },
            "max": { "type": "integer", "minimum": 0 },
            "from_nested": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/definitions/submission_requirements"
              }
            }
          },
          "required": ["rule", "from_nested"],
          "additionalProperties": false
        }
      ]
    },
    "input_descriptors": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "purpose": { "type": "string" },
        "group": {
          "type": "array",
          "items": { "type": "string" }
        },
        "schema": {
          "type": "array",
          "items": { "$ref": "#/definitions/schema" }
        },
        "constraints": {
          "type": "object",
          "properties": {
            "limit_disclosure": {
              "type": "string",
              "enum": ["required", "preferred"]
            },
            "statuses": {
              "type": "object",
              "properties": {
                "active": {
                  "type": "object",
                  "properties": {
                    "directive": {
                      "type": "string",
                      "enum": ["required", "allowed", "disallowed"]
                    }
                  }
                },
                "suspended": {
                  "type": "object",
                  "properties": {
                    "directive": {
                      "type": "string",
                      "enum": ["required", "allowed", "disallowed"]
                    }
                  }
                },
                "revoked": {
                  "type": "object",
                  "properties": {
                    "directive": {
                      "type": "string",
                      "enum": ["required", "allowed", "disallowed"]
                    }
                  }
                }
              }
            },
            "fields": {
              "type": "array",
              "items": { "$ref": "#/definitions/field" }
            },
            "subject_is_issuer": {
              "type": "string",
              "enum": ["required", "preferred"]
            },
            "is_holder": {
              "type": "array",
              "items": {
                "type": "object",
                "properties":  {
                  "field_id": {
                    "type": "array",
                    "items": { "type": "string" }
                  },
                  "directive": {
                    "type": "string",
                    "enum": ["required", "preferred"]
                  }
                },
                "required": ["field_id", "directive"],
                "additionalProperties": false
              }
            },
            "same_subject": {
              "type":  "array",
              "items": {
                "type": "object",
                "properties":  {
                  "field_id": {
                    "type": "array",
                    "items": { "type": "string" }
                  },
                  "directive": {
                    "type": "string",
                    "enum": ["required", "preferred"]
                  }
                },
                "required": ["field_id", "directive"],
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        }
      },
      "required": ["id", "schema"],
      "additionalProperties": false
    },
    "field": {
      "type": "object",
      "oneOf": [
        {
          "properties": {
            "id": { "type": "string" },
            "path": {
              "type": "array",
              "items": { "type": "string" }
            },
            "purpose": { "type": "string" },
            "filter": { "$ref": "#/definitions/filter" }
          },
          "required": ["path"],
          "additionalProperties": false
        },
        {
          "properties": {
            "id": { "type": "string" },
            "path": {
              "type": "array",
              "items": { "type": "string" }
            },
            "purpose": { "type": "string" },
            "filter": { "$ref": "#/definitions/filter" },
            "predicate": {
              "type": "string",
              "enum": ["required", "preferred"]
            }
          },
          "required": ["path", "filter", "predicate"],
          "additionalProperties": false
        }
      ]
    }
  },
  "type": "object",
  "properties": {
    "presentation_definition": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "purpose": { "type": "string" },
        "format": { "$ref": "#/definitions/format"},
        "submission_requirements": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/submission_requirements"
          }
        },
        "input_descriptors": {
          "type": "array",
          "items": { "$ref": "#/definitions/input_descriptors" }
        }
      },
      "required": ["id", "input_descriptors"],
      "additionalProperties": false
    }
  }
}

§ Presentation Request

A Presentation Request is any transport mechanism used to send a Presentation Definition from a Verifier to a Holder. A wide variety of transport mechanisms or Claim exchange protocols may be used to send Presentation Definitions. This specification does not define Presentation Requests and is designed to be agnostic to them. Please note, however, that different use cases, supported signature schemes, protocols, and threat models may require a Presentation Requestto have certain properties. Some of these are expressed below:

  • Signature verification - Strongly identifying the entity making a request via a presentation definition is outside the scope of this specification, however a Holder may wish to have assurances as to the provenance, identity, or status of a Presentation Definition. In this case, a Presentation Request that uses digital signatures may be required.
  • Replay protection - Some presentation protocols may require that presentations be unique, i.e., it should be possible for a Verifier to detect if a presentation has been used before. Other protocols may require that a presentation be bound to a particular communication exchange or session. In these cases, a Presentation Request that provides a domain, challenge,or nonce value may be required.

§ Presentation Submission

Presentation Submissions are objects embedded within target Claim negotiation formats that express how the inputs presented as proofs to a Verifier are provided in accordance with the requirements specified in a Presentation Definition. Embedded Presentation Submission objects MUST be located within target data format as the value of a presentation_submission property, which is composed and embedded as follows:

  • The presentation_submission object MUST be included at the top-level of an Embed Target, or in the specific location described in the Embed Locations table in the Embed Target section below.
  • The presentation_submission object MUST contain an id property. The value of this property MUST be a unique identifier, such as a UUID.
  • The presentation_submission object MUST contain a definition_id property. e value of this property MUST be the id value of a valid Presentation Definition.
  • The presentation_submission object MUST include a descriptor_map property. The value of this property MUST be an array of Input Descriptor Mapping Objects, composed as follows:
    • The descriptor_map object MUST include an id property. The value of this property MUST be a string that matches the id property of the Input Descriptor in the Presentation Definition that this Presentation Submission is related to.
    • The descriptor_map object MUST include a format property. The value of this property MUST be a string that matches one of the Claim Format Designation. This denotes the data format of the Claim.
    • The descriptor_map object MUST include a path property. The value of this property MUST be a JSONPath string expression. The path property indicates the Claim submitted in relation to the identified Input Descriptor, when executed against the top-level of the object the Presentation Submission is embedded within.
    • The object MAY include a path_nested object to indicate the presence of a multi-Claim envelope format. This means the Claim indicated is to be decoded separately from its parent enclosure.
      • The format of a path_nested object mirrors that of a descriptor_map property. The nesting may be any number of levels deep. The id property MUST be the same for each level of nesting.
      • The path property inside each path_nested property provides a relative path within a given nested value.
EXAMPLE
{ 
  // NOTE: VP, OIDC, DIDComm, or CHAPI outer wrapper properties would be here.
  
  "presentation_submission": {
    "id": "a30e3b91-fb77-4d22-95fa-871689c322e2",
    "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "descriptor_map": [
      {
        "id": "banking_input_2",
        "format": "jwt_vc",
        "path": "$.verifiableCredential[0]"
      },
      {
        "id": "employment_input",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[1]"
      },
      {
        "id": "citizenship_input_1",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[2]"
      }
    ]
  }
  
}

§ Processing of path_nested Entries

Example Nested Submission

{
  "presentation_submission": {
    "id": "a30e3b91-fb77-4d22-95fa-871689c322e2",
    "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "descriptor_map": [
      {
        "id": "banking_input_2",
        "format": "jwt_vp",
        "path": "$.outerClaim[0]",
        "path_nested": {
          "id": "banking_input_2",
          "format": "ldp_vc",
          "path": "$.innerClaim[1]",
          "path_nested": {
            "id": "banking_input_2",
            "format": "jwt_vc",
            "path": "$.mostInnerClaim[2]"
          }
        }
      }
    ]
  }
}

When the path_nested property is present in a Presentation Submission object, process as follows:

  1. For each Nested Submission Traversal Object in the path_nested array:
    1. Execute the JSONPath expression string on the Current Traversal Object, or if none is designated, the top level of the Embed Target.
    2. Decode and parse the value returned from JSONPath execution in accordance with the Claim Format Designation specified in the object’s format property. If the value parses and validates in accordance with the Claim Format Designation specified, let the resulting object be the Current Traversal Object
    3. If present, process the next Nested Submission Traversal Object in the current path_nested property.
  2. If parsing of the Nested Submission Traversal Objects in the path_nested property produced a valid value, process it as the submission against the Input Descriptor indicated by the id property of the containing Input Descriptor Mapping Object.

§ Limited Disclosure Submissions

For all Claims submitted in relation to Input Descriptor Objects that include a constraints object with a limit_disclosure property set to the string value required, ensure that the data submitted is limited to the entries specified in the fields property of the constraints object. If the fields property is not present, or contains zero field objects, the submission SHOULD NOT include any data from the Claim. For example, a Verifier may simply want to know whether a Holder has a valid, signed Claim of a particular type, without disclosing any of the data it contains.

§ Validation of Claims

Once a Claim has been ingested via a Presentation Submission, any validation beyond the process of evaluation defined by the Input Evaluation section is outside the scope of Presentation Exchange. Verification of signatures and other cryptographic proofs are a function of the given Claim format, and should be evaluated in accordance with the given Claim format’s standardized processing steps. Additional verification of Claim data or subsequent validation required by a given Verifier are left to the Verifier's systems, code and business processes to define and execute.

During validation, each Input Descriptor Object MUST only refer to a single discrete container within a Presentation Submission, such that all checks refer to properties within the same container and are protected by the same digital signature, if the container format supports digital signatures. Examples of discrete container formats include a single Verifiable Credential within a Verifiable Presentation as defined in W3C Verifiable Credentials, OpenID Connect Tokens, and JSON Web Tokens. This is to ensure that related requirements, for example, “given name” and “family name” within the same Input Descriptor Object also come from the same container.

§ Embed Targets

The following section details where the Presentation Submission 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 presentation_submission 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 following JSON Schema Draft 7 definition summarizes the rules above:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Presentation Submission",
  "type": "object",
  "properties": {
    "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": ["presentation_submission"],
  "additionalProperties": false
}

§ Claim Format Designations

Within the Presentation Exchange specification, there are numerous sections where Verifiers and Holders convey what Claim variants they support and are submitting. The following are the normalized references used within the specification:

  • jwt - the format is a JSON Web Token (JWTs) [RFC7797] that will be submitted in the form of a JWT encoded string. Expression of supported algorithms in relation to this format MUST be conveyed using an alg property paired with values that are identifiers from the JSON Web Algorithms registry [RFC7518].
  • jwt_vc, jwt_vp - these formats are JSON Web Tokens (JWTs) [RFC7797] that will be submitted in the form of a JWT encoded string, and the body of the decoded JWT string is defined in the JSON Web Token (JWT) [RFC7797] section of the W3C Verifiable Credentials specification. Expression of supported algorithms in relation to these formats MUST be conveyed using an alg property paired with values that are identifiers from the JSON Web Algorithms registry [RFC7518].
  • ldp_vc, ldp_vp - these formats are W3C Verifiable Credentials [VC-DATA-MODEL] that will be submitted in the form of a JSON object. Expression of supported algorithms in relation to these formats MUST be conveyed using a proof_type property paired with values that are identifiers from the Linked Data Cryptographic Suite Registry.
  • ldp - this format is defined in the W3C CCG Linked Data Proofs specification [[spec:Linked Data Proofs]], and will be submitted as objects. Expression of supported algorithms in relation to these formats MUST be conveyed using a proof_type property with values that are identifiers from the Linked Data Cryptographic Suite Registry.

§ JSON Schema Vocabulary Definition

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

§ JSONPath Syntax Definition

The Presentation Exchange specification adopts and defines the following syntax from the JSONPath object query language, which implementers MUST support for evaluation of the portions of the Presentation Exchange specification that call for JSONPath expression execution.

JSONPath Description
$ The root object/element
@ The current object/element
. Child member operator
.. Recursive descendant operator; JSONPath borrows this syntax from E4X
* Wildcard matching all objects/elements regardless their names
[] Subscript operator
[,] Union operator for alternate names or array indices as a set
[start:end:step] Array slice operator borrowed from ES4 / Python
?() Applies a filter (script) expression via static evaluation
() Script expression via static evaluation

Example JSON Object

{
  "store": {
    "book": [ 
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      }, {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      }, {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      }, {
        "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}

Example JSONPath Expressions

JSONPath Description
$.store.book[*].author The authors of all books in the store
$..author All authors
$.store.* All things in store, which are some books and a red bicycle
$.store..price The price of everything in the store
$..book[2] The third book
$..book[(@.length-1)] The last book via script subscript
$..book[-1:] The last book via slice
$..book[0,1] The first two books via subscript union
$..book[:2] The first two books via subscript array slice
$..book[?(@.isbn)] Filter all books with isbn number
$..book[?(@.price<10)] Filter all books cheaper than 10
$..book[?(@.price==8.95)] Filter all books that cost 8.95
$..book[?(@.price<30 && @.category=="fiction")] Filter all fiction books cheaper than 30
$..* All members of JSON structure

§ Normative References

OIDC
Open ID Connect. Jones, M., Bradley, J., and N. Sakimura. Status: Approved Specification

RFC7518
JSON Web Algorithms (JWA). M. Jones; 2015-05. Status: Proposed Standard.
RFC7797
JSON Web Signature (JWS) Unencoded Payload Option. M. Jones; 2016-02. Status: Proposed Standard.
VC-DATA-MODEL
Verifiable Credentials Data Model 1.0. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; 2019-11-19. Status: REC.

§ Informative References

CHAPI
W3C Credential Handler API 1.0. Dave Longley, Manu Sporny. 2020-2-19. Status: Draft Community Group Report.
DIDComm
DIF DIDComm Messaging. Daniel Hardman, Sam Curren. Status: Working Group Draft.

§ Appendix

§ Embed Target Examples

§ Presentation Submissions

EXAMPLE
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://identity.foundation/presentation-exchange/submission/v1"
  ],
  "type": [
    "VerifiablePresentation",
    "PresentationSubmission"
  ],
  "presentation_submission": {
    "id": "a30e3b91-fb77-4d22-95fa-871689c322e2",
    "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "descriptor_map": [
      {
        "id": "banking_input_2",
        "format": "jwt_vc",
        "path": "$.verifiableCredential[0]"
      },
      {
        "id": "employment_input",
        "format": "ldp_vc",
        "path": "$.verifiableCredential[1]"
      },
      {
        "id": "citizenship_input_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": "..."
  }
}

EXAMPLE
{
  "iss": "https://self-issued.me",
  "sub": "248289761001",
  "preferred_username": "superman445",
  "presentation_submission": {
    "id": "a30e3b91-fb77-4d22-95fa-871689c322e2",
    "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "descriptor_map": [
      {
        "id": "banking_input_2",
        "format": "jwt",
        "path": "$._claim_sources.banking_input_2.JWT"
      },
      {
        "id": "employment_input",
        "format": "jwt_vc",
        "path": "$._claim_sources.employment_input.VC_JWT"
      },
      {
        "id": "citizenship_input_1",
        "format": "ldp_vc",
        "path": "$._claim_sources.citizenship_input_1.VC"
      }
    ]
  },
  "_claim_names": {
    "verified_claims": [
      "banking_input_2",
      "employment_input",
      "citizenship_input_1"
    ]
  },
  "_claim_sources": {
    "banking_input_2": {
      "JWT": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5vdGhlcm9wLmNvbSIsInN1YiI6ImU4MTQ4NjAzLTg5MzQtNDI0NS04MjViLWMxMDhiOGI2Yjk0NSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoiaWFsX2V4YW1wbGVfZ29sZCJ9LCJjbGFpbXMiOnsiZ2l2ZW5fbmFtZSI6Ik1heCIsImZhbWlseV9uYW1lIjoiTWVpZXIiLCJiaXJ0aGRhdGUiOiIxOTU2LTAxLTI4In19fQ.FArlPUtUVn95HCExePlWJQ6ctVfVpQyeSbe3xkH9MH1QJjnk5GVbBW0qe1b7R3lE-8iVv__0mhRTUI5lcFhLjoGjDS8zgWSarVsEEjwBK7WD3r9cEw6ZAhfEkhHL9eqAaED2rhhDbHD5dZWXkJCuXIcn65g6rryiBanxlXK0ZmcK4fD9HV9MFduk0LRG_p4yocMaFvVkqawat5NV9QQ3ij7UBr3G7A4FojcKEkoJKScdGoozir8m5XD83Sn45_79nCcgWSnCX2QTukL8NywIItu_K48cjHiAGXXSzydDm_ccGCe0sY-Ai2-iFFuQo2PtfuK2SqPPmAZJxEFrFoLY4g"
    },
    "employment_input": {
      "VC": {
        "@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": "..."
        }
      }
    },
    "citizenship_input_1": {
      "VC": {
        "@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": "EcdsaSecp256k1VerificationKey2019",
          "created": "2017-06-18T21:19:10Z",
          "proofPurpose": "assertionMethod",
          "verificationMethod": "https://example.edu/issuers/keys/1",
          "jws": "..."
        }
      }
    }
  }
}

EXAMPLE
{
    "type": "web",
    "dataType": "VerifiablePresentation",
    "data": {
      "comment": "Presentation Submission goes here"
    }
  }
  
EXAMPLE
{
    "@type": "https://didcomm.org/present-proof/%VER/presentation",
    "@id": "f1ca8245-ab2d-4d9c-8d7d-94bf310314ef",
    "comment": "some comment",
    "formats" : [{
        "attach_id" : "2a3f1c4c-623c-44e6-b159-179048c51260",
        "format" : "dif/presentation-exchange/[email protected]"
    }],
    "presentations~attach": [{
        "@id": "2a3f1c4c-623c-44e6-b159-179048c51260",
        "mime-type": "application/ld+json",
        "data": {
            "json": {
              "comment": "Presentation Submission goes here"
            }
        }
    }]
}

§ Developer Resources

§ JSONPath

§ JSON Schema

§ IANA Considerations

§ JSON Web Token Claims Registration

This specification registers the Claims in section Registry Contents in the IANA JSON Web Token Claims registry defined in RFC 751 JSON Web Token (JWT).

§ Registry Contents
Presentation Definition Values
Claim Name: presentation_definition
Claim Description: Presentation Definition
Change Controller: DIF Claims & Credentials - Working Group - https://github.com/decentralized-identity/claims-credentials/blob/main/CODEOWNERS
Specification Document(s): Section 5 of this document
Presentation Submission Values
Claim Name: presentation_submission
Claim Description: Presentation Submission
Change Controller: DIF Claims & Credentials - Working Group - https://github.com/decentralized-identity/claims-credentials/blob/main/CODEOWNERS
Specification Document(s): Section 6 of this document
Table of Contents