TaskNotes Specification
The TaskNotes specification defines how tools should read, write, and reason about task data stored as markdown files with YAML frontmatter.
It exists so that multiple implementations — the Obsidian plugin, the terminal UI, CLI tools, and anything else that touches the same vault — can agree on what a task looks like, how dates and recurrence work, and what happens when a task is completed, skipped, or archived.
The spec is maintained separately from any single implementation. The canonical source is callumalpass/tasknotes-spec.
Sections
| Section | Content |
|---|---|
| Overview | Motivation, scope, and design principles |
| Terminology | Normative definitions used throughout |
| Model & Mapping | Task data model, semantic roles, and field mapping |
| Temporal Semantics | Date, datetime, and timezone rules |
| Recurrence | RRULE semantics and per-instance state |
| Operations | Create, update, complete, skip, delete behaviors |
| Validation | Validation rules and the issue model |
| Conformance | Conformance profiles and how to claim them |
| Compatibility & Migrations | Migration and backwards-compatibility policy |
| Configuration | tasknotes.yaml schema and the provider model |
| Dependencies & Reminders | Dependency and reminder semantics |
| Links | Link syntax, parsing, and resolution |
Conformance
The spec includes an executable conformance suite — a set of JSON test fixtures that any implementation can run against via a simple adapter interface. The suite covers date handling, recurrence, field mapping, configuration, operations, validation, and more.
Implementations claim conformance to one or more profiles (core-lite, recurrence, extended, templating) and must declare their spec version and any known deviations.
See the Conformance section for details.
For implementers
If you're building a tool that reads or writes TaskNotes data, the spec is the contract. Start with Model & Mapping to understand the data model, then Operations for write behavior. The conformance suite can validate your implementation against the spec's expectations.