Credential Type Metadata Markdown Format

Define Verifiable Credential Type Metadata using familiar Markdown syntax with support for display names, multiple languages, and rich rendering options.

Basic Structure

A credential metadata markdown file consists of YAML front matter followed by structured content sections: 

---
vct: https://example.com/credentials/identity
background_color: "#1a365d"
text_color: "#ffffff"
---

# Identity Credential

A verifiable credential for identity verification.

## Claims

- `given_name` "Given Name" (string): The given name [mandatory]
- `family_name` (string): The family name [mandatory]

## Images

![Logo](images/logo.png)

Front Matter

The optional YAML front matter configures credential-level properties:

PropertyDescription
vctThe Verifiable Credential Type identifier (URI)
background_colorBackground color for credential display (hex)
text_colorText color for credential display (hex)
extendsURI of another VCT that this type extends
doctypemso_mdoc document type identifier
formatsComma-separated list of output formats to generate (e.g. sd-jwt, w3c). When omitted, all formats are generated. Aliases: vctm/sd-jwt/sdjwt, mddl/mdoc/mso_mdoc, w3c/jwt_vc_json

Claims

Claims are defined as list items under a ## Claims section: 

- `claim_name` "Display Name" (type): Description [flags]

Claim Components

ComponentRequiredDescription
`claim_name`YesThe claim identifier in backticks
"Display Name"NoHuman-readable label
(type)NoValue type: string, date, number, object, image
[mandatory]NoMark the claim as required
[sd=always|never]NoSelective disclosure setting
[svg_id=id]NoSVG template element ID

Examples

# Simple claim with type
- `email` (string): The holder's email address

# Claim with display name
- `given_name` "Given Name" (string): The first name of the holder

# Mandatory claim with selective disclosure
- `personal_id` "Personal ID" (string): Unique identifier [mandatory] [sd=always]

Nested Claims

Claims that contain sub-fields (objects) or repeated items (arrays) are expressed using Markdown sub-lists. Use (object) for structured data and (array) for repeating items: 

- `address` (object): Postal address [mandatory]
    - `street` (string): Street address [mandatory]
    - `city` (string): City [mandatory]
    - `postal_code` (string): Postal code
    - `country` (string): Country code
- `previous_addresses` (array): Previous addresses
    - `street` (string): Street address
    - `city` (string): City

Each output format represents nested claims appropriately:

ContainerVCTM (SD-JWT)mDOC (MDDL)W3C (JSON Schema)
object Nested paths, e.g. ["address", "street"] Dot-notation, e.g. address.street Nested properties
array Paths with null index, e.g. ["previous_addresses", null, "city"] Dot-notation, e.g. previous_addresses.city items schema with properties

Localization

Add multi-language support by nesting locale-specific entries under claims:

- `given_name` "Given Name" (string): The given name [mandatory]
  - de-DE: "Vorname" - Der Vorname des Inhabers
  - sv: "Förnamn" - Innehavarens förnamn
  - fr: "Prénom" - Le prénom du titulaire

Multi-Format Output

registry-cli generates three credential format specifications from each Markdown file:

  • SD-JWT VC Type Metadata (.vctm.json)
  • mso_mdoc Configuration (.mdoc.json)
  • W3C VCDM 2.0 Schema (.vc.json)

To generate only specific formats for a credential, add formats to the front matter: 

---
vct: https://example.com/credentials/identity
formats: sd-jwt, w3c
---

When formats is omitted, all three formats are generated.

References