Define a credential schema

What is a credential schema?

A credential schema defines the structure of claims for a specific type of credential. Credential schemas ensure that credentials follow a consistent structure, making them easier to validate, share, and verify.

To represent static schemas created in the app code, follow this page to use user-defined types (UDTs), which allow you to specify the required fields, data types, and any linked credentials or files. To represent dynamic schemas (for example, created by end users from a frontend app), you need to work directly with the API as described in the following how-to guide.

Prerequisites

Install and configure the SDK

Example: Define a basic credential schema

You can define credential schemas using UDTs, which represent the structure of claims within a credential. For example, a basic ClaimsModelExample schema can include name and age claims:

TypeScript

@VcSchema()
class ClaimsModelExample {
    @VcClaim
    name?: string;

    @VcClaim
    age?: number;
}

Java

@VcSchema
class ClaimsModelExample {
    String name;

    int age;
}

Example: Define an advanced credential schema

You can define more complex schemas that include different value types, linked credentials, file attachments, and more.

Example: Enum values

Use the @VcStringEnumClaim decorator to define enum values:

TypeScript

@VcSchema()
class ClaimsModelExample {
    @VcStringEnumClaim([
        { value: "option1", title: "Option 1" },
        { value: "option2", title: "Option 2" },
    ])
    field1?: "option1" | "option2";
}

Java

@VcSchema
class ClaimsModelExample {
    @EnumClaim({
        @EnumClaimValue(value = "option1", title = "Option 1"),
        @EnumClaimValue(value = "option1", title = "Option 1")
    })
    String field1;
}

Example: Date and date-time values

To pass date or date-time claim values use two specially defined data types:

• Rfc3339Date - use this claims type when you want to define a date without time.
• Rfc3339DateTime - use this claims type when you want to define the date including time (it is equivalent to the JavaScript Date type).

For example:

TypeScript

@VcSchema()
class ClaimsModelExample {
    @VcClaim
    field1?: Rfc3339Date;

    @VcClaim
    field2?: Rfc3339DateTime;
}

Java

@VcSchema
class ClaimsModelExample {
    LocalDate field1;

    OffsetDateTime field2;
}

Example: Required values

Use the @VcNotEmptyClaim to set the claim as required:

TypeScript

@VcSchema()
class ClaimsModelExample {
    @VcNotEmptyClaim
    field1!: number;

    @VcClaim
    field2?: string;
}

Java

@VcSchema
class ClaimsModelExample {
    @NotEmpty
    int field1;

    String field2;
}

Example: Array values

If you need to pass an array of primitive or nested struct claims, use the @VcArrayClaim. This is used to set the data type of the items in the array claim.

For example:

TypeScript

@VcSchema()
class ClaimsModelExample {
    @VcArrayClaim(Number)
    field1?: number[];
}

Java

@VcSchema
class ClaimsModelExample {
    List<Integer> field1;
}

Example: Nested structures

Define a nested structure based on the following example:

TypeScript

@VcSchema()
class NestedStruct {
    @VcArrayClaim(Number)
    field1?: number[];
}

@VcSchema()
class ClaimsModelExample {
    @VcClaim
    field1?: NestedStruct;
}

Java

@VcSchema
class NestedStruct {
    List<Integer> field1;
}

@VcSchema
class ClaimsModelExample {
    NestedStruct field1;
}

Further reading

You can use UDTs to link credentials to each other and files to credentials. Refer to the following pages for more details:

• Link credentials
• Link files

From schema definition to management

Defining a credential schema is the first step toward building a trustworthy digital ecosystem. While you can immediately use this schema to create a draft and issue a credential, you need to think about schema publication, versioning, and lifecycle management for a production-ready and interoperable solution. The Credential Schemas section provides comprehensive documentation on all these topics, empowering you to build future-proof solutions.