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:

StandardOrganizationSpecificationFormat IdentifierKey Validation Features
W3C Verifiable Credentials v1.1W3CVC Data Model v1.1w3:vc-data-model:json-ldJSON-LD context validation, credential structure
W3C Verifiable Credentials v2.0W3CVC Data Model v2.0w3:vc-data-model:json-ldEnhanced JSON-LD context, updated credential structure
W3C Verifiable Presentations v1.1W3CVC Data Model v1.1w3:vp-data-model:json-ldJSON-LD presentation validation, credential wrapping
W3C Verifiable Presentations v2.0W3CVC Data Model v2.0w3:vp-data-model:json-ldEnhanced presentation structure, improved proof support
JWT Verifiable CredentialsW3C/IETFVC Data Model + RFC 7519jwt_vc_jsonJWT structure validation, credential claims extraction
JWT Verifiable PresentationsW3C/IETFVC Data Model + RFC 7519jwt_vp_jsonJWT presentation validation, nested credential extraction
IETF SD-JWT Digital CredentialsIETFSD-JWT VC Draftietf.dc-sd-jwtSelective disclosure validation, JWT structure
ISO 18013-5:2021 Mobile Driving LicenseISOISO 18013-5org.iso.18013.5mDL document validation, CBOR structure

Format Validation Process

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 TypeDescriptionTypical Cause
Unsupported Format ErrorCredential format is not supportedUnknown credential format or disabled format type
Invalid Format ErrorCredential format is malformedMalformed JSON-LD, invalid JWT, corrupted CBOR
Context Resolution ErrorJSON-LD context cannot be resolvedInvalid @context URLs, network issues
Structure Validation ErrorCredential structure is invalidMissing required fields, invalid field values
Version Compatibility ErrorCredential version is not supportedUnsupported VC version, disabled version support

Supported Format Matrix

FormatValidator SupportQuery SupportTrust SupportNotes
W3C VC JSON-LD v1.1Full JSON-LD validation with context resolution
W3C VC JSON-LD v2.0Enhanced JSON-LD with updated contexts
W3C VP JSON-LD v1.1Presentation validation with credential extraction
W3C VP JSON-LD v2.0Enhanced presentation structure
JWT VCJWT-based credential validation
JWT VPJWT presentation with nested credentials
IETF SD-JWT DCSelective disclosure with trust validation
ISO 18013-5 mDLMobile 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.