mtcvctm

Markdown To Create Verifiable Credential Type Metadata

---

A tool to generate VCTM (Verifiable Credential Type Metadata) files from markdown, as specified in Section 6 of draft-ietf-oauth-sd-jwt-vc-11.

Overview

mtcvctm allows you to author Verifiable Credential Type definitions using familiar markdown syntax and automatically converts them to valid VCTM JSON files. The tool is designed to be used in CI/CD pipelines, particularly as a GitHub Action, to maintain a registry of credential type definitions.

Installation

From Source

go install github.com/sirosfoundation/mtcvctm/cmd/mtcvctm@latest

Using Docker

docker pull ghcr.io/sirosfoundation/mtcvctm:latest

Usage

Generate a Single File

mtcvctm generate credential.md
mtcvctm gen credential.md -o output.vctm
mtcvctm generate credential.md --base-url https://registry.example.com

Batch Processing

Process all markdown files in a directory:

mtcvctm batch --input ./credentials --output ./vctm --base-url https://registry.example.com

GitHub Action Mode

mtcvctm batch --github-action --vctm-branch vctm --commit-message "Update VCTM files"

Markdown Format

Basic Structure

---
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 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]
- `birth_date` (date): Date of birth [sd=always]
- `nationality` (string): Nationality of the holder

## Images

![Logo](images/logo.png)

Front Matter

The optional YAML front matter supports:

Key	Description
vct	Verifiable Credential Type identifier
background_color	Background color for credential display
text_color	Text color for credential display
extends	Comma-separated list of VCT identifiers this type extends

Claim Format

Claims are defined in list items with the following format:

- `claim_name` "Display Name" (type): Description [mandatory] [sd=always|never]
  - locale: "Localized Label" - Localized description

• claim_name: The claim identifier (required)
• "Display Name": Human-readable display label for the claim (optional)
• type: The value type - string, date, number, etc. (default: string)
• Description: Human-readable description
• [mandatory]: Mark the claim as mandatory
• [sd=always|never]: Selective disclosure setting

Localization

Add translations as nested list items under a claim:

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

The format for localization items is:

- locale: "Label" - Description

Where locale is a BCP 47 language tag (e.g., en-US, de-DE, sv).

Images

Images referenced in the markdown become:

• The first image becomes the credential logo
• SVG files become SVG templates for rendering

By default, images are embedded as base64 data URLs in the VCTM, making the output self-contained without external dependencies. Use --no-inline-images to generate URLs instead (requires --base-url).

Configuration

Configuration can be provided via:

1. YAML configuration file
2. Command line arguments (take priority)

Config File Example

input: credential.md
output: credential.vctm
base_url: https://registry.example.com
language: en-US
vctm_branch: vctm
inline_images: true  # Default: images embedded as data URLs

GitHub Action

Use mtcvctm as a GitHub Action to automatically generate VCTM files:

name: Update VCTM
on:
  push:
    branches: [main]
    paths:
      - 'credentials/**/*.md'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: sirosfoundation/mtcvctm@v1
        with:
          input-dir: ./credentials
          output-dir: ./vctm
          base-url: https://registry.example.com
          vctm-branch: vctm

Action Inputs

Input	Description	Default
input-dir	Directory containing markdown files	.
output-dir	Output directory for VCTM files	.
base-url	Base URL for generating image URLs	``
vctm-branch	Branch name for VCTM files	vctm
commit-message	Commit message for updates	Update VCTM files [skip ci]
no-inline-images	Use URLs instead of embedding images	false

Action Outputs

Output	Description
registry-path	Path to the generated registry file
credential-count	Number of credentials processed

Registry Format

The tool generates a .well-known/vctm-registry.json file:

{
  "version": "1.0",
  "generated": "2024-01-15T10:00:00Z",
  "repository": {
    "url": "https://github.com/org/repo",
    "owner": "org",
    "name": "repo",
    "branch": "main",
    "commit": "abc123"
  },
  "credentials": [
    {
      "vct": "https://example.com/credentials/identity",
      "name": "Identity Credential",
      "source_file": "identity.md",
      "vctm_file": "identity.vctm",
      "last_modified": "2024-01-15T10:00:00Z",
      "commit_history": [...]
    }
  ]
}

Development

Build

make build

Test

make test

Coverage

make coverage

Docker Build

make docker-build

License

BSD 2-Clause License - Copyright (c) 2026 Siros Foundation. See LICENSE for details.