ODS Specification

Open Document Spec - Working Draft 1

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

Design principles, in priority order:

1. Human first: readable in any text editor, forever.
2. Free at level zero: standard Markdown is already fully conformant; adopting ODS means enriching existing documents with metadata, never migrating or rewriting them.
3. Token efficient (DRY): every fact has exactly one canonical location to minimize redundancy and optimize AI context consumption.
4. Graph native: relationships between documents are declared explicitly as frontmatter metadata, rather than inferred from text links or prose.
5. Trust from validation: metadata is only as reliable as the checks that enforce it; the specification does not require any rules that cannot be automatically validated or linted.

Format model

An ODS Document is a Markdown file with optional YAML frontmatter.

The frontmatter is machine-readable metadata for tools. The Markdown body is human-readable content for people and AI agents. Frontmatter values are the normative source for identity, lifecycle, graph edges, resource links, code references, and context loading. Body prose explains purpose, rationale, decisions, and usage; it does not redefine metadata.

Plain Markdown without frontmatter remains a valid Level-0 Document.

1. Core model

ODS defines four core concepts:

There are no other core concepts. A workspace may contain any number of subdirectories and files. Concepts like bundles, shared folders, archives, and local groups are represented as ordinary directories—the filesystem tree naturally expresses these relationships. collection is not a core concept; if a workspace uses the term, it must define distinct, documented semantics outside of this specification.

2. Documents and conformance levels

Each conformance level described below is fully valid under ODS.

Level 0 - plain Markdown

Any .md file, with or without frontmatter, is a valid ODS document. Tools MUST accept frontmatter-less documents and MUST NOT require any fields upon document creation.

Level 1 - typed

A Level-1 document introduces identity frontmatter (such as profile and status):

---
profile: guide
status: draft
---

# Checkout Setup

Steps for configuring checkout in a local development environment.

Level 2 - linked

A Level-2 document establishes graph relationships (see Graph Specification) and resides within an indexed workspace (see Indexes Specification).

Level 3 - validated

A Level-3 workspace enforces structural integrity and lint rules both locally and in Continuous Integration (CI). These checks ensure there are no dangling references, no duplicate IDs, all profiles resolve correctly, and indexes remain up to date. Documents marked as status: stable or listed in an index SHOULD be held to Level-3 validation (“creation is free; promotion has rules”).

3. Frontmatter

Frontmatter is a single YAML block delimited by --- at the very beginning of the document. All fields are optional. To allow for custom extensions and static site generator (SSG) interoperability, tools MUST ignore unknown fields.

Frontmatter is segregated into Universal Top-Level Metadata (read by SSGs, Obsidian, OpenGraph, CMSs) and ODS Engine Metadata (nested under an ods: map):

Universal Top-Level Metadata Keys

ODS Engine Metadata Keys (Nested inside ods:)

When scaffolded (ods new), adopted (ods adopt), or formatted (ods fmt --write), keys inside the ods: map MUST be emitted in this exact Canonical Key Sequence:

Root index.md Workspace Configuration Keys

[!IMPORTANT] Frontmatter title Prohibition Rule: Frontmatter MUST NOT contain a title: key. The document title exists exclusively as the first # H1 heading in the Markdown body prose (Single Source of Truth / Token Efficiency).

Tooling Tolerance Contract: The ODS parser MUST NOT error if frontmatter keys inside ods: appear out of sequence. However, formatting and scaffolding commands (ods fmt --write, ods new, ods adopt) MUST enforce canonical key sequence (profile $\rightarrow$ status $\rightarrow$ id $\rightarrow$ share $\rightarrow$ depends, related, resources, code, context).

Minimal and Complete Examples

A minimal typed document specifies profile and status inside the ods: map:

---
ods:
  profile: guide
  status: draft
---

# Checkout Setup

Steps for configuring checkout in a local development environment.

Here is a complete document example illustrating Universal Top-Level metadata and ODS Engine metadata in canonical sequence:

---
# Universal Top-Level Metadata
description: How to process customer refunds in the dashboard.
tags:
  - customer-care
  - billing
owner:
  - support-team
  - billing-ops

# ODS Engine Metadata (Canonical Key Order: profile -> status -> id -> share -> depends, related, resources, code, context)
ods:
  profile: guide
  status: stable
  id: docs/guide/07-examples/ecommerce/support/refund-guide
  share: public

  depends:
    - ../website/cart-checkout.md
    - ../auth/sessions.md
  related:
    - ../products/glow-serum.md

  resources:
    - path: docs/refund-flow.pdf
    - path: docs/architecture-diagram.png

  code:
    - path: apps/web/src/routes/refund.tsx
      role: entrypoint
      symbol: RefundRoute
    - path: apps/web/src/features/refunds/process.ts
      role: implementation
      symbol:
        - processRefund
        - validateRefund
        - RefundSchema
    - path: apps/web/src/features/refunds/process.test.ts
      role: test
      symbol:
        - processRefundTest

  context:
    max-depth: 2
    load:
      - ../website/cart-checkout.md
      - ../resources/users-sample.csv
    ignore:
      - marketing/
      - legacy/
---

# Refund Processing

## Overview

Use this guide when processing customer refunds in the dashboard.

Specification Modules

The remaining parts of ODS are detailed in the following sub-specifications:

• Identity & Graph Relationships: ID resolution, single source of truth rules, and graph edge semantics.
• Indexes & Workspace Scanning: Folder index rules, root index requirements, and scanning ignores.
• Resources & Code References: Native asset mappings and standardized implementation roles.
• Deterministic AI Context: How agents load context blocks safely.
• Profiles & Catalogs: Document schemas, expected headings, and custom profile mapping.
• Validation & Compatibility: Lint rules matrix, unknown content handling, and tooling expectations.
• Non-Goals: Out-of-scope concepts and design boundaries.

4. Lifecycle Operations & Heading Inference

Atomic Document Lifecycle

Tools MUST support four core atomic lifecycle operations for workspace documents:

1. Scaffolding (ods new <path>): Instantly creates a document pre-populated with Level-1 frontmatter (profile, status: draft, description), path-derived ID, inferred H2/H3 section placeholders, and automatically updates the parent index.md child listing.
2. Relocation (ods mv <from> <to>): Renames or moves a document or folder while atomically updating path-derived IDs, relative prose links, depends:, related:, code[].path, and child index.md entries across the workspace graph.
3. Archival (ods archive <path-or-id>): Updates document metadata to status: archived, moves the file to an archive/ subfolder, updates index listings, and preserves graph edges.
4. Atomic Deletion (ods rm <path-or-id>): Removes the target document from disk, strips the file entry from parent index.md files, and scrubs the deleted document ID from all dependent documents’ depends: and related: frontmatter arrays workspace-wide.

Smart Profile Inference (H2 + H3 Heading Scanning)

When adopting or creating un-typed documents, tools SHOULD scan both Heading 2 (##) AND Heading 3 (###) section titles to infer the target profile:

• Goal, Objective, Scope, Requirements, Acceptance Criteria, Risks $\rightarrow$ profile: feature
• Overview, Prerequisites, Steps, Troubleshooting $\rightarrow$ profile: guide
• Context, Decision, Alternatives, Consequences $\rightarrow$ profile: decision
• Purpose, Rules, Exceptions, Validation, Rollback $\rightarrow$ profile: sop
• Request, Response, Errors, Examples, Endpoint $\rightarrow$ profile: api
• Attendees, Agenda, Decisions, Action Items $\rightarrow$ profile: meeting
• Q/A, Questions, Answers, FAQ $\rightarrow$ profile: faq