Portable types, queries, and automation for Markdown collections.

mdbase is an open specification for tools that work with structured Markdown. It gives editors, command-line tools, plugins, and agents a shared way to discover records, validate YAML frontmatter, resolve links, run queries, and update files safely.

The durable data stays in ordinary Markdown files. Collections remain readable in a text editor, reviewable in Git, and usable across conforming tools.

The current specification is v0.3.0.

Read the overview · Visit mdbase.dev · Explore an example collection

What mdbase Provides

• JSON Schema types for YAML frontmatter
• path and frontmatter rules for matching records to types
• collection-aware defaults, uniqueness rules, and validation
• portable links between Markdown records
• CEL expressions for filtering, ordering, and projections
• ordinary Markdown view records for saved queries and advisory presentation
• consistent create, read, update, delete, rename, and batch operations
• lifecycle policies for IDs, timestamps, slugs, and managed values
• first-class record, event, and action contracts with one identity and digest model
• optional CloudEvents-based application interoperability
• optional durable runtime execution for workflows, timers, and recovery
• conformance profiles that show which features each tool supports

A Collection At A Glance

An mdbase collection starts with an mdbase.yaml file:

project/
├── mdbase.yaml
├── _types/
│   └── task.md
└── tasks/
    └── write-docs.md

The minimal configuration declares the specification version:

spec_version: "0.3.0"

A type file associates records with a JSON Schema:

---
kind: mdbase.type
name: task
match:
  path_glob: "tasks/**/*.md"
schema:
  dialect: json-schema-2020-12
  value:
    type: object
    required: [title]
    properties:
      title:
        type: string
        minLength: 1
      status:
        enum: [open, in_progress, done]
      priority:
        type: integer
        minimum: 1
        maximum: 5
---
# Task
Task records live under `tasks/`.

Records stay recognizable as ordinary Markdown:

---
title: Write the documentation
status: in_progress
priority: 2
---
Explain how to create a first collection.

A query can select matching records with a CEL expression:

types: [task]
where: 'status != "done" && priority <= 2'
order_by:
  - field: priority
    direction: asc

Where To Start

Implementations

Choose an implementation based on how you want to work with a collection:

Implementations declare conformance profiles independently, so their supported features may differ. Package versions and specification versions advance independently.

Specification Guide

The specification is organized by topic:

• Chapters 00–04 introduce the model, records, collection layout, and configuration.
• Chapters 05–09 and 05A define types, data contracts, schemas, collection semantics, links, and lifecycle policy.
• Chapters 10–12 define CEL expressions, queries, and record operations.
• Chapters 13–14 define the optional durable runtime companion built on core contracts and event/action interoperability.
• Chapters 15–16 cover migration, compatibility, and conformance.

The v0.2.1 archive preserves the earlier specification and implementer material. Legacy fixtures are documented in tests/README.md.

Repository Contents

• schemas/v0.3/ contains the canonical JSON Schemas.
• tests/v0.3/ contains shared conformance fixtures.
• examples/v0.3/ contains example and migration collections.
• packages/ contains CEL, runtime, interoperability, and black-box testbed support packages.
• standard-packs/ contains inspectable, transactional standard-library distributions such as the durable runtime pack.
• site/ builds the versioned specification reader imported by the independently deployed mdbase.dev website.

Repository Verification

Run the relevant checks after changing specification artifacts or support packages:

python3 scripts/check_v03_tests.py
python3 scripts/prototype_tasknotes_v03_migration.py --check-fixture
npm test --prefix packages/runtime-contracts
cargo test --manifest-path packages/runtime-contracts-rs/Cargo.toml
npm test --prefix packages/cel-host
npm test --prefix packages/runtime-executor
npm test --prefix packages/testbed
npm run build --prefix site

License

MIT