0838eae6e9
Add docs/spec.md as a landing page for the specification section with a section index, conformance summary, and implementer guidance. Link to it from the home page quick links and from core-concepts field mapping section. Update nav to include the landing page.
2.6 KiB
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.