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
- 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
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| Goal | Start here |
|---|---|
| Understand the model | Overview and Concepts |
| Create a collection | Collection Layout, Configuration, Type Files, and First-Class Contracts |
| Validate, query, or save views over records | JSON Schema Profile, CEL Profile, and Querying |
| Add links or managed fields | Links and Lifecycle |
| Connect applications | Event and Action Interoperability |
| Define durable automation | Durable Runtime Companion, Workflow Execution, and the standard runtime pack |
| Migrate a v0.2 collection | Migrations And Compatibility |
| Exchange typed events and actions | Event/action interoperability profile 0.1 and canonical interoperability schemas |
| Build a conforming tool | Conformance, the portable interoperability testbed, canonical schemas, and test fixtures |
Choose an implementation based on how you want to work with a collection:
| Project | Role |
|---|---|
| mdbase | TypeScript collection library and migration engine |
| mdbase-rs | Rust collection library |
| mdbase-cli | Command-line collection operations and migration |
| mdbase-lsp | Editor diagnostics and language-server support |
| mdbase-obsidian | Obsidian integration and runtime host adapter |
Implementations declare conformance profiles independently, so their supported features may differ. Package versions and specification versions advance independently.
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.
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.
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 siteMIT