Skip to main content

Create a schema

Before a credential schema can be published and used in a production environment, you must define it. This page provides a practical guide to creating a schema definition.

You can create schemas using two methods:

  1. Using the SDK: The recommended method for defining schemas programmatically within your code.
  2. Using the API: The method for creating schemas with a non-SDK client.

Use the SDK to define a schema​

Prerequisites

The easiest way to define a schema is by creating a user-defined type (UDT) in your code. The UDT serves as the blueprint for your schema and is associated with it via the @VcSchema decorator. This approach provides compile-time type safety and simplifies the schema definition process.

For a detailed guide on how to define schemas with various data types and code examples, refer to the Define a credential schema SDK guide.

// Define a UDT for a basic proof of identity
@VcSchema(slug = "proof-of-identity", version = 1)
class ProofOfIdentity {
    @NotEmpty
    String firstName;

    @NotEmpty
    String lastName;
}

// In your application, this UDT is used to create a decorator
VcDecorator<ProofOfIdentity> proofOfIdentity = client.vcDecorator(ProofOfIdentity.class);

// You can now create a draft or publish the schema for production

The VcSchema decorator accepts the following options:

  • slug - optional string. If the slug is not provided, this schema is considered temporary. You cannot publish the schema without a slug.
  • version - optional number. If the version is not provided, the platform defaults to version=1.
  • owner - optional string, which is a tenantId of the schema owner (another Truvity tenant). If provided, the platform uses a schema published by that owner. This establishes trust - for example, when issuing a credential that is based on the schema published by the government, you want to ensure you use a government-published schema, as verifiers only trust the government-owned schemas for such important information.

Use the API to create a schema​

Prerequisites

For direct API access, you can create a new schema resource using the POST /schemas endpoint. This method requires you to provide a schema JSON object, which is Truvity's universal meta-schema model.

This approach is useful for building applications that generate schemas dynamically (for example, from a frontend) or for integrating with non-SDK clients. The following how-to guide explains how to create applications that work with dynamic schemas created by end users.

Further reading​