Managing Credential Schemas

This document explains how to define and manage credential schemas from the Schemas screen of the One-Click Deployment operator panel. A schema describes the claims a credential carries, the formats it can be issued in, and the metadata wallets use to display it. Once defined, a schema can be assigned to any of your Issuers and referenced when creating credential offers.

The Schemas screen with the schema list

---

Opening the Schemas Screen

1. Open the operator panel and click Schemas in the sidebar menu.

2. The screen lists every schema you have created, grouped by schema type (the VCT identifier, or the name when no VCT is set) and showing the active version of each.

3. Click an existing schema to view or version it, or click Create Schema to define one from scratch.

---

Defining a Schema

The schema builder authors a schema through an attribute builder form. Its columns are Attributes, JSON, AI, and History. You add each claim as an attribute using form fields, and the panel keeps an equivalent JSON view in sync (a Monaco-based editor with syntax highlighting, bracket matching, and live validation) that you can also edit directly. As you work, the panel validates the claim properties and flags errors inline before you can publish.

A schema is described by the following fields:

• name: The schema name, for example EmployeeBadge. Use a name that starts with a letter or digit and contains only letters, digits, underscores, and hyphens. The Define form itself also accepts spaces (and rejects dots), but the create-schema API the panel calls on publish enforces ^[A-Za-z0-9][A-Za-z0-9._-]*$, so names containing spaces fail at publish.

• version: The schema version. The panel assigns it automatically — a new schema starts at version 1, and each new version increments it.

• type: The Verifiable Credential Type (VCT) identifier, used for SD-JWT credentials, for example EmployeeBadgeCredential. The panel restricts this field to letters, digits, underscores, and hyphens; to publish a URL-style VCT such as https://issuer.example.com/vct/employee-badge, call POST /schemas directly with the vct field.

• description: A human-readable description of the credential. Required in the panel's Define form; optional when calling the create-schema API directly.

• attributes (claims): Each claim has a name, a type, an optional title and description, and a Required flag. Together the attributes form the JSON-Schema definition of the claims (type, properties, and required).

To define the schema:

1. Click Create Schema, then enter the schema name, description, and type and click Define New Schema to open the schema builder.

2. Add each claim using the attribute builder: set its name and type, optionally a title and description, and tick Required for mandatory claims. The panel keeps the equivalent JSON view in sync under the JSON column, which you can also edit directly.

3. Click Publish to save the schema. It becomes the active version under its name.

The Create Schema form — the schema's name, description, and type, before opening the builder

The panel publishes the schema as { name, version, description, vct, schema }. A published schema defaults to both credential formats, sd-jwt and jwt-vc-json; the panel does not offer a format field. The disclosureFrame (SD-JWT selective-disclosure keys) is likewise an option on the underlying create-schema API request rather than a field in the Schemas screen.

The schema builder — the Attributes list and live JSON view

Example Schema Definition

The attributes you add in the builder produce a schema definition like the one below. This illustrates the resulting create-schema request rather than something you type wholesale into a single editor. The formats and disclosureFrame fields are optional API-level options that the Schemas screen does not collect.

{
  "name": "EmployeeBadge",
  "version": "1",
  "description": "Employee access badge credential.",
  "formats": ["sd-jwt", "jwt-vc-json"],
  "schema": {
    "type": "object",
    "properties": {
      "employee_id": { "type": "string" },
      "full_name":   { "type": "string" },
      "department":  { "type": "string" }
    },
    "required": ["employee_id", "full_name", "department"]
  },
  "vct": "EmployeeBadgeCredential",
  "disclosureFrame": ["employee_id", "full_name", "department"]
}

---

Versioning a Schema

Schemas are versioned by name. Each name@version pair is unique, so you cannot overwrite an existing version, but you can publish new ones alongside it.

1. Open an existing schema and click Add New Version to start a new version from its definition.

2. Adjust the claims in the attribute builder (or the synced JSON view). The panel assigns the next version number automatically (for example 1 → 2); the version is not editable in the builder. To publish an arbitrary version string such as 1.1, call POST /schemas directly.

3. Click Publish.

When you publish a new version, it becomes the active version for that name and the previous version is marked superseded. Superseded versions are retained and can still be viewed in the schema's version history; the schema list shows the active version by default.

The schema's version panel, with the published version and Add New Version

---

Credential Configuration IDs

A schema combined with a format produces a credential configuration id of the form Name@Version:format. For the example above this yields:

EmployeeBadge@1:sd-jwt
EmployeeBadge@1:jwt-vc-json

These identifiers are what credential offers reference when issuing credentials, so a single schema published in two formats exposes two configuration ids.

---

Assigning a Schema to an Issuer

Before an Issuer can offer a credential, the schema must be assigned to it.

1. Go to the Issuer's detail page and open the Schemas tab.

2. Select the schema to assign, identified by its Name@Version, for example EmployeeBadge@1.

3. Confirm the assignment.

The schema is added to the Issuer and its OpenID4VCI issuer metadata is refreshed so the credential configuration ids become available for offers. The Issuer can now issue credentials for any configuration id derived from that schema, such as EmployeeBadge@1:sd-jwt.

The Issuer's Schemas tab before anything is assigned — start from Assign schema

The Assign schema to issuer dialog

---

For any issues while defining, versioning, or assigning schemas, please contact our support team for assistance.