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",
            "ecosystemSchemaId": "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
}

Formats

The formats array declares which credential formats this schema can be issued in. You can later choose a subset of formats in which to issue any given credential when you create the credential.

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.

Referencing instances and not types

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": { ... }
    }
}
}

This separation of instance naming and type allows for having multiple configurations of the same type. The value you provide in formats therefore must reference (and match exactly) the name of one of your configured format instances.

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.

When you create a schema in multiple credential formats, consider whether you wish to map individual claims to a namespace (for mdoc) or to a technical key (any format), per credential format. See Claim mappings for more. For system behavior when issuing with multiple formats, see Multi-format issuance.

Schema ID

Optionally, provide an ecosystemSchemaId 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.
• For all other formats, you cannot pass an ecosystemSchemaId.

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.

Claim datatypes

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

If a claim's datatype is OBJECT, it nests other claims inside it via its own claims array.

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 credential 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.

See Suspending and Revoking for details.

note

For multi-format schemas, revocation and suspension logic may differ between credentials issued, according to the formats used. See Suspending and Revoking — Multi-format credentials.

Translations

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

Other schema options

Credential expiration

The expiration parameter sets the administrative lifetime of credentials issued using this schema. After a credential has expired, it is no longer valid and cannot be refreshed. For an explanation of expiration behavior, see Credential Expiration for Issuers.

Batch issuance

The optional batchSize parameter sets the maximum number of credentials that can be issued from this schema in a single batch request. See Single, Batch, and Multi-Format Issuance.

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.

Embedded disclosure policy

An embedded disclosure policy lets issuers specify which relying parties a holder is permitted to disclose a credential to. The policy is attached to a credential schema and transmitted to the wallet as part of credential metadata. The wallet reads it at presentation time and warns the user if an incoming verifier request falls outside the policy.

This feature is defined in ETSI TS 119 472-3. See Embedded Disclosure Policy.