Credential Type Metadata Markdown Format

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 at the top of your file configures credential-level properties:

Credential-Level Localization

Localize the credential name and description into multiple languages using the display block in front matter:

---
vct: https://example.com/credentials/student-id
display:
  de-DE:
    name: "Studentenausweis"
    description: "Ein digitaler Studentenausweis"
  fr-FR:
    name: "Carte étudiant"
    description: "Une carte étudiant numérique"
  sv-SE:
    name: "Studentlegitimation"
    description: "Ett digitalt studentkort"
---

# Student ID

A digital student identification credential.

Each locale key (e.g., de-DE, fr-FR) creates a separate display entry in the generated credential type metadata. The default locale is taken from the H1 title and first paragraph, using the language configured for the generation (default: en-US).

Title and Description

The first H1 heading becomes the credential name, and the first paragraph after it becomes the description:

# Student ID Credential

A digital student identification credential issued by educational institutions.

Claims

Claims are defined as list items under a ## Claims section using this format:

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

Claim Components

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]

# Claim with complex type
- `address` "Address" (object): Current residential address [sd=always]

# Combined flags in one bracket
- `birth_date` "Date of Birth" (date): Birth date [mandatory, sd=always, svg_id=dob]

# SVG template mapping
- `photo` "Photo" (image): Holder's photograph [mandatory, svg_id=photo_element]

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

Locale Format

- locale: "Label" - Description

The locale code follows BCP 47 format (e.g., en-US, de-DE, sv, fr-CA).

Full Localized Example

## Claims

- `given_name` "Given Name" (string): The given name of the holder [mandatory]
  - de-DE: "Vorname" - Der Vorname des Inhabers
  - sv: "Förnamn" - Innehavarens förnamn
- `family_name` "Family Name" (string): The family name of the holder [mandatory]
  - de-DE: "Familienname" - Der Familienname des Inhabers
  - sv: "Efternamn" - Innehavarens efternamn
- `birth_date` "Date of Birth" (date): Date of birth [sd=always]
  - de-DE: "Geburtsdatum" - Geburtsdatum des Inhabers

Images

Reference images using standard Markdown syntax. Images are processed specially:

• The first image becomes the credential logo
• SVG images become SVG templates for dynamic rendering
• When using --base-url, images get full URLs and SRI integrity hashes

## Images

![Credential Logo](images/logo.png)
![Card Template](images/card-template.svg)

SVG Templates

SVG files can include placeholders that wallets replace with actual claim values:

<text id="given_name"></text>
<text id="issue_date"></text>

Complete Example

Here's a complete example combining all features:

---
vct: https://university.edu/credentials/student-id
background_color: "#003366"
text_color: "#ffffff"
---

# Student ID Credential

A digital student identification credential issued by accredited educational institutions.

## Description

This credential verifies the holder's enrollment status and basic identity information 
at an educational institution. It supports selective disclosure to minimize data exposure.

## Claims

- `student_id` "Student ID" (string): Unique student identifier [mandatory]
  - de-DE: "Matrikelnummer" - Die eindeutige Studierendennummer
  - sv: "Studentnummer" - Unikt studentnummer
- `given_name` "Given Name" (string): Legal first name [mandatory]
  - de-DE: "Vorname" - Der Vorname
  - sv: "Förnamn" - Förnamn
- `family_name` "Family Name" (string): Legal family name [mandatory]
  - de-DE: "Familienname" - Der Familienname
  - sv: "Efternamn" - Efternamn
- `enrollment_date` "Enrollment Date" (date): Date of initial enrollment
- `expected_graduation` "Expected Graduation" (date): Expected graduation date [sd=always]
- `program` "Program" (string): Enrolled academic program
- `faculty` "Faculty" (string): Academic faculty or department
- `photo` "Photo" (image): Student photograph [sd=always]

## Images

![University Logo](images/university-logo.svg)
![Student Card](images/student-card-template.svg)

## Issuer Requirements

The issuer must be an accredited educational institution with a valid digital 
credential issuing capability.

Generated Credential Type Metadata Output

The above Markdown generates a credential metadata JSON document like this:

{
  "vct": "https://university.edu/credentials/student-id",
  "name": "Student ID Credential",
  "description": "A digital student identification credential...",
  "display": [{
    "locale": "en-US",
    "name": "Student ID Credential",
    "description": "...",
    "rendering": {
      "simple": {
        "logo": { "uri": "...", "uri#integrity": "sha256-..." },
        "background_color": "#003366",
        "text_color": "#ffffff"
      },
      "svg_templates": [...]
    }
  }],
  "claims": [{
    "path": ["student_id"],
    "mandatory": true,
    "display": [
      { "locale": "en-US", "label": "Student ID", "description": "..." },
      { "locale": "de-DE", "label": "Matrikelnummer", "description": "..." },
      { "locale": "sv", "label": "Studentnummer", "description": "..." }
    ]
  }, ...]
}

Using mtcvctm

Generate credential metadata files using the command line or GitHub Action:

Command Line

# Generate single file
mtcvctm generate credential.md -o credential.vctm --base-url https://example.com

# Batch process directory
mtcvctm batch --input ./credentials --output ./vctm --base-url https://example.com

GitHub Action

See the GitHub Action Setup guide for automated credential metadata generation in your CI/CD pipeline.

Multi-Format Output

mtcvctm generates three credential format specifications from each Markdown file:

• SD-JWT VC Type Metadata (.vctm.json) - IETF draft-ietf-oauth-sd-jwt-vc specification
• mso_mdoc Configuration (.mdoc.json) - ISO 18013-5 mobile document format for OpenID4VCI
• W3C VCDM 2.0 Schema (.vc.json) - W3C Verifiable Credentials Data Model 2.0

All formats are derived from the same Markdown source, ensuring consistency across different credential implementations. Use the doctype front matter property to specify the mso_mdoc document type identifier when needed.

Example with mso_mdoc DocType

---
vct: https://example.com/credentials/mdl
doctype: org.iso.18013.5.1.mDL
background_color: "#003366"
---

# Mobile Driver's License

A verifiable mobile driver's license credential.

## Claims

- `family_name` "Family Name" (string): Family name [mandatory]
- `given_name` "Given Name" (string): Given name [mandatory]
- `birth_date` "Date of Birth" (date): Date of birth [sd=always]

References

• mtcvctm on GitHub
• SD-JWT VC Specification
• GitHub Action Setup
• Register Your Credentials
• Support & Contributing