Typed Markdown Collections
mdbase specifies how Markdown files with YAML frontmatter are discovered, typed, validated, queried, linked, and updated. The durable state remains ordinary files on disk.
- collection layout
- schema files
- validation
- queries
- conformance tests
A collection is a directory with mdbase.yaml
The spec defines collection boundaries, type definition files, record discovery, effective frontmatter, and operation behavior. Implementations can claim the conformance level they support.
_types/task.md
Type definitions
Fields, inheritance, generated values, matching rules, and strictness are specified in Markdown files.
tasks/fix-bug.md
Record validation
Records are ordinary Markdown files with effective frontmatter derived from matching types.
query.where
Queries and expressions
Filtering, ordering, body search, and link traversal are defined by the query and expression sections.
Files stay authoritative
Durable state is represented as Markdown and YAML. Derived indexes, caches, views, and watchers are implementation details, not replacement storage formats.
Files are the source of truth
Tools read from and write to the filesystem. Indexes and caches are derived and disposable.
Human-readable first
No proprietary formats. A user with a text editor can read and modify any persistent file.
Progressive strictness
Collections can start untyped, then opt into validation, matching, links, caching, and watch mode.
Portable by default
Collections work with any conforming tool. Templates, plugins, and agents rely on the same specified behavior.
Git-friendly
Every durable change is text, reviewable in a diff and versioned with the rest of the collection.
Schemas, queries, and expressions in plain text
The same primitives appear in the spec, the reference tests, and real implementations.
my-project/
|-- mdbase.yaml # marks this folder as a collection
|-- _types/ # type definitions (schemas)
| |-- task.md
| `-- person.md
|-- tasks/
| |-- fix-bug.md # a record of type "task"
| `-- write-docs.md
`-- people/
`-- alice.md # a record of type "person"---
name: task
fields:
title:
type: string
required: true
status:
type: enum
values: [open, in_progress, done]
default: open
priority:
type: integer
min: 1
max: 5
assignee:
type: link
target: person
---query:
types: [task]
where:
and:
- 'status != "done"'
- "priority >= 3"
order_by:
- field: due_date
direction: asc
limit: 20# Filter by status and tags
status == "open" && tags.contains("urgent")
# Date arithmetic
due_date < today() + "7d"
# Link traversal
assignee.asFile().team == "engineering"
# Null coalescing
priority ?? 3Conformance levels
Implementations claim conformance at the level they support. Each level includes every level before it.
Implementation resources
The repository includes adapter documentation, a reference runner, fixtures, and lookup material for implementors.
Implementing.md
Step-by-step Level 1 on-ramp: required operations, test YAML interpretation, and conformance workflow.
- Zero-to-Level-1 path
- Adapter contract summary
- Suggested build order
Reference Runner
Canonical adapter protocol and command usage for `scripts/mdbase-test.py`.
- stdin/stdout JSON interface
- Expectation model
- Fixture setup behavior
Adapter Template
Minimal adapter scaffold to connect your implementation to the conformance suite.
- Single-request process model
- Operation dispatch skeleton
- Error shape examples
Annotated Collection
Runnable sample collection with valid and invalid records for manual smoke testing.
- Complete folder fixture
- Type definitions and records
- Manual check script in README
Quick Reference
Compact reference for operations, field types, error codes, operators, and precedence.
- High-frequency lookups
- Error code index
- Operator precedence
Read the full spec
Jump into a section or open the full reader with the sidebar navigation.