Input Descriptors

Input Descriptors are the core building blocks of Presentation Exchange that enable verifiers to precisely articulate what credential data they need from holders. They form the foundation of Presentation Definitions in credential exchange workflows, providing both the technical schema and the human-readable context for data requests.

What are input descriptors?

Input Descriptors define specific credential data requirements a verifier needs from a holder. They allow verifiers to:

Specify exactly which credential fields are needed
Define constraints on acceptable values
Set requirements for credential formats
Configure disclosure limitations to enhance privacy
Express the purpose for requesting specific information

Input Descriptors bridge technical verification requirements with meaningful user consent by being both machine-processable and human-readable.

Why use input descriptors?

Input Descriptors solve key challenges in decentralized identity verification:

Standardized requests: Create consistent credential data requests across different systems and formats
Precise targeting: Request exactly the data points needed while respecting privacy
Format flexibility: Work with various credential formats (VCs, JWTs, etc.) through a single mechanism
Enhanced privacy: Enable selective disclosure and data minimization
Clear expectations: Communicate to holders what information is needed and why

Without Input Descriptors, credential verification would require custom, non-interoperable request formats or overly broad data sharing that compromises privacy.

Core structure

An Input Descriptor consists of a unique identifier, optional descriptive properties for user understanding, and constraints that define acceptable credentials:

{
    "id": "employment_credential",
    "name": "Proof of Employment",
    "purpose": "We need to verify your current employment status",
    "constraints": {
        "fields": [
            {
                "path": ["$.type", "$.vc.type"],
                "filter": {
                    "type": "array",
                    "contains": {
                        "type": "string",
                        "pattern": "^EmploymentCredential$"
                    }
                }
            }
        ]
    }
}

The structure includes:

id (required): Unique identifier for the descriptor
name (optional): Human-readable label
purpose (optional): Explanation of why this information is requested
format (optional): Acceptable credential formats and cryptographic requirements
group (optional): Identifiers for use in submission requirements
constraints (required): Rules defining acceptable credentials

How input descriptors work

Targeting credential data

Input Descriptors use JSONPath expressions to locate specific data within credentials. Since credentials may have different structures depending on their format, multiple path options can be provided:

"path": ["$.credentialSubject.dateOfBirth", "$.vc.credentialSubject.dateOfBirth"]

The system evaluates paths from left to right until finding a match. This flexibility accommodates format variations while maintaining precise data targeting.

Validating values

Filters use JSON Schema to validate found values. They can check data types, enforce patterns, require specific values, or apply complex validation rules:

"filter": {
    "type": "string",
    "enum": ["Employed", "Full-time", "Part-time"]
}

Fields can be marked as optional, allowing credentials to be accepted even when certain data is absent—though present data must still satisfy filter requirements.

Privacy controls

The limit_disclosure property controls information sharing:

required: Holder must only share requested fields
preferred: Holder should limit disclosure when possible
(omitted): No specific disclosure constraints

This enables data minimization by requesting only necessary information.

Format requirements

Input Descriptors can specify acceptable credential formats and cryptographic algorithms:

"format": {
    "jwt_vc": {
        "alg": ["ES256K", "EdDSA"]
    }
}

This ensures credentials are presented in formats the verifier can process and verify.

Advanced capabilities

Input Descriptors support several advanced features for complex verification scenarios:

Holder and Subject Binding: Ensures credentials are bound to the holder or that multiple credentials share the same subject
Predicate-Based Disclosure: Allows proving statements about data (e.g., “over 18”) without revealing the actual value
Status Checking: Validates credential status (active, revoked, suspended) before acceptance

These features enable privacy-preserving verification patterns and more sophisticated credential requirements. For detailed specifications, see the DIF Presentation Exchange specification.

Role in Vidos

The Validator service processes Input Descriptors to match presented credentials against verifier requirements, applying validation rules, privacy controls, and format-specific verification before allowing interactions to proceed.

Example: age verification

A privacy-preserving age verification descriptor:

{
    "id": "age_verification",
    "name": "Age Verification",
    "purpose": "Verify you meet the minimum age requirement",
    "constraints": {
        "limit_disclosure": "required",
        "fields": [
            {
                "path": ["$.credentialSubject.birthDate"],
                "filter": {
                    "type": "string",
                    "format": "date"
                }
            }
        ]
    }
}

This descriptor requests only the birthdate field, limiting disclosure to the minimum information needed for age verification.

Summary

Input Descriptors enable precise, privacy-respecting credential verification by:

Providing standardized credential data requests
Supporting multiple credential formats
Enabling selective disclosure and data minimization
Clearly communicating requirements to holders
Balancing security with privacy considerations

They form the detailed specification layer that makes Presentation Exchange flexible and privacy-preserving.