A specification for treating folders of markdown files as typed, queryable data collections. Define schemas as markdown. Query with expressions. No proprietary formats.
Tools read from and write to the filesystem. Indexes and caches are derived and disposable.
No proprietary formats. A user with a text editor can read and modify any file.
Works with no schema at all. Validation is opt-in and configurable.
Collections work with any conforming tool. No vendor lock-in.
All persistent state is text files suitable for version control.
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 ?? 3Implementations claim conformance at the level they support. Each level builds on the last.