Credential Format Validation Policy Reference

This reference documents the credential format validation policy used by the validator service. The format policy validates that credentials conform to supported formats and can be properly parsed before proceeding with other validation checks.

Policy Overview

The credential format validation policy is the foundation of the validator service’s validation process. It ensures that credentials are structured correctly according to supported standards and can be parsed into a standardized format for subsequent validation policies. This policy must succeed before other validation policies (credential query and trusted issuer) are executed.

Supported Standards

The format validation policy supports credential validation across multiple standards:

Standard	Organization	Specification	Format Identifier	Key Validation Features
W3C Verifiable Credentials v1.1	W3C	VC Data Model v1.1	w3:vc-data-model:json-ld	JSON-LD context validation, credential structure
W3C Verifiable Credentials v2.0	W3C	VC Data Model v2.0	w3:vc-data-model:json-ld	Enhanced JSON-LD context, updated credential structure
W3C Verifiable Presentations v1.1	W3C	VC Data Model v1.1	w3:vp-data-model:json-ld	JSON-LD presentation validation, credential wrapping
W3C Verifiable Presentations v2.0	W3C	VC Data Model v2.0	w3:vp-data-model:json-ld	Enhanced presentation structure, improved proof support
JWT Verifiable Credentials	W3C/IETF	VC Data Model + RFC 7519	jwt_vc_json	JWT structure validation, credential claims extraction
JWT Verifiable Presentations	W3C/IETF	VC Data Model + RFC 7519	jwt_vp_json	JWT presentation validation, nested credential extraction
IETF SD-JWT Digital Credentials	IETF	SD-JWT VC Draft	ietf.dc-sd-jwt	Selective disclosure validation, JWT structure
ISO 18013-5:2021 Mobile Driving License	ISO	ISO 18013-5	org.iso.18013.5	mDL document validation, CBOR structure

Format Validation Process

flowchart TD
    subgraph "Credential Format Validation"
        Input[Credential Input] --> DetectType[Format Detection]
        DetectType --> VP{VP JSON-LD?}
        DetectType --> VC{VC JSON-LD?}
        DetectType --> JWT{JWT-based?}
        DetectType --> MDL{mDL Base64?}

        VP -->|Yes| ValidateVP[Validate VP Structure]
        ValidateVP --> ExtractCreds[Extract Credentials]
        ExtractCreds --> VPResult[VP Result]

        VC -->|Yes| ValidateVC[Validate VC Structure]
        ValidateVC --> ValidateContext[Validate JSON-LD Context]
        ValidateContext --> VCResult[VC Result]

        JWT -->|Yes| ParseJWT[Parse JWT]
        ParseJWT --> ValidateJWTStructure[Validate JWT Structure]
        ValidateJWTStructure --> ExtractClaims[Extract Claims]
        ExtractClaims --> JWTResult[JWT Result]

        MDL -->|Yes| DecodeBase64[Decode Base64URL]
        DecodeBase64 --> ParseMDL[Parse mDL CBOR]
        ParseMDL --> ValidateMDLStructure[Validate mDL Structure]
        ValidateMDLStructure --> MDLResult[mDL Result]

        VP -->|No| NextCheck1[Next Format Check]
        VC -->|No| NextCheck2[Next Format Check]
        JWT -->|No| NextCheck3[Next Format Check]
        MDL -->|No| UnsupportedFormat[Unsupported Format]

        NextCheck1 --> VC
        NextCheck2 --> JWT
        NextCheck3 --> MDL

        VPResult --> Success[Format Validation Success]
        VCResult --> Success
        JWTResult --> Success
        MDLResult --> Success
        UnsupportedFormat --> Failure[Format Validation Failure]
    end

    style Input fill:#f9f9f9,stroke:#333,stroke-width:1px
    style DetectType fill:#e1f5fe,stroke:#333,stroke-width:1px
    style VP fill:#e1f5fe,stroke:#333,stroke-width:1px
    style VC fill:#e1f5fe,stroke:#333,stroke-width:1px
    style JWT fill:#e1f5fe,stroke:#333,stroke-width:1px
    style MDL fill:#e1f5fe,stroke:#333,stroke-width:1px
    style ValidateVP fill:#e8f5e8,stroke:#333,stroke-width:1px
    style ValidateVC fill:#e8f5e8,stroke:#333,stroke-width:1px
    style ValidateJWTStructure fill:#fff3e0,stroke:#333,stroke-width:1px
    style ValidateMDLStructure fill:#f3e5f5,stroke:#333,stroke-width:1px
    style Success fill:#dcedc8,stroke:#333,stroke-width:1px
    style Failure fill:#ffcdd2,stroke:#333,stroke-width:1px

When validating credential formats, the policy follows these steps:

