mDoc credential preset

This page walks through the shape of an mDoc credential preset field by field. For the SD-JWT shape, see SD-JWT credential preset. mDoc presets describe credentials conforming to ISO 18013-5 (the standard behind mobile driving licences and other government-issued ID). The shape reflects that lineage: namespaced attributes, certificate-based signing, and a tighter validity window.

mDoc in one minute: the DocType

The DocType is a string, defined by ISO 18013-5, that names the kind of document the credential represents. It’s the credential’s type identifier: a verifier reading an mDoc looks at its docType field to know what kind of document it is, what namespaces and fields to expect, and how to interpret them. Two mDocs with the same DocType are the same kind of document. The convention is reverse-DNS (e.g. org.iso.18013.5.1.mDL): a bare string that never resolves to anything; it’s just an identifier. The DocType is the bridge between everyone who touches the credential:

The preset declares the DocType in its templateType.
The issued credential carries the DocType in its docType field.
The presentation request uses the DocType 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 docType. 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.

The shape, end to end

{
  "id": "didx:national-id",
  "author": "didx",
  "code": "national-id",
  "credentialFormat": "mdoc",
  "templateName": "National ID",
  "templateDescription": "South African national identity document",
  "templateType": "za.co.didx.national-id",
  "templateAttributes": {
    "za.co.didx": {
      "properties": {
        "firstName": {
          "type": "string",
          "name": "First Name",
          "required": true
        },
        "dateOfBirth": {
          "type": "date",
          "name": "Date of Birth",
          "required": true
        },
        "portrait": {
          "type": "binary",
          "name": "Portrait",
          "required": false
        }
      }
    }
  },
  "issuerConfig": { "signer": "certificate", "keyType": "P-256" },
  "validUntil": { "future": { "days": 365 } }
}

Identifier and metadata

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

`templateType` (the DocType)

The DocType for this preset (see mDoc in one minute): a dot-separated reverse-DNS-style string, e.g. org.iso.18013.5.1.mDL.

`issuerConfig`

Always certificate-based; mDoc has no DID option:

{ "signer": "certificate", "keyType": "P-256" }

The optional keyType (P-256 or Ed25519) narrows the selection to a specific algorithm. ISO 18013-5 mDLs in practice require P-256; verifier compatibility for other key types depends on the verifier. The platform picks an active certificate from the tenant’s certificate pool that matches keyType. Manage the pool through the Certificates API.

`validUntil`

How long the issued credentials remain valid. Required (not optional, unlike SD-JWT) and capped at 365 days:

{ "future": { "days": 365 } }

Field	What it is
`future.days` / `future.months` / `future.years`	The duration of the validity window. The total must not exceed 365 days.

There’s no start field — mDoc validity is always counted from issuance.

`templateAttributes`: the namespaced fields

mDoc credentials carry their attributes inside namespaces. The outer key of templateAttributes is a namespace; each namespace has a properties map of attribute name → definition.

{
  "za.co.didx": {
    "properties": {
      "firstName": {
        "type": "string",
        "name": "First Name",
        "required": true
      },
      "dateOfBirth": {
        "type": "date",
        "name": "Date of Birth",
        "required": true
      }
    }
  }
}

A single preset can carry multiple namespaces:

{
  "org.iso.18013.5.1": {
    "properties": {
      "given_name": {
        "type": "string",
        "name": "Given Name",
        "required": true
      },
      "family_name": {
        "type": "string",
        "name": "Family Name",
        "required": true
      }
    }
  },
  "za.gov.home-affairs": {
    "properties": {
      "id_number": {
        "type": "string",
        "name": "ID Number",
        "required": true
      }
    }
  }
}

Field	What it is
`type`	Data type. Primitives: `string`, `number`, `boolean`, `date`, `binary` (mDoc-only, e.g. portraits). Arrays are also supported via `{ type: "array", items: ... }`.
`name`	Human-readable label the wallet shows the holder.
`description`	Optional explanation of the attribute.
`required`	Whether the issuer must supply a value for this attribute when issuing.

Unlike SD-JWT, mDoc has no alwaysDisclosed field — its selective-disclosure mechanism works at presentation time via the verifier’s intentToRetain flag rather than per-attribute settings on the credential. mDoc also has no nested object types. The namespace is the grouping mechanism; if you need finer-grained grouping, declare a second namespace. To issue against a preset, see Issue a credential.

Overview

User Onboarding

Issuance

Verification

Webhooks

Custom Templates (advanced)

Errors

mDoc in one minute: the DocType

The shape, end to end

Identifier and metadata

`templateType` (the DocType)

`issuerConfig`

`validUntil`

`templateAttributes`: the namespaced fields

​mDoc in one minute: the DocType

​The shape, end to end

​Identifier and metadata

​templateType (the DocType)

​issuerConfig

​validUntil

​templateAttributes: the namespaced fields

mDoc in one minute: the DocType

The shape, end to end

Identifier and metadata

`templateType` (the DocType)

`issuerConfig`

`validUntil`

`templateAttributes`: the namespaced fields