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 origin: 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, for example org.iso.18013.5.1.mDL. It is a bare string that never resolves to anything, just an identifier. The DocType is what links 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 where alignment is on you. Ask for a different type and the wallet won’t surface the right credentials.

The shape, end to end

This is a create request. code, type, templateName, templateDescription, templateAttributes, and validUntil are required, because the /mdoc endpoint defaults credentialFormat for you. namespace, issuerConfig, and branding are optional:

{
  "credentialFormat": "mdoc",
  "code": "national-id",
  "type": "za.co.didx.national-id",
  "namespace": "public",
  "templateName": "National ID",
  "templateDescription": "South African national identity document",
  "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 } },
  "branding": { "backgroundColor": "#0066CC", "textColor": "#FFFFFF" }
}

namespace here is the preset’s namespace, either public or private, controlling catalogue visibility. It is unrelated to the mDoc attribute namespaces inside templateAttributes (za.co.didx above), which group claims within the credential. They are two different ideas sharing one word. See public and private presets and templateAttributes respectively.

The response adds the fields the platform owns: id, author, createdAt, updatedAt, and your type echoed back as templateType.

Identifier and metadata

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

`type` / `templateType` (the DocType)

The DocType for this preset (see mDoc in one minute). It is a dot-separated reverse-DNS-style string, for example org.iso.18013.5.1.mDL. Send it as type; it comes back as templateType. type is required on mDoc presets, unlike SD-JWT, where the platform can derive it from code. A DocType is a reverse-DNS identifier the platform cannot guess, so you always state it. Omitting it returns a 400 pointing at /type.

`branding`

Optional card styling: backgroundColor, textColor, and backgroundImageUrl. Colours must be 6-digit hex. The background image should be 16:9, PNG or JPEG, and under 1 MB. It is fixed at creation like everything else on a preset, so set it now. See Branding.

`issuerConfig`

Signing is always certificate-based, because 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, and support for other key types varies between verifiers. 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. This is required, 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 always counts from issuance.

`templateAttributes`: the namespaced fields

mDoc credentials carry their attributes inside namespaces. The outer key of templateAttributes is a namespace, and each namespace has a properties map from attribute name to 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, for portraits and the like). You can also declare arrays with `{ 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 through 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, so if you need finer-grained grouping, declare a second namespace. To issue against a preset, see Issue a credential.

Overview

User Onboarding

Issuance

Verification

Branding

Webhooks

Custom Templates (advanced)

Errors

mDoc in one minute: the DocType

The shape, end to end

Identifier and metadata

`type` / `templateType` (the DocType)

`branding`

`issuerConfig`

`validUntil`

`templateAttributes`: the namespaced fields

​mDoc in one minute: the DocType

​The shape, end to end

​Identifier and metadata

​type / templateType (the DocType)

​branding

​issuerConfig

​validUntil

​templateAttributes: the namespaced fields

mDoc in one minute: the DocType

The shape, end to end

Identifier and metadata

`type` / `templateType` (the DocType)

`branding`

`issuerConfig`

`validUntil`

`templateAttributes`: the namespaced fields