Skip to main content

Credential Schemas (V2)

Preview

This page covers credential schemas using the /api/credential-schema/v2 endpoints. The v2 schema API is available now but support for using v2 schemas in issuance and verification flows is still in development.

V1 schemas remain the current standard until that work is complete, at which point v1 will be disabled. See Credential Schemas (V1) for the current implementation.

A credential schema defines the structure of a credential type: the claims it contains, the formats it can be issued in, and how it should appear in a wallet. You create a schema once and reuse it every time you issue a credential of that type. If you are issuing Driver Licenses, you create a Driver License schema; every Driver License you subsequently issue is an instance of that schema.

Annotated example​

example

{
  "name": "Driver License",
  "organisationId": "{{YOUR-ORG-UUID}}",
  "formats": [
    {
      // schemaId optional for JWT; auto-generated if omitted
      "format": "JWT"
    },
    {
      // schemaId sets the mdoc DocType
      "format": "MDOC",
      "schemaId": "org.iso.18013.5.1.mDL"
    }
  ],
  "claims": [
    {
      // mdoc requires all root-level claims to be OBJECT type
      "key": "Driving Privileges",
      "datatype": "OBJECT",
      "required": true,
      "mapping": [
        {
          // namespace must be explicit on the parent object and all nested claims
          "format": "MDOC",
          "technicalKey": "driving_privileges",
          "namespace": "org.iso.18013.5.1"
        }
      ],
      "claims": [
        {
          // No mapping: JWT uses auto-generated path "driving_privileges/name"
          "key": "name",
          "datatype": "STRING",
          "required": true
        },
        {
          // Mapping overrides the default technicalKey for mdoc
          "key": "birthdate",
          "datatype": "BIRTH_DATE",
          "required": true,
          "mapping": [
            {
              "format": "MDOC",
              "technicalKey": "birth_date",
              "namespace": "org.iso.18013.5.1"
            }
          ]
        },
        {
          "key": "license_number",
          "datatype": "STRING",
          "required": true
        },
        {
          "key": "expiry_date",
          "datatype": "DATE",
          "required": true
        }
      ]
    }
  ],
  "batchSize": 5,
  "layoutType": "CARD"
}

Key concepts​

Formats array​

A schema can be issued in one or more credential formats simultaneously. Declare each supported format in the formats array, providing a schemaId for each. The schemaId serves a format-specific purpose: for mdoc it sets the DocType, for SD-JWT VC it sets the vct identifier. If omitted where optional, the system auto-generates one.

Claim mapping​

Each claim has a key, the business-level name used across all formats. Optionally, add a mapping to override how a claim is represented in a specific format, providing a format-specific technicalKey and, for mdoc, a namespace. Without a mapping, the key is used as the technicalKey directly; for nested claims in JWT, the system auto-generates a path-style key (for example, employee/fullName).

Batch issuance​

The optional batchSize parameter sets the maximum number of credentials that can be issued from this schema in a single batch request.