Skip to main content

Credential schemas

A credential schema defines the structure and meaning of information in a verifiable credential. It acts as a blueprint that helps issuers, holders, and verifiers understand what data a credential contains and how to interpret it.

What is a credential schema?​

A credential schema:

  • Defines available information

    Lists the claims (pieces of information) that a credential must include.

  • Specifies the shape of information

    Sets the type of each claim (for example, text, numbers, or dates).

  • Enforces validation rules

    Defines mandatory and optional claims, as well as allowed values (for example, if the age must be positive).

For example, a “Dutch Driving License (Issued From November 14, 2014)” schema defines claims like firstName, lastName, licenseNumber, and expiryDate. Every issued driving license credential follows this same structure.

Semantics and meaning​

Schemas organize data but don’t always explain what the data means. Semantics add this context and make sure everyone interprets claims the same way.

Without semantics, identical claim names can have different meanings:

  • status might mean employment status in one credential.
  • status might mean document approval status in another.

Semantic definitions remove this ambiguity. Systems can then process credentials consistently and accurately.

Why schemas and semantics matter​

Reusable schemas and semantics enable rapid adoption of credentials by:

  1. Ensuring consistency

    Credentials of the same type always follow the same rules.

  2. Enabling automation

    Software can validate and interpret claims without manual checks.

  3. Supporting interoperability

    Organizations can exchange credentials across platforms and maintain a shared understanding of the data.

Truvity’s approach​

Truvity provides a unified schema model that defines both structure and meaning in one place. With this model, you:

  • Define a schema once and reuse it across ecosystems.
  • Stay compatible with multiple credential standards and formats.
  • Reduce complexity when developing credential-based solutions.

Schema evolution​

Data requirements and regulations change over time, and credential schemas need to evolve without breaking trust. To do so:

  • Keep schemas immutable

    Once a schema issues credentials, it never changes.

  • Create new versions

    Introduce updated schemas for new credentials.

  • Maintain backward compatibility

    Keep older credentials valid and verifiable.

This approach ensures you can adapt to new requirements while preserving the reliability of existing credentials.

Further reading​