Skip to main content

Publication and versioning

Once you are ready to move a schema from a temporary development state to a production-ready resource, you must publish it. This page explains the core concepts of publishing and versioning schemas within the Truvity platform.

Schema publication​

Schema publication is the process of making a schema publicly verifiable, immutable, and discoverable. When you publish a schema, you are essentially creating a permanent, cryptographically protected record of that schema definition.

Publication is critical for building trust and ensuring the long-term integrity of the verifiable credentials (VCs) you issue. The key principles of publication are:

  • Immutability

    Once a schema is published, its definition is permanently frozen and cannot be changed. This guarantees that all credentials issued against that specific version always refer to the exact same schema definition, preventing retroactive changes that could invalidate proofs.

  • Provenance

    A published schema includes verifiable information about its origin and history, allowing all parties to trust its source.

Schema versioning​

As real-world data definitions and business requirements evolve, your schemas need to change. Schema versioning is the mechanism for managing these changes in a controlled way that respects the principle of immutability.

Instead of editing an existing published schema, you create and publish a new version. This ensures:

  • Backward compatibility

    Existing VCs issued with an older schema version remain valid and verifiable against their original, immutable definition.

  • Forward progress

    You can introduce new fields or rules in a new schema version, allowing your ecosystem to evolve without breaking old credentials.

Slugs and versions as public identifiers​

You can identify a published schema by a unique combination of a slug and a version.

  • A slug is a human-readable identifier (for example, proof-of-identity) that groups different versions of the same conceptual schema.
  • A version is a number (for example, 1, 2) that denotes a distinct iteration of that schema.

The combination of a slug and a version forms a unique, public identifier of a schema. This identifier is a stable URL that verifiers can use to retrieve the schema and validate any credential issued against it.

Further reading​

  • Manage schemas - get hands-on with the practical steps for creating, publishing, and versioning your schemas.