ODS · Scope & Architectural Non-Goals
What ODS intentionally excludes from core design: boundaries, architectural non-goals, and rationale by domain.
ODS · Scope & Architectural Non-Goals
This document defines the Architectural Boundaries of Open Document Spec (ODS)—explicitly documenting what ODS intentionally excludes and the rationale behind each design choice.
At a glance
- What this chapter defines: Features ODS will not add, and why.
- Why it exists: A spec that grows every requested key stops being learnable.
- When you need it: You are proposing a new key, edge type, or file extension.
- When you can skip it: You are adopting the current standard, not extending it.
- Learn this first: FAQ · Extend ODS
- Prerequisite chapters: README.md
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.
2. Keys & Identity Non-Goals
| Excluded Feature |
Architectural Rationale |
No New File Extension (.ods) |
Files MUST remain standard .md so they can be viewed, edited, and rendered natively across GitHub, GitLab, VS Code, Obsidian, and all web platforms without custom plugins. |
No Frontmatter title: |
The document title exists strictly as the first # H1 heading in the Markdown body. Supporting a title: frontmatter key violates the Single Source of Truth (SSOT) principle and causes title drift. |
No Parallel type: Taxonomy |
ODS avoids multiple classification taxonomies (e.g. type, kind, category). ods.profile is the single canonical structural classification. |
| No Per-Document Spec Versions |
Spec versions belong strictly on the repository root ods.toml. Per-file version tags cause upgrade fatigue and merge friction across large repositories. |
| No Mandatory Hand-Maintained Timestamps |
Git commit history is authoritative for document updates. Frontmatter updated timestamps are optional for non-git export environments. |
| No Closed Tag Registries |
Tags are free-form strings normalized to lowercase. Mandating closed tag registries restricts team flexibility. |
3. Workspace & Indexing Non-Goals
| Excluded Feature |
Architectural Rationale |
No Committed Folder Indexes (index.ods.md) |
Committed folder navigation files cause endless Git merge conflicts in collaborative teams, produce massive commit churn, and suffer from link rot. Discovery is dynamically computed by the CLI. |
| No Root Index as Workspace Marker |
Root index.md / index.ods.md and scalar ods: 0.1 frontmatter are not the workspace boundary. The marker is ods.toml with spec. Optional profile: index documents are navigation, not policy. |
| No Zero-Config-File Workspace |
ODS requires exactly one workspace config file (ods.toml). It does not use .odsconfig, workspace.toml, or .odsignore as the boundary. Ignore lists live in ods.toml ignore. |
No Required llms.txt in Core |
An llms.txt file can be generated by tooling on demand, but is not part of the core document contract. |
| No Enterprise Namespaces in Core |
ODS avoids bloating core schema with vendor-specific governance fields. Organizations can use top-level custom frontmatter keys, which ODS preserves non-destructively. |
4. Graph & Context Scoping Non-Goals
| Excluded Feature |
Architectural Rationale |
| No Complex Ontologies in Core |
High-order edge types (implements, extends, replaces, conflicts-with) introduce high cognitive overhead for authors without improving automated AI prompt assembly. Core standardizes only depends (hard prerequisite) and related (soft reference). |
| No Blurring of Graph Prerequisites vs Prompt Fixtures |
Non-document fixtures (JSON schemas, mock CSVs) MUST NOT be placed in depends. They do not participate in DAG topological sorting. Prompt fixtures belong strictly in context.load. |
| No Auto-Loading of Arbitrary Resources |
ods.resources contains 50MB PDFs and binary PNG diagrams. Automatically dumping all resources into the AI prompt window causes immediate token budget exhaustion. Authors surgically declare prompt payloads via context.load. |
No Universal Frontmatter url: |
External URLs belong in the Markdown body prose where context and anchor text explain their relevance. |
| No Hand-Written Backlinks |
Authors declare relationships only on the dependent document. Inbound backlinks MUST be computed dynamically by tooling to prevent synchronization bugs. |
5. Assets & Code Binding Non-Goals
| Excluded Feature |
Architectural Rationale |
| No Frontmatter Inside Source Code |
Source code belongs to compilers, interpreters, and linters. Annotating source files with ODS frontmatter pollutes codebase syntax. All bindings live in Markdown docs. |
| No Line Numbers as Code Identity |
Line numbers (e.g. :L45-L60) change on almost every commit, immediately breaking documentation. ODS mandates paths and language symbol references. |
| No Custom Code Roles |
The 8 standard code roles (entrypoint, implementation, test, schema, migration, config, infrastructure, pipeline) provide a universal taxonomy so external AI agents can navigate any repository without custom configuration. |
6. Profiles & Rendering Non-Goals
| Excluded Feature |
Architectural Rationale |
| No Profile Inheritance Trees |
ODS profiles are flat, additive structural contracts. Deep inheritance hierarchies (guide inherits technical-doc inherits base) make validation fragile and opaque. |
| No Built-in Rendering / Template Engine |
ODS is a metadata and structural specification, not a Static Site Generator (SSG). Rendering HTML or PDF is left to specialized tools (Hugo, Astro, Docusaurus, Next.js). |
No Dedicated specs Profile |
Specifications naturally express different intents and should use the appropriate profile (feature for PRDs, decision for ADRs, architecture for system designs, guide for specs with implementation steps). |
7. Transport Non-Goals
| Excluded Feature |
Architectural Rationale |
| No Proprietary Transport Protocol |
Git, filesystems, and standard tarballs serve as the transport layer. ODS does not require a custom HTTP protocol or database daemon for basic operations. |
Navigation & Reading Order