Uploading the Credential Schema

What We Are Doing:

• Defining a credential schema that describes the claims our credential will carry (e.g., age, first_name, last_name).

• Creating that schema on the platform, then assigning it to our Issuer so its credential configurations are advertised to wallets.

Why: A schema is the contract for a credential. It declares the claim names, their types, and which claims are mandatory, so credentials stay consistent and interoperable. Assigning a schema to an Issuer refreshes the Issuer's OpenID4VCI metadata so wallets can discover the schema's credential configurations.

This is a two-step workflow:

1. Create the schema with POST /schemas — this registers a reusable, versioned schema on the platform.

2. Assign the schema to your Issuer with POST /issuers/:issuerDid/schemas — this refreshes the Issuer's OpenID4VCI metadata so the schema's credential configurations are advertised to wallets.

Both endpoints require a valid OIDC Bearer token. Set up your environment first:

ISSUER_BASE_URL=https://your-issuer.evdi.app
ISSUER_DID=did:web:your-issuer.evdi.app:8f3c...   # your Issuer's DID
TOKEN=<your OIDC access token>                     # any valid OIDC access token (JWT); the tutorial reuses the admin token from the authentication step

Step 1 — Create the schema

Create a schema.json file with the schema definition:

{
  "name": "KYCCredential",
  "version": "1.0",
  "description": "Know-Your-Customer verification credential.",
  "formats": ["sd-jwt", "jwt-vc-json"],
  "schema": {
    "type": "object",
    "properties": {
      "age": { "type": "number" },
      "first_name": { "type": "string" },
      "last_name": { "type": "string" }
    },
    "required": ["age", "first_name", "last_name"]
  },
  "vct": "https://your-issuer.evdi.app/vct/kyc-credential",
  "disclosureFrame": ["age", "first_name", "last_name"]
}

A few notes on the fields:

• name and version are required and must be token-like (matching ^[A-Za-z0-9][A-Za-z0-9._-]*$) — no spaces. Together they form the schema identifier name@version (here, [email protected]).

• schema is a JSON Schema describing the claims. Every key listed in required must also appear in properties.

• formats is optional; each entry is one of sd-jwt or jwt-vc-json. If omitted, both formats are enabled by default.

• vct is the credential type identifier used for SD-JWT VC credentials.

• disclosureFrame lists the claims a holder can selectively disclose when presenting an SD-JWT VC — the holder can reveal, for example, only age without exposing first_name or last_name.

• For JWT-VC-JSON credentials you can additionally set jwtVcTypes (e.g., ["VerifiableCredential", "KYCCredential"]); if you leave it out, sensible defaults are derived from the schema name.

Upload it with curl:

curl -X POST "$ISSUER_BASE_URL/schemas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @schema.json

The response echoes back the stored schema, including its identifier and lifecycle status:

{
  "schemaId": "[email protected]",
  "name": "KYCCredential",
  "version": "1.0",
  "status": "active",
  "schema": { "...": "the definition you sent" },
  "createdAt": "2026-06-22T12:00:00.000Z",
  "updatedAt": "2026-06-22T12:00:00.000Z"
}

Schemas are versioned. Creating a new version of an existing name (e.g., [email protected]) automatically marks the previous active version as superseded, so the latest version becomes the default. Older versions remain retrievable with GET /schemas/:schemaId?includeInactive=true (or via GET /schemas/:schemaName/versions).

Step 2 — Assign the schema to the Issuer

Creating a schema makes it available on the platform. Assigning it refreshes the Issuer's OpenID4VCI metadata so the schema's credential configurations are advertised to wallets. Assign it by posting the schema identifier (name@version):

curl -X POST "$ISSUER_BASE_URL/issuers/$ISSUER_DID/schemas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "schemaId": "[email protected]" }'

The response confirms the assignment:

{ "status": "assigned" }

What you get: credential configuration IDs

Each schema combined with a format produces a credential configuration id of the form name@version:format. Our [email protected] schema with both formats enabled yields:

• [email protected]:sd-jwt

• [email protected]:jwt-vc-json

These configuration ids are what you reference when creating credential offers later in the tutorial. For example, an SD-JWT VC offer for this schema uses [email protected]:sd-jwt.

With the schema created and assigned, the Issuer now knows exactly what a "KYC Verifiable Credential" looks like. Next, we'll look at the two credential formats and how selective disclosure works before issuing against these configuration ids.