Validator Configuration Reference

This reference documents the configuration options for the validator service. The validator service validates credential structure, format, and completeness before cryptographic verification.

Core Configuration

This section documents the complete configuration provided by Vidos.

{
    "cors": {
        "enabled": false,
        "origin": ["*"],
        "credentials": false,
        "allowMethods": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
        "exposeHeaders": [],
        "allowHeaders": [],
        "maxAge": 86400
    },
    "policies": {
        "credentialFormat": {
            "standards": {
                "w3c": {
                    "vc-data-model": {
                        "v1.1": {
                            "enabled": true
                        },
                        "v2.0": {
                            "enabled": true
                        }
                    }
                },
                "iso": {
                    "18013-5:2021": {
                        "enabled": true
                    }
                }
            }
        },
        "trustedIssuer": {
            "skip": false,
            "trustedIssuerRootCertificates": [
                {
                    "type": "predefined",
                    "tag": "vidos"
                }
            ]
        },
        "presentationSubmission": {
            "skip": false,
            "onPresentationEvaluationWarning": "warning"
        }
    }
}

Configuration Schema

The complete JSON Schema for the validator configuration is available:

• Download validator.schema.json

Configuration Options

cors Configuration

For CORS configuration options see the CORS Configuration Reference.

policies Configuration

The policies section consists of independent validation policies that can be configured separately. Each policy controls a specific aspect of credential validation and focuses on structural integrity rather than cryptographic verification. Policies can be:

• Enabled or disabled independently using skip: true/false
• Configured with different validation behaviors (error/warning/valid)
• Set with policy-specific parameters

The validator supports the following validation policies:

• credentialFormat: Format and structure validation
• trustedIssuer: Trusted issuer certificate validation
• presentationSubmission: Presentation submission validation

Example of policy configuration:

{
    "policies": {
        "credentialFormat": {
            "standards": {
                "w3c": {
                    "vc-data-model": {
                        "v1.1": {
                            "enabled": true
                        },
                        "v2.0": {
                            "enabled": false
                        }
                    }
                }
            }
        },
        "trustedIssuer": {
            "skip": false,
            "trustedIssuerRootCertificates": [
                {
                    "type": "predefined",
                    "tag": "aamva"
                }
            ]
        },
        "presentationSubmission": {
            "skip": true
        }
    }
}

Each policy section below details its specific configuration options.

credentialFormat

Controls credential format and structure validation.

• Type: object
• Properties:
  • standards: Supported credential format standards
    • w3c: W3C Verifiable Credentials Data Model
    • iso: ISO standard formats
• Description: Configures supported credential format standards and versions for structural validation
• See: W3C VC Data Model

The credential format policy validates that credentials conform to the expected structure, contain required fields, and follow the format specification before any cryptographic verification takes place.

Example configuration:

{
    "credentialFormat": {
        "standards": {
            "w3c": {
                "vc-data-model": {
                    "v1.1": {
                        "enabled": true
                    },
                    "v2.0": {
                        "enabled": true
                    }
                }
            },
            "iso": {
                "18013-5:2021": {
                    "enabled": true
                }
            }
        }
    }
}

Supported Standards

Standard	Version	Description	Validation Focus
w3c.vc-data-model.v1.1	1.1	W3C Verifiable Credentials Data Model v1.1	JSON-LD structure, required fields, context validation
w3c.vc-data-model.v2.0	2.0	W3C Verifiable Credentials Data Model v2.0	Enhanced structure, multi-proof support, secured formats
iso.18013-5:2021	2021	ISO 18013-5 Mobile Driving License	CBOR structure, mDL-specific fields, ISO compliance

trustedIssuer

Controls trusted issuer certificate validation.

• Type: object
• Properties:
  • skip: boolean - Whether to skip trusted issuer validation
  • trustedIssuerRootCertificates: Array of trusted certificate configurations
• Description: Configures trusted issuer certificate validation for credential issuers
• See: Certificate Trust Chains

The trusted issuer policy validates that credentials are issued by trusted entities based on certificate chains and root certificates.

Example configuration:

{
    "trustedIssuer": {
        "skip": false,
        "trustedIssuerRootCertificates": [
            {
                "type": "predefined",
                "tag": "vidos"
            },
            {
                "type": "pem",
                "pem": "-----BEGIN CERTIFICATE-----\nMIIBkTCB+wIJANkB9AUFGEqkMA0GCSqGSIb3DQEBCwUA...\n-----END CERTIFICATE-----"
            }
        ]
    }
}

