Define credential schema

What is a credential schema?

A credential schema defines the structure of claims for a specific type of credential. These schemas are represented using User-Defined Types (UDTs), which allow you to specify the required fields, data types, and any linked credentials or files. Credential schemas ensure that credentials follow a consistent structure, making them easier to validate, share, and verify.

Each credential schema is associated with a namespace, ensuring that the schema is unique and can be recognized across different systems.

Prerequisites

Install and configure the SDK

JSON schemas

Truvity SDK can work with any credentials that are compliant with Verifiable Credentials Data Model v1.1, so it is up to you to decide how to manage schemas inside credentials. However, if you want to display your credentials to users you should use JSON Schema to describe credential claims data types and visual annotations such as labels and descriptions.

tip

To learn more about differences between Contexts, Types, and CredentialSchemas, refer to the Verifiable Credentials Data Model v1.1 specification.

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
Java

@VcContext({ name: "ClaimsModelExample", namespace: "https://www.w3.org/ns/credentials/issuer-dependent" })
class ClaimsModelExample {
    @VcClaim
    name?: string;

    @VcClaim
    age?: number;
}

@Data
@VcContext(name = "ClaimsModelExample", namespace = "https://www.w3.org/ns/credentials/issuer-dependent")
public static class ClaimsModelExample {
    private Optional<String> name;

    private Optional<Integer> age;
}

In this schema:

VcContext specifies the name and namespace of the schema

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
Java

@VcContext({ name: "ClaimsModelExample", namespace: "https://www.w3.org/ns/credentials/issuer-dependent" })
class ClaimsModelExample {
    @VcStringEnumClaim([
        { value: "option1", title: "Option 1" },
        { value: "option2", title: "Option 2" },
    ])
    field1?: "option1" | "option2";
}

@Data
@VcContext(name = "ClaimsModelExample", namespace = "https://www.w3.org/ns/credentials/issuer-dependent")
public static class ClaimsModelExample {
    @EnumClaim({
        @EnumClaimValue(value = "option1", title = "Option 1"),
        @EnumClaimValue(value = "option1", title = "Option 1")
    })
    private Optional<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
Java

@VcContext({ name: "ClaimsModelExample", namespace: "https://www.w3.org/ns/credentials/issuer-dependent" })
class ClaimsModelExample {
    @VcClaim
    field1?: Rfc3339Date;

    @VcClaim
    field2?: Rfc3339DateTime;
}

@Data
@VcContext(name = "ClaimsModelExample", namespace = "https://www.w3.org/ns/credentials/issuer-dependent")
public static class ClaimsModelExample {
    private Optional<LocalDate> field1;

    private Optional<OffsetDateTime> field2;
}

Example: Required values

Use the @VcNotEmptyClaim to set the claim as required:

TypeScript
Java

@VcContext({ name: "ClaimsModelExample", namespace: "https://www.w3.org/ns/credentials/issuer-dependent" })
class ClaimsModelExample {
    @VcNotEmptyClaim
    field1!: number;

    @VcClaim
    field2?: string;
}

@Data
@VcContext(name = "ClaimsModelExample", namespace = "https://www.w3.org/ns/credentials/issuer-dependent")
public static class ClaimsModelExample {
    @NotEmpty
    private Integer field1;

    private Optional<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
Java

@VcContext({ name: "ClaimsModelExample", namespace: "https://www.w3.org/ns/credentials/issuer-dependent" })
class ClaimsModelExample {
    @VcArrayClaim(Number)
    field1?: number[];
}

@Data
@VcContext(name = "ClaimsModelExample", namespace = "https://www.w3.org/ns/credentials/issuer-dependent")
public static class ClaimsModelExample {
    Optional<List<Integer>> field1;
}

Example: Nested structures

Define a nested structure based on the following example:

TypeScript
Java

@VcContext({ name: "NestedStruct", namespace: "https://www.w3.org/ns/credentials/issuer-dependent" })
class NestedStruct {
    @VcArrayClaim(Number)
    field1?: number[];
}

@VcContext({ name: "ClaimsModelExample", namespace: "https://www.w3.org/ns/credentials/issuer-dependent" })
class ClaimsModelExample {
    @VcClaim
    field1?: NestedStruct;
}

@Data
@VcContext(name = "NestedStruct", namespace = "https://www.w3.org/ns/credentials/issuer-dependent")
public static class NestedStruct {
    Optional<List<Integer>> field1;
}

@Data
@VcContext(name = "ClaimsModelExample", namespace = "https://www.w3.org/ns/credentials/issuer-dependent")
public static class ClaimsModelExample {
    Optional<NestedStruct> field1;
}

Define credential schema

What is a credential schema?​

JSON schemas

Example: Define a basic credential schema​

Example: Define an advanced credential schema​

Example: Enum values​

Example: Date and date-time values​

Example: Required values​

Example: Array values​

Example: Nested structures​

Further reading​