SD-JWT credential preset

This page walks through the shape of an SD-JWT credential preset field by field. For the mDoc shape, see mDoc credential preset.

SD-JWT in one minute: the VCT

The VCT (Verifiable Credential Type) is a URI, defined by the SD-JWT-VC specification, that names the kind of credential. It’s the credential’s type identifier: a verifier looking at a presented credential reads its vct value to know what kind of credential it is, what fields it carries, and how to interpret them. Two credentials with the same VCT are the same kind of credential. The URI itself doesn’t need to resolve to anything, but the convention is that it could, pointing to a published metadata document describing the credential type, schema, and display rules. For URL-shaped VCTs the document lives at the URL itself; for non-URL VCTs (such as a urn:) the owning ecosystem publishes it out of band. The VCT is the bridge between everyone who touches the credential:

The preset declares the VCT in its templateType.
The issued credential carries the VCT in its vct claim.
The presentation request uses the VCT in templateCredentials[].type to filter the holder’s wallet down to credentials of the right kind.

The platform keeps the first two aligned automatically: a credential issued from the preset carries the preset’s templateType verbatim as its vct. The presentation request is the one place alignment is on you — ask for a different type and the wallet won’t surface the right credentials, and verification won’t happen.

The shape, end to end

{
  "id": "didx:basic-identity",
  "author": "didx",
  "code": "basic-identity",
  "credentialFormat": "sd-jwt",
  "templateName": "Basic Identity Credential",
  "templateDescription": "Standard basic identity credential",
  "templateType": "https://didx.co.za/vct/didx/basic-identity",
  "templateAttributes": {
    "firstName": {
      "type": "string",
      "name": "First Name",
      "required": true,
      "alwaysDisclosed": false
    },
    "lastName": {
      "type": "string",
      "name": "Last Name",
      "required": true,
      "alwaysDisclosed": false
    }
  },
  "issuerConfig": { "signer": "did:web" },
  "validUntil": { "start": "validFrom", "future": { "years": 5 } }
}

Identifier and metadata

The shared metadata fields (id, author, code, templateName, templateDescription, credentialFormat) are documented on the credential presets intro. The fields specific to SD-JWT are below.

`templateType` (the VCT)

The VCT for this preset (see SD-JWT in one minute): either a platform VCT URL (https://didx.co.za/vct/<author>/<code>) or an external urn: URI. Other http(s) URLs are not supported.

`issuerConfig`

How the platform signs credentials issued from this preset:

{ "signer": "did:web" }
// or
{ "signer": "certificate", "keyType": "P-256" }

did:web (the default) — credentials are signed using the tenant’s did:web DID. Verifiers fetch the DID document to validate the signature.
certificate — credentials are signed using an x509 certificate from the tenant’s certificate pool. The optional keyType (P-256 or Ed25519) narrows the selection to a specific algorithm.

`validUntil`

How long the issued credentials remain valid. Optional; defaults to five years measured from validFrom.

{ "start": "validFrom", "future": { "years": 5 } }

Field	What it is
`start`	When the validity window starts counting. `"validFrom"` (the typical SD-JWT choice) or `"issuance"` (required when `signer` is `certificate`).
`future.days` / `future.months` / `future.years`	The duration of the window. Specify any combination; the total must not exceed the platform cap (5 years for DID-signed, 1 year for certificate-signed).

`templateAttributes`: the credential’s fields

A flat map from attribute name to its definition. Each entry expresses a field on the credential and how it should behave at presentation time.

"firstName": {
  "type": "string",
  "name": "First Name",
  "required": true,
  "alwaysDisclosed": false
}

Field	What it is
`type`	Data type. Primitives: `string`, `number`, `boolean`, `date`. Compound: `object` (with `properties`), `array` (with `items`).
`name`	Human-readable label the wallet shows the holder (e.g. `"First Name"`, not `"firstName"`).
`description`	Optional explanation of the attribute.
`required`	Whether the issuer must supply a value for this attribute when issuing.
`alwaysDisclosed`	Whether the attribute is always revealed when the credential is presented, regardless of selective disclosure.

The attribute keys you declare (e.g. firstName, lastName) are what issuers pass under attributes when calling the issuance endpoint, and what verifiers ask for in a presentation request. They become the JSON keys on the issued credential itself.

Nested objects and arrays

SD-JWT supports nested attribute structures. An object attribute carries its own properties map; an array attribute carries an items schema:

"address": {
  "type": "object",
  "name": "Address",
  "required": false,
  "alwaysDisclosed": false,
  "properties": {
    "country": {
      "type": "string",
      "name": "Country",
      "required": true,
      "alwaysDisclosed": true
    }
  }
},
"nationalities": {
  "type": "array",
  "name": "Nationalities",
  "required": false,
  "alwaysDisclosed": false,
  "items": { "type": "string" }
}

`alwaysDisclosed` and selective disclosure

For SD-JWT credentials, the holder controls what they share on a per-presentation basis. alwaysDisclosed: false (the default) means an attribute can be withheld when the credential is presented; alwaysDisclosed: true means it is always revealed. Set alwaysDisclosed: true only for fields whose presence is meaningful in itself, typically trust signals like a verified flag, where the credential carries no useful meaning without it. For ordinary personal data (name, date of birth, etc.), leave it false and let the holder decide. To issue against a preset, see Issue a credential.

Overview

User Onboarding

Issuance

Verification

Webhooks

Custom Templates (advanced)

Errors

SD-JWT in one minute: the VCT

The shape, end to end

Identifier and metadata

`templateType` (the VCT)

`issuerConfig`

`validUntil`

`templateAttributes`: the credential’s fields

Nested objects and arrays

`alwaysDisclosed` and selective disclosure

​SD-JWT in one minute: the VCT

​The shape, end to end

​Identifier and metadata

​templateType (the VCT)

​issuerConfig

​validUntil

​templateAttributes: the credential’s fields

​Nested objects and arrays

​alwaysDisclosed and selective disclosure

SD-JWT in one minute: the VCT

The shape, end to end

Identifier and metadata

`templateType` (the VCT)

`issuerConfig`

`validUntil`

`templateAttributes`: the credential’s fields

Nested objects and arrays

`alwaysDisclosed` and selective disclosure