Skip to main content

Version a schema

Schema versioning is the mechanism for managing changes to a schema over time while preserving the immutability of existing published versions. This process ensures that old credentials remain valid against their original schema, and new credentials can be issued against an updated definition.

To create a new version of a schema, you must first create a new credential schema resource, make your changes, and then publish it with an incremented version number.

Using the SDK​

Prerequisites

The easiest way to create a new version of a schema is to define a new user-defined types (UDTs) definition with an incremented version number. You can then make your changes to the new UDT definition and publish it.

// Existing UDT definition for v1
@VcSchema(slug = "proof-of-identity", version = 1)
class ProofOfIdentityV1 {
    @NotEmpty
    String firstName;

    @NotEmpty
    String lastName;

    @NotEmpty
    double identityNumber;
}

// New UDT for v2 with an updated field type
@VcSchema(slug = "proof-of-identity", version = 2)
class ProofOfIdentityV2 {
    @NotEmpty
    String firstName;

    @NotEmpty
    String lastName;

    @NotEmpty
    String identityNumber;
}
Tip

If you want to only add new fields when extending an existing schema definition, you don't need to copy and paste the full UDT definition and can use class extension instead. The example below shows how to do it.

// Existing UDT definition for v1
@VcSchema(slug = "proof-of-identity")
class ProofOfIdentity {
    @NotEmpty
    String firstName;

    @NotEmpty
    String lastName;
}

// New UDT for v2 with an added field
@VcSchema(slug = "proof-of-identity", version = 2)
class ProofOfIdentityV2 extends ProofOfIdentity {
    @NotEmpty
    LocalDate dateOfBirth; // New field for v2
}

Using the API​

Prerequisites

For direct API access, the workflow for creating a new version involves three steps:

  1. Duplicate the existing schema resource.
  2. Modify the schema to include your changes.
  3. Publish the modified schema with a new version number.

This example assumes you have the ID of a credential schema that you want to version.

  1. Use the POST /schemas endpoint to duplicate the existing schema:
{
  "from_schema": "b4d2e7a1-c9f3-d5a8-b7c6-e1f0a3b9c2d5"
}

This request returns the resource ID of the new, duplicated schema.

  1. Use the PATCH /schemas/{id} endpoint to modify the new schema resource:
{
    "data": {
        "schema": {
            "fields": [
                {
                    "kind": "STRING",
                    "name": "projectName"
                },
                {
                    "kind": "STRING",
                    "name": "projectStatus" // Add the new field
                }
            ]
        }
    }
}
  1. Use the PATCH /schemas/{id}/publish to publish the modified schema as a new version:
{
  "slug": "project-credentials",
  "version": 2
}

Further reading​