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
Section titled “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
Section titled “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
Section titled “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:
- Format detection - Identifies the credential format through structure analysis
- Format-specific validation - Applies validation rules specific to the detected format
- Structure validation - Ensures the credential conforms to format specifications
- Data extraction - Extracts credential data into a standardized format
- Result generation - Returns formatted credential data or validation errors
Format-Specific Validation
Section titled “Format-Specific Validation”W3C Verifiable Credentials (JSON-LD)
Section titled “W3C Verifiable Credentials (JSON-LD)”For W3C VC JSON-LD credentials, the policy:
- Validates JSON-LD structure - Ensures proper JSON-LD format
- Checks @context values - Validates context URLs and references
- Validates required fields - Ensures mandatory VC fields are present
- Checks credential types - Validates the
type
field values - Assesses version compatibility - Ensures the VC version is supported
W3C Verifiable Presentations (JSON-LD)
Section titled “W3C Verifiable Presentations (JSON-LD)”For W3C VP JSON-LD presentations, the policy:
- Validates presentation structure - Ensures proper VP JSON-LD format
- Extracts embedded credentials - Identifies and extracts contained credentials
- Validates presentation context - Checks JSON-LD context for presentations
- Validates presentation types - Ensures proper VP type values
- Maintains credential relationships - Preserves credential-to-presentation mapping
JWT-based Credentials
Section titled “JWT-based Credentials”For JWT-based credentials and presentations, the policy:
- Parses JWT structure - Validates JWT header, payload, and signature format
- Extracts credential claims - Retrieves credential data from JWT payload
- Validates JWT headers - Ensures proper JWT header structure
- Handles nested credentials - Extracts VCs from JWT VPs when present
- Preserves JWT metadata - Maintains JWT-specific information
IETF SD-JWT Digital Credentials
Section titled “IETF SD-JWT Digital Credentials”For IETF SD-JWT Digital Credentials, the policy:
- Validates SD-JWT structure - Ensures proper SD-JWT format with disclosures
- Processes selective disclosure - Handles disclosed and undisclosed claims
- Validates VCT claims - Ensures proper verifiable credential type
- Extracts credential data - Processes both disclosed and compact claims
- Maintains disclosure state - Preserves selective disclosure information
ISO 18013-5 Mobile Driving License
Section titled “ISO 18013-5 Mobile Driving License”For mDL credentials, the policy:
- Decodes Base64URL - Converts base64url-encoded mDL to binary
- Parses CBOR structure - Validates CBOR-encoded mDL document
- Validates mDL schema - Ensures proper mDL document structure
- Extracts document data - Processes mDL document and namespaces
- Validates version compatibility - Ensures mDL version is supported
Shared Policy Architecture
Section titled “Shared Policy Architecture”The credential format policy is a shared policy used by both the validator and verifier services:
Validator Service Integration
Section titled “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
Section titled “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
Section titled “Configuration”The format validation policy supports comprehensive configuration:
Format Support Configuration
Section titled “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
Section titled “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
Section titled “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
Section titled “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 |