1. Format detection - Identifies the credential format through structure analysis
2. Format-specific validation - Applies validation rules specific to the detected format
3. Structure validation - Ensures the credential conforms to format specifications
4. Data extraction - Extracts credential data into a standardized format
5. Result generation - Returns formatted credential data or validation errors

Format-Specific Validation

W3C Verifiable Credentials (JSON-LD)

For W3C VC JSON-LD credentials, the policy:

1. Validates JSON-LD structure - Ensures proper JSON-LD format
2. Checks @context values - Validates context URLs and references
3. Validates required fields - Ensures mandatory VC fields are present
4. Checks credential types - Validates the type field values
5. Assesses version compatibility - Ensures the VC version is supported

W3C Verifiable Presentations (JSON-LD)

For W3C VP JSON-LD presentations, the policy:

1. Validates presentation structure - Ensures proper VP JSON-LD format
2. Extracts embedded credentials - Identifies and extracts contained credentials
3. Validates presentation context - Checks JSON-LD context for presentations
4. Validates presentation types - Ensures proper VP type values
5. Maintains credential relationships - Preserves credential-to-presentation mapping

JWT-based Credentials

For JWT-based credentials and presentations, the policy:

1. Parses JWT structure - Validates JWT header, payload, and signature format
2. Extracts credential claims - Retrieves credential data from JWT payload
3. Validates JWT headers - Ensures proper JWT header structure
4. Handles nested credentials - Extracts VCs from JWT VPs when present
5. Preserves JWT metadata - Maintains JWT-specific information

IETF SD-JWT Digital Credentials

For IETF SD-JWT Digital Credentials, the policy:

1. Validates SD-JWT structure - Ensures proper SD-JWT format with disclosures
2. Processes selective disclosure - Handles disclosed and undisclosed claims
3. Validates VCT claims - Ensures proper verifiable credential type
4. Extracts credential data - Processes both disclosed and compact claims
5. Maintains disclosure state - Preserves selective disclosure information

ISO 18013-5 Mobile Driving License

For mDL credentials, the policy:

1. Decodes Base64URL - Converts base64url-encoded mDL to binary
2. Parses CBOR structure - Validates CBOR-encoded mDL document
3. Validates mDL schema - Ensures proper mDL document structure
4. Extracts document data - Processes mDL document and namespaces
5. Validates version compatibility - Ensures mDL version is supported

Shared Policy Architecture

The credential format policy is a shared policy used by both the validator and verifier services:

Validator Service Integration

• Primary validation step - Must succeed before other validator policies execute
• Format result dependency - Credential query and trusted issuer policies depend on format results
• Error propagation - Format validation failures prevent subsequent validation
• Performance optimization - Early format validation prevents unnecessary processing

Multi-Service Support

• Service-aware results - Policy results include service identification
• Configurable format support - Different services can enable/disable specific formats
• Consistent format detection - Same format detection logic across services
• Unified error handling - Consistent error types and messages

Configuration

The format validation policy supports comprehensive configuration:

Format Support Configuration

• W3C VC version control - Enable/disable specific VC data model versions
• ISO 18013-5 support - Enable/disable mDL format validation
• JWT format support - Control JWT-based credential validation
• SD-JWT support - Enable/disable selective disclosure JWT validation

Validation Behavior

• Strict validation - Control validation strictness for each format
• Error handling - Configure error reporting and validation failure behavior
• Performance tuning - Optimize format detection and validation performance

For detailed configuration options, see the Validator Configuration Reference.

Error Handling

The format validation policy returns specific errors for various validation failures:

Error Type	Description	Typical Cause
Unsupported Format Error	Credential format is not supported	Unknown credential format or disabled format type
Invalid Format Error	Credential format is malformed	Malformed JSON-LD, invalid JWT, corrupted CBOR
Context Resolution Error	JSON-LD context cannot be resolved	Invalid @context URLs, network issues
Structure Validation Error	Credential structure is invalid	Missing required fields, invalid field values
Version Compatibility Error	Credential version is not supported	Unsupported VC version, disabled version support

Supported Format Matrix

Format	Validator Support	Query Support	Trust Support	Notes
W3C VC JSON-LD v1.1	✅	✅	❌	Full JSON-LD validation with context resolution
W3C VC JSON-LD v2.0	✅	✅	❌	Enhanced JSON-LD with updated contexts
W3C VP JSON-LD v1.1	✅	✅	❌	Presentation validation with credential extraction
W3C VP JSON-LD v2.0	✅	✅	❌	Enhanced presentation structure
JWT VC	✅	✅	❌	JWT-based credential validation
JWT VP	✅	✅	❌	JWT presentation with nested credentials
IETF SD-JWT DC	✅	✅	✅	Selective disclosure with trust validation
ISO 18013-5 mDL	✅	✅	✅	Mobile driving license with full support

Tip

The format validation policy is essential for ensuring credential compatibility across the validator service. It provides the foundation for all other validation policies and should be configured to support the credential formats required by your specific use case.