Trusted Certificate Types

The validator supports multiple methods for specifying trusted issuer certificates:

PEM Certificate

Direct PEM-encoded certificate specification:

{
    "type": "pem",
    "pem": "-----BEGIN CERTIFICATE-----\nMIIBkTCB+wIJANkB9AUFGEqkMA0GCSqGSIb3DQEBCwUA...\n-----END CERTIFICATE-----"
}

VICAL Certificate

VICAL (Verifiable Issuer Certificate Authority List) format:

{
    "type": "vical",
    "cbor": "base64-encoded-cbor-data",
    "vicalTrustedCertificates": [
        "-----BEGIN CERTIFICATE-----\nMIIBkTCB+wIJANkB9AUFGEqkMA0GCSqGSIb3DQEBCwUA...\n-----END CERTIFICATE-----"
    ]
}

VICAL URL

VICAL certificate list retrieved from URL:

{
    "type": "vical-url",
    "url": "https://example.com/vical-list.cbor",
    "vicalTrustedCertificates": [
        "-----BEGIN CERTIFICATE-----\nMIIBkTCB+wIJANkB9AUFGEqkMA0GCSqGSIb3DQEBCwUA...\n-----END CERTIFICATE-----"
    ]
}

Predefined Certificate Sets

Predefined certificate sets for common trust anchors:

{
    "type": "predefined",
    "tag": "vidos"
}

Tag	Description	Use Case
vidos	Vidos default trust anchors	Standard Vidos ecosystem certificates
aamva	AAMVA (American Association of Motor Vehicle Administrators)	US/Canada driver’s license credentials

presentationSubmission

Controls presentation submission validation.

• Type: object
• Properties:
  • skip: boolean - Whether to skip presentation submission validation
  • onPresentationEvaluationWarning: "valid" | "error" | "warning" - Action when presentation evaluation warnings occur
• Description: Configures validation of presentation submissions against presentation definitions
• See: DIF Presentation Exchange

The presentation submission policy validates that verifiable presentations properly fulfill presentation definition requirements and contain the expected structure.

Example configuration:

{
    "presentationSubmission": {
        "skip": false,
        "onPresentationEvaluationWarning": "warning"
    }
}

Presentation Evaluation Actions

Action	Description	Use Case
valid	Treat warnings as valid	Lenient validation, warnings don’t fail validation
warning	Generate warnings	Standard validation, warnings logged but don’t fail
error	Treat warnings as errors	Strict validation, warnings cause validation failure

Example presentation submission validation:

{
    "presentation_submission": {
        "id": "example-submission",
        "definition_id": "example-definition",
        "descriptor_map": [
            {
                "id": "credential-1",
                "format": "ldp_vc",
                "path": "$.verifiableCredential[0]"
            }
        ]
    }
}

Error Handling

The validator supports three validation outcomes:

• error: Validation fails, stops processing
• warning: Validation continues with warnings
• valid: Successful validation

Common scenarios:

Scenario	Default Action	Configuration Option
Unsupported credential format	Error	credentialFormat.standards.{standard}.enabled
Missing required fields	Error	Built-in validation rules
Invalid certificate chain	Error	trustedIssuer.skip
Presentation evaluation warning	Warning	presentationSubmission.onPresentationEvaluationWarning

Environment Variables

The validator service supports configuration through environment variables:

• VALIDATOR_CORS_ENABLED - Enable CORS
• VALIDATOR_POLICIES_CREDENTIALFORMAT_STANDARDS_W3C_VC_DATA_MODEL_V1_1_ENABLED - Enable W3C VC Data Model v1.1
• VALIDATOR_POLICIES_TRUSTEDISSUER_SKIP - Skip trusted issuer validation
• VALIDATOR_POLICIES_PRESENTATIONSUBMISSION_SKIP - Skip presentation submission validation

Configuration Validation

The validator service validates its own configuration on startup to ensure:

• Required fields are present
• Configuration values are valid
• Certificate formats are correct
• Policy configurations are consistent

Integration with Other Services

The validator service integrates with other Vidos services:

• Verifier Service: Provides pre-verification validation to ensure credentials are properly structured
• Authorizer Service: Validates authorization-related fields and trusted issuer configurations
• Resolver Service: Validates DID and key reference formats before resolution

Additional Resources

• Understanding Configuration in Vidos
• Validator Service Overview
• Verifier Configuration Reference
• W3C Verifiable Credentials Data Model
• ISO 18013-5:2021 Mobile Driving License
• DIF Presentation Exchange