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 will 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 membership cards, you create a membership card schema; every membership card you subsequently issue is an instance of that schema.

Example

The following schema issues a credential in two formats simultaneously: SD-JWT VC and ISO mdoc. It contains three claims: a flat string claim with format-specific technical keys, a nested address object, and a flat boolean claim with no mapping.

{
    "name": "Membership Card",
    "organisationId": "{{YOUR-ORG-UUID}}",
    "formats": [
        {
            "format": "MDOC",
            "schemaId": "org.example.membership"
        },
        {
            "format": "SD_JWT_VC"
        }
    ],
    "claims": [
        {
            "key": "Last Name",
            "datatype": "STRING",
            "required": true,
            "mappings": [
                {
                    "format": "MDOC",
                    "namespace": "org.example.membership",
                    "technicalKey": "family_name"
                },
                {
                    "format": "SD_JWT_VC",
                    "technicalKey": "surname"
                }
            ]
        },
        {
            "key": "Address",
            "datatype": "OBJECT",
            "required": true,
            "mappings": [
                {
                    "format": "MDOC",
                    "namespace": "org.example.membership",
                    "technicalKey": "address"
                },
                {
                    "format": "SD_JWT_VC",
                    "technicalKey": "address"
                }
            ],
            "claims": [
                {
                    "key": "Street",
                    "datatype": "STRING",
                    "required": true,
                    "mappings": [
                        {
                            "format": "MDOC",
                            "technicalKey": "street_address"
                        },
                        {
                            "format": "SD_JWT_VC",
                            "technicalKey": "street_address"
                        }
                    ]
                },
                {
                    "key": "Postal code",
                    "datatype": "STRING",
                    "required": true,
                    "mappings": [
                        {
                            "format": "MDOC",
                            "technicalKey": "postal_code"
                        },
                        {
                            "format": "SD_JWT_VC",
                            "technicalKey": "post_code"
                        }
                    ]
                }
            ]
        },
        {
            "key": "member_status",
            "datatype": "BOOLEAN",
            "required": true
        }
    ],
    "allowRevocation": true,
    "allowSuspension": true,
    "batchSize": 10,
    "layoutType": "CARD"
}

Formats

The formats array declares which credential formats this schema will be issued in. Each entry references the name of a configured format instance — not a format type or media type identifier. In the example above, formats references two instances named MDOC and SD_JWT_VC; your deployment configuration defines what each of those names actually means.

The configuration for the example might define these two instances like this:

{
  "format": {
    // Reference this
    "SD_JWT_VC": {
      "type": "SD_JWT_VC",
      "params": { ... }
    },
    // Reference this
    "MDOC": {
      "type": "MDOC",
      "params": { ... }
    }
  }
}

The value provided in formats must match one of your configured instance names exactly. The system applies the corresponding configuration, including any format-specific identifiers like dc+sd-jwt, automatically. You do not set those values in the schema.

Schema ID

Optionally, provide a schemaId alongside the format name. Its effect depends on the format:

• For mdoc, it sets the DocType.
• For SD-JWT VC, it sets the vct claim.

If omitted, the system generates one. For guidance on reading your configuration and identifying available format instances and their capabilities, see Reading the Configuration.

Claims

Claims define the attributes a credential contains. Each claim needs a key, a datatype for validation, and a required flag. If required is false, the issuer can leave that claim empty at issuance time.

If a claim's datatype is OBJECT, it nests other claims inside it via its own claims array, as with the Address claim in the example above.

Claim mappings

By default, a claim's key is used directly as its technical representation in every format. Add a mappings array to a claim when you need one of the following:

• A separate technical key per format: the key serves as a single, user-friendly display value for the claim across all formats, while technicalKey is the value actually written into the credential. This lets one schema definition support different technical naming per format. For example, a claim with the key Surname might map to last_name in one format and surname in another.

• A namespace for mdoc root-level claims: the mdoc standard expects every root-level claim to belong to a namespace. If you don't provide a namespace in a claim's mdoc mapping, the system falls back to using the schema ID as the namespace. For nested claims inside an OBJECT, the namespace is inherited from the parent and doesn't need to be repeated.

A mappings entry is never required on its own — you can omit mappings from a claim entirely. If you do include one, format and technicalKey are both required within that entry.

Revocation and suspension

Set allowRevocation: true to enable credential revocation. Suspension requires revocation to be enabled; set both allowRevocation and allowSuspension to true to allow issued credentials to be suspended.

In a multi-format schema, revocation and suspension apply per format according to what each format supports. If a format in your schema does not support a revocation or suspension feature you have enabled, that feature does not apply to credentials issued in that format, while other formats in the same schema are unaffected.

MDOC

ISO mdoc supports suspension only, not revocation. Suspension of mdocs works by preventing the wallet from obtaining a new Mobile Security Object (MSO) when the current one expires. This means suspension of an mdoc credential takes effect at the next MSO refresh rather than immediately.

Translations

Schema names and individual claim names can be translated for display in wallets that support localization. See Translating Credential Schemas.

Other schema options

Batch issuance

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

Layout

layoutType controls how the credential is rendered in the wallet. CARD is currently the only supported value.

Transaction codes

transactionCode requires the holder to enter a code to accept the credential. See Transaction Codes for configuration options and use cases.

Wallet unit attestation

keyStorageSecurity and requiresWalletInstanceAttestation: these settings require the wallet to provide attestations related to app integrity and ability to generate certain types of keys. These settings restrict which devices can receive credentials issued under this schema. See Device Limitations for Wallet Unit Attestation.

Claim datatypes

For available claim datatypes, see the datatype object of your configuration. For configuration, see Datatypes.