Presentation Submission

Presentation Submission is a standardized data format that enables holders to clearly communicate how their presented credentials satisfy a verifier's requirements. Developed by the Decentralized Identity Foundation (DIF), it addresses the challenge of providing a consistent response format in credential exchange systems.

Why use Presentation Submission?

When a holder needs to present credentials in response to a verifier's request, they need a clear way to indicate which credentials satisfy which requirements. Presentation Submission solves this by providing:

  • A standardized format for mapping credentials to verification requirements
  • Clear indication of which credentials fulfill which requirements
  • Support for different credential formats within a single submission
  • A consistent structure that works across transport protocols
  • Simplified verification through structured response format

Without Presentation Submission, verifiers would struggle to process and verify presented credentials, leading to integration challenges, verification errors, and an inconsistent user experience.

What is a Presentation Submission?

A Presentation Submission is a JSON object that maps presented credentials to the requirements specified in a Presentation Definition. It contains:

  1. A reference to the Presentation Definition being responded to
  2. A mapping between Input Descriptor IDs and the actual credentials being presented
  3. Information about where to find each credential within the submission
  4. Details about the format of each presented credential

At its core, a Presentation Submission contains:

  • The identifier of the Presentation Definition it's responding to
  • A descriptor map that links required inputs to provided credentials
  • Path information indicating where to find each credential

Here's a simplified example responding to an email verification request:

{
    "definition_id": "user_verification_example",
    "descriptor_map": [
        {
            "id": "email_credential",
            "format": "jwt_vc",
            "path": "$.verifiableCredential[0]"
        }
    ]
}

How Presentation Submission Works

The Presentation Submission is a crucial part of the credential exchange process. After receiving a Presentation Definition, a holder:

  1. Analyzes Requirements: Examines the Presentation Definition to understand what's being requested
  2. Matches Credentials: Identifies which of their credentials satisfy the requirements
  3. Creates Mapping: Builds a Presentation Submission that maps their credentials to the defined requirements
  4. Packages Response: Includes both the credentials and the Presentation Submission in their response
  5. Submits Response: Sends the complete package back to the verifier
  6. Verification: The verifier uses the Presentation Submission to locate and verify each credential

Core Components

Descriptor Map

The descriptor_map is the central component of a Presentation Submission. It contains an array of descriptor objects, each mapping a specific input descriptor from the Presentation Definition to a credential in the submission. Each descriptor includes:

  • id: Matches an input descriptor ID from the Presentation Definition
  • format: Indicates the format of the credential (e.g., "jwt_vc", "ldp_vc")
  • path: A JSONPath expression pointing to where the credential can be found

For example:

"descriptor_map": [
  {
    "id": "driver_license_credential",
    "format": "ldp_vc",
    "path": "$.verifiableCredential[1]"
  },
  {
    "id": "proof_of_address",
    "format": "jwt_vc",
    "path": "$.verifiableCredential[0]"
  }
]

Definition ID Reference

The definition_id property links the Presentation Submission to the specific Presentation Definition it's responding to. This ensures the verifier can connect the response to their original request:

"definition_id": "identity_verification_request_12345"

Format Specifications

The format property within each descriptor indicates how the credential is encoded or structured. Common formats include:

  • jwt_vc: JSON Web Token Verifiable Credential
  • jwt_vp: JSON Web Token Verifiable Presentation
  • ldp_vc: Linked Data Proof Verifiable Credential
  • ldp_vp: Linked Data Proof Verifiable Presentation
  • mso_mdoc: Mobile Security Object (ISO mdoc)

This information helps the verifier correctly process and verify each credential according to its specific format requirements.

Relationship with Presentation Definition

Presentation Submission can only be understood in relation to a Presentation Definition:

  • Presentation Definition specifies what credentials and fields a verifier requires
  • Presentation Submission explains how the presented credentials satisfy those requirements

Each Input Descriptor in a Presentation Definition has a corresponding entry in the Presentation Submission's descriptor_map. This mapping is what allows verifiers to efficiently locate and process the credentials they requested.

The submission doesn't repeat the requirements—it simply provides a navigational aid that helps the verifier connect their requirements with the actual credentials being presented. For details on Presentation Definition, see the Presentation Definition documentation.

ID Token Mapping

In environments that integrate with OpenID Connect, Presentation Submission can work with ID Token Mapping to transform verified credentials into standard OIDC claims:

  1. A verifier requests specific credentials through a Presentation Definition that includes ID token mapping instructions
  2. The holder provides credentials in a Presentation Submission
  3. The system extracts specific fields from these credentials using the paths in the Presentation Submission
  4. These fields are mapped into standard ID token claims as specified in the mapping

This process creates a bridge between verifiable credentials and traditional identity protocols. For example:

"idTokenMapping": [
  {
    "sourceField": "$.credentialSubject.email",
    "idTokenClaim": "email",
    "inputDescriptorId": "email_credential"
  },
  {
    "sourceField": "$.credentialSubject.name",
    "idTokenClaim": "name",
    "inputDescriptorId": "profile_credential"
  }
]

Use Cases

Presentation Submission enables several important scenarios in credential exchange:

Multi-credential Responses

When a verification requires multiple credentials, Presentation Submission clearly indicates which credential satisfies which requirement, making complex verification scenarios manageable.

Format-flexible Verification

Verifiers can accept credentials in different formats (JWT, Linked Data Proofs, etc.) and still efficiently process them through the format specifications in the descriptor_map.

Selective Disclosure Response

When responding to requests that require only specific fields from credentials, the Presentation Submission clearly maps the precise parts of credentials that satisfy the requirements, supporting privacy-preserving verification.

Protocol Bridging

The consistent structure allows credentials to be presented across different protocols while maintaining a clear mapping to requirements, enabling interoperability across diverse systems.

Integration with Vidos

In the Vidos ecosystem, Presentation Submission is a critical component of the OpenID for Verifiable Presentations (OpenID4VP) flow:

  • Authorizer Service: The Authorizer receives the Presentation Submission from the wallet during the OpenID4VP authorize flow. This submission contains the credentials presented by the wallet and explains how they map to the requirements specified in the Presentation Definition.

  • Validator Service: When the Authorizer receives a Presentation Submission, it calls the Validator to check both the submission and the original definition as part of the validator policies. The Validator ensures that:

    • The credentials in the submission match the formats requested in the definition
    • All required fields are present in the submitted credentials
    • The credentials meet all constraints specified in the definition
    • The logical combinations of credentials satisfy the submission requirements

This architecture provides a clear separation of concerns, where the Authorizer handles the protocol flow while the Validator performs the specialized task of credential verification against the specified requirements.

Summary

Presentation Submission provides a standardized, interoperable way for holders to communicate how their presented credentials satisfy verification requirements. By clearly mapping credentials to requirements, it enables consistent credential verification across different systems and formats.

Key benefits include:

  • Clear mapping between requirements and credentials
  • Support for multiple credentials in a single response
  • Format flexibility for broad compatibility
  • Simplified verification through structured response format
  • Reduced implementation complexity across the ecosystem

Through Presentation Submission, the Vidos platform enables standardized, interoperable verification workflows that allow credentials to be clearly and efficiently presented in response to verification requirements.

Further Resources