Anatomy of an mDoc credential preset

This page walks through the shape of an mDoc credential preset field by field. For the SD-JWT shape, see Anatomy of an 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 — but unlike SD-JWT’s VCT, this is a bare string, not a URL: it 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.

preset.templateType  ─────►  credential.docType  ─────►  presentation request type matcher

If those three values don’t match exactly, nothing connects. Unlike SD-JWT’s VCT, the DocType is not derived from the preset’s <author> and <code> — you supply it explicitly at preset creation. The convention is reverse-DNS:

org.iso.18013.5.1.mDL          // ISO 18013-5 mobile driving licence — fixed by spec
za.gov.home-affairs.passport   // ecosystem-specific
za.co.didx.national-id         // organisation-specific

If your credential is intended to interoperate with verifiers expecting a spec or ecosystem DocType, you must use that exact DocType — pick it for verifier compatibility, not internal naming convenience.

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). Author-supplied; not derived.

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

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.

What happens at issuance time

When an issuer issues a credential against the preset, the platform uses its structure directly:

The issuer calls the issuance endpoint with presetId and an attributes map of namespace → values.
The platform validates the attributes against templateAttributes: required fields must be present, types must match, namespaces and keys must be declared.
It produces an mDoc credential with the preset’s templateType as the DocType, signed by the matching certificate from the tenant’s pool, with the validity window from validUntil.
The credential is offered to the holder’s wallet, where they can accept it.
Once accepted, the credential lives in the wallet, ready to be used in any presentation request that asks for credentials of this DocType from a trusted issuer.

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

What happens at issuance time

​mDoc in one minute: the DocType

​The shape, end to end

​Identifier and metadata

​templateType (the DocType)

​issuerConfig

​validUntil

​templateAttributes: the namespaced fields

​What happens at issuance time

mDoc in one minute: the DocType

The shape, end to end

Identifier and metadata

`templateType` (the DocType)

`issuerConfig`

`validUntil`

`templateAttributes`: the namespaced fields

What happens at issuance time