VCTM Markdown Format

Basic Structure

A VCTM 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:

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]

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 VCTM Output

The above Markdown generates a VCTM 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 VCTM 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 VCTM generation in your CI/CD pipeline.

References

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