Home / Docs / Introduction to Open Document Spec (ODS)

Introduction to Open Document Spec (ODS)

stable profile: note

Principles, Level 0–3 adoption ladder, learning path, and core benefits of Open Document Spec.

Introduction to Open Document Spec (ODS)

Open Document Spec (ODS) is a Markdown-first documentation specification for repositories that need human-readable files and deterministic navigation for people and AI agents.

Documents stay plain .md files. Metadata is optional YAML frontmatter. Nothing requires a new file extension or proprietary store.

Core design principles

  1. Human first — Readable in any text editor, forever.
  2. Free at level zero — Plain Markdown is already conformant; adoption is enrichment, never migration.
  3. Token efficient — Every fact has exactly one canonical location.
  4. Graph native — Relationships are explicit frontmatter data, not inferred from prose.
  5. Trust from validation — Metadata is only as reliable as the checks that enforce it.

Adoption ladder (Level 0–3)

LevelWhat you haveDone when
0Any Markdown treeFiles open in any editor
1Optional profile + status frontmatterDocs are typed where it matters
2Path IDs, depends / related, index.md navigationGraph and maps exist
3CI lint: no dangling refs, indexes current, resources existTrust comes from validation

You never migrate Level 0 away. You only add structure when you need it.

Learning path

StepDocTimeYou will
1Introduction5 minUnderstand principles and Level 0–3
2Quickstart Guide10 minSkill-first setup, init, start/watch, lint, context
3Adopting ODS15 minEnrich an existing Markdown repo
4Tooling Reference15 minCLI, setup, service, CI, update
5Features20 minFull feature catalog
6Profiles & Catalogs15 minStandard and custom profiles
7Advanced Workspaces20 minAgents, context, large workspaces
8FAQas neededTroubleshooting

Normative rules live in specs/SPEC.md. This guide is operational.

Automation default: child lists in index.md are generated by ods index / ods start / ods watch. Do not hand-edit those bullets—set document description instead.

What you get

  • Clear shapes — Standard profiles (guide, feature, decision, …) reduce format guesswork.
  • Navigable trees — Generated index.md files stay current under ods start / watch / index.
  • Explicit edges — depends and related feed agents and tools.
  • Bounded AI context — context.* plus ods context / optional ods export.
  • Share-aware publishing — ods share writes a real, filtered directory (public docs only by default) that you git init/push yourself.
  • Safer refactors — Rename while the service/watch runs, or use ods mv; refs and indexes update together.
  • CLI trust — ods lint is the Level-3 gate (green message or ods-error.md).