Presentation Definition

Presentation Definition is a standardized data format that enables verifiers to clearly articulate proof requirements to holders in decentralized identity systems. Developed by the Decentralized Identity Foundation (DIF), it addresses the fundamental challenge of how parties can request specific verifiable information in a consistent, interoperable way.

Why use Presentation Definition?

When a verifier needs specific information from a holder to proceed with a transaction or service, they need a clear way to communicate exactly what’s required. Presentation Definition solves this by providing:

• A standardized format for requesting credentials that is system-agnostic
• Clear articulation of which credential fields are required
• Support for complex requirement combinations through logical operators
• A way to specify constraints on acceptable credential formats and issuers
• Built-in support for selective disclosure of information

Without Presentation Definition, each verifier would need to implement custom request formats, leading to compatibility issues, poor user experience, and increased development costs across the ecosystem.

What is a Presentation Definition?

A Presentation Definition is a JSON object that specifies:

1. What kinds of credentials a verifier needs to see
2. Which specific fields within those credentials are required
3. What combinations of credentials satisfy the requirements
4. Any specific constraints on the credential data

At its core, a Presentation Definition contains:

• A unique identifier
• One or more input descriptors that define required credentials
• Optional submission requirements that specify logical combinations of inputs
• Format-specific requirements for credential types

Here’s a simplified example requesting email verification:

{
    "id": "user_verification_example",
    "input_descriptors": [
        {
            "id": "email_credential",
            "name": "Email Verification",
            "purpose": "We need to verify your email address",
            "constraints": {
                "fields": [
                    {
                        "path": ["$.type"],
                        "filter": {
                            "type": "array",
                            "contains": { "type": "string", "pattern": "EmailCredential" }
                        }
                    },
                    {
                        "path": ["$.credentialSubject.email"],
                        "purpose": "The email address must be verified",
                        "filter": { "type": "string", "format": "email" }
                    }
                ]
            }
        }
    ]
}

How Presentation Definition Works

Presentation Definition is one part of a complete credential exchange process. Here’s how it fits into the workflow between a verifier and a holder:

1. Request Formation: The verifier creates a Presentation Definition specifying the credentials and fields they require
2. Request Transmission: The definition is sent to the holder via a transport protocol (OIDC, DIDComm, etc.)
3. Holder Processing: The holder’s wallet/agent interprets the definition to understand what’s being requested
4. Credential Selection: The holder selects credentials that satisfy the requirements

After these steps, the holder responds with a Presentation Submission that maps their credentials to the requirements specified in the Presentation Definition. For details on that process, see the Presentation Submission documentation.

sequenceDiagram
    participant Verifier
    participant Holder

    Note over Verifier: 1. Creates Presentation Definition
    Verifier->>Holder: 2. Sends Presentation Definition
    Note over Holder: 3. Processes the definition
    Note over Holder: 4. Selects matching credentials
    Note over Verifier,Holder: Returns Presentation submission

Core Components

Input Descriptors

Input Descriptors are the primary building blocks of a Presentation Definition. Each descriptor specifies:

• A unique ID for reference in the Presentation Submission
• A human-readable name and purpose
• Constraints on the credential fields required
• Format requirements for the credential

Input Descriptors use JSONPath expressions to target specific fields within credentials, allowing for precise requirements.

Constraints

Constraints define specific requirements for credential fields. They can:

• Specify required fields through the “path” property
• Apply filters to validate field values
• Set requirements for specific formats or patterns
• Limit acceptable values to an enumerated set
• Apply complex validations through JSON Schema

For example, a constraint might require a credential field to match a specific pattern:

"constraints": {
  "fields": [
    {
      "path": ["$.credentialSubject.birthDate"],
      "filter": {
        "type": "string",
        "format": "date"
      }
    }
  ]
}

Submission Requirements

Submission Requirements enable verifiers to specify logical combinations of Input Descriptors. They support:

• The “all” rule: all inputs from a group must be submitted
• The “pick” rule: a minimum number of inputs from a group must be submitted
• Nested rules for complex combinations

For example, requiring either an ID card or a combination of other credentials:

"submission_requirements": [
  {
    "rule": "pick",
    "min": 1,
    "from": [
      {
        "rule": "all",
        "from": ["A"]
      },
      {
        "rule": "all",
        "from": ["B", "C"]
      }
    ]
  }
]

This flexibility allows verifiers to express requirements like “provide either a government ID, or both a proof of address and proof of employment.”

Format Agnosticism

One key strength of Presentation Definition is its independence from specific credential formats. It works with:

• Verifiable Credentials (W3C VC Data Model)
• JSON Web Tokens (JWTs)
• JSON Web Credentials (JWT-VCs)
• OpenID Connect tokens
• Any other JSON-serializable claim format

This flexibility ensures broad compatibility across different identity systems and credential types.

Relationship with Presentation Submission

Presentation Definition and Presentation Submission work together as complementary parts of the credential exchange process:

• Presentation Definition: Specifies what the verifier wants (the request)
• Presentation Submission: Describes how the holder’s presented credentials satisfy the definition (the response)

When a verifier sends a Presentation Definition, they expect to receive a Presentation Submission in return that maps the provided credentials to the requirements in the definition. For detailed information on how Presentation Submission works, see the Presentation Submission documentation.

Use Cases

Presentation Definition enables numerous verification scenarios:

Authentication

When used with protocols like Self-Issued OpenID Provider v2 (SIOP), Presentation Definition allows verifiers to request specific identity attributes during authentication, combining traditional login with verified attribute checking.

Selective Disclosure

By precisely defining which credential fields are required, Presentation Definition enables holders to share only the specific information a verifier needs, preserving privacy while still satisfying verification requirements.

Credential Composition

Verifiers can use Submission Requirements to specify complex combinations of credentials from different issuers to satisfy verification needs, such as “education credential from an accredited university AND proof of residence.”

Cross-Protocol Integration

The format-agnostic design allows Presentation Definition to work across different transport protocols, enabling consistent credential requests regardless of the underlying communication channel.

Integration with Vidos

In the Vidos ecosystem, Presentation Definition plays a key role in the OpenID for Verifiable Presentations (OpenID4VP) flow:

• Authorizer Service: The Authorizer provides the Presentation Definition to the wallet during the OpenID4VP authorize flow. This definition specifies exactly which credentials and fields the wallet needs to present to satisfy the verifier’s requirements.

• Validator Service: The Validator uses the Presentation Definition as a reference point to check the Presentation Submission as part of validator policies. It ensures that the presented credentials match what was requested.

For example, when a user initiates an authentication flow, the Vidos Authorizer generates the appropriate Presentation Definition based on the configured policies, sends it to the user’s wallet, and later receives the corresponding Presentation Submission. The Authorizer then passes both the definition and submission to the Validator to verify that the presented credentials satisfy the original requirements.

Summary

Presentation Definition provides a standardized, interoperable way for verifiers to request specific verified attributes from holders. By clearly defining what credentials and fields are required, it enables consistent credential requests across different systems and formats.

Key benefits include:

• Standardized format for credential requests
• Support for complex logical combinations of requirements
• Format-agnostic design for broad compatibility
• Precise specification of required fields for enhanced privacy
• Reduced implementation complexity across the ecosystem

Through Presentation Definition, the Vidos platform enables standardized, interoperable verification workflows that respect privacy while providing the flexibility needed for diverse verification scenarios.

Further Resources

• DIF Presentation Exchange Specification