Credential Schemas

What are credential schemas?

Credential schemas are structural blueprints that define the format and constraints of verifiable credentials. They ensure consistent formatting across the ecosystem—similar to how physical credentials like driver’s licenses follow standard templates.

Schemas help all participants—issuers, holders, and verifiers—interpret credential data consistently. When issuers create credentials according to published schemas, verifiers can validate their structure and establish trust through predictable formats.

Role in the verifiable credentials ecosystem

Schemas provide data integrity, interoperability, and trust:

graph TD
    A[Issuer] -->|Creates credentials using| B[Credential Schema]
    C[Holder] -->|Presents credentials conforming to| B
    D[Verifier] -->|Validates credentials against| B
    B -->|Ensures| E[Consistent Interpretation]

The W3C Verifiable Credentials Data Model defines schemas through the credentialSchema property, which verifiers use to determine structural conformance. Schemas are important when you’re:

• Standardizing credential types across issuers
• Processing credentials from multiple sources
• Verifying structure programmatically
• Establishing industry-specific templates

JSON Schema implementation

The W3C Verifiable Credentials JSON Schema specification uses JSON Schema standards for validation.

Here’s a credential schema reference:

"credentialSchema": {
  "id": "https://example.com/schemas/email.json",
  "type": "JsonSchema"
}

The id points to the schema document. The type specifies the validation mechanism.

Here’s a schema definition example:

{
    "$id": "https://example.com/schemas/email.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "EmailCredential",
    "type": "object",
    "properties": {
        "credentialSubject": {
            "type": "object",
            "properties": {
                "emailAddress": {
                    "type": "string",
                    "format": "email"
                }
            },
            "required": ["emailAddress"]
        }
    }
}

This schema validates that credentials contain a credentialSubject with a properly formatted emailAddress.

JsonSchemaCredential

You can package schemas as verifiable credentials for additional trust:

• Verify schema authorship
• Validate schema validity periods
• Prevent tampering

JsonSchemaCredential combines verifiable credential features with JSON Schema, adding cryptographic proofs to the schema.

Schema validation process

Schema validation follows four steps:

1. Identify the schema reference in the credentialSchema property
2. Resolve the schema by dereferencing the URL
3. Validate the credential structure against the schema
4. Continue with other verification steps if valid

Schema resolution involves security considerations, especially for remote-hosted schemas.

Key considerations

Validation scope: Schemas can validate entire credentials, only credentialSubject properties, or specific fields.

Versioning: Include versions in URLs, manage backward compatibility, and document changes.

Privacy: Design schemas that support data minimization and selective disclosure. Don’t use overly specific schemas that leak information.

Distribution: Balance centralized repositories (convenient but vulnerable) with decentralized storage (resilient but complex). Cache frequently used schemas.

Relationship to data integrity

Schemas work with data integrity mechanisms to create comprehensive trust:

• Schemas: Ensure correct structure and data types
• Data integrity proofs: Ensure credentials remain unaltered
• Status mechanisms: Verify credentials remain unrevoked

Together, these create a foundation for trusted credential exchange.

Summary

Credential schemas provide structured templates that enable consistent interpretation of credential data across all parties. Well-designed schemas enhance interoperability, establish trust, and facilitate automated processing.

Schemas form one part of verification. Complete verification also requires cryptographic validation, status checking, and trust establishment.