The open specification format for AI agent orchestration.
Documentation · Quickstart · Contributing · Governance · RFCs
OpenSpec Format is a versioned, tool-agnostic format for describing software projects as hierarchical specifications that AI agents can execute.
schemaVersion: "1.1"
One field. Any tool that reads it knows exactly what to expect.
Think OpenAPI for agent orchestration — instead of describing REST endpoints, you describe decomposed work: Specification → Epics → Tickets, with a dependency graph, acceptance criteria, implementation instructions, and quality patterns. Any compliant agent can consume it.
AI agents are good at small, bounded tasks. The hard part is decomposition: how do you describe a large project in a way that preserves context, enforces ordering, and survives the limits of a single context window?
OpenSpec Format encodes the full decomposition graph — with rich metadata per entity — in a portable, versionable file. The format is engine-agnostic: you can build tooling on top of it without depending on any specific platform.
npm install -g @blacksmithers/openspec
openspec ./my-project.oschema.json
# ✓ Valid OpenSpec spec (v1.1) — jsonWorks offline. No auth. No SaaS dependency. Supports .oschema.json, .oschema.yaml, and .oschema.toon.
In v1.1 the document is a single specification — schemaVersion plus a structured planning core (goals, requirements, scope, acceptance criteria, …):
{
"schemaVersion": "1.1",
"id": "spec-my-project",
"projectId": "proj-my-project",
"title": "My Project",
"status": "planning",
"goals": [ /* … */ ],
"requirements": [ /* … */ ],
"scope": { "inScope": [ /* … */ ], "outOfScope": [ /* … */ ] },
"epics": [],
"blueprints": []
}A complete, valid minimal document lives at versions/v1.1/examples/minimal.oschema.json.
import { validate, toJson } from '@blacksmithers/openspec';
const raw = fs.readFileSync('./spec.oschema.yaml', 'utf-8');
const data = toJson(raw); // auto-detects format
const result = validate(data); // { valid: boolean, errors: ValidationError[] }
if (result.valid) {
console.log('Ship it.');
}Schema validation answers "is this a well-formed OpenSpec document?". To answer "is this spec ready to build?", use crucible — an OSS, deterministic readiness engine (Python) that scores a spec against a fixed rubric and reports a pass/fail gate. No LLM, reproducible in CI.
pip install crucible-forgefrom crucible import validate, load_defaults
result = validate(spec, {"phase": "planning_spec", "config": load_defaults()})
print(result.scoring.gate_result) # 'pass' | 'fail'The two are complementary: @blacksmithers/openspec checks the shape, crucible checks the readiness.
Specification # the document root — one deliverable
├── goals / requirements # structured planning core (+ scope, NFRs, guardrails)
├── sharedPatterns # coding standards that inherit down
├── Blueprint[] # design artifacts (diagrams, ADRs, mockups)
└── Epic[] # work groups
└── Ticket[] # atomic units of work
├── implementationSteps # ordered steps
├── filesToBe* # created / modified / deleted / referenced
├── codeReferences # symbols the agent must follow
├── typeReferences # types to use
├── testSpecification # test types and quality gates
└── dependencies[] # { ticketId, type: requires | blocks }
Full schema reference: openspec.tech
| Format | Extension | Best for | Token efficiency |
|---|---|---|---|
| JSON | .oschema.json |
Programmatic generation, CI pipelines, storage | Baseline |
| YAML | .oschema.yaml |
Human authoring, version control, readable diffs | ~15% fewer |
| TOON | .oschema.toon |
LLM agent context injection | 39.9% fewer |
All three are lossless representations of the same schema. The validator accepts all three. Round-trip conversion is guaranteed: JSON → TOON → JSON produces identical output.
JSON Schema published at permanent versioned URLs:
https://openspec.tech/schema/v1.1/openspec-schema.json
Stability guarantee: old schema URLs never change. Every published version is permanent. See GOVERNANCE.md for the versioning policy.
The format follows MAJOR.MINOR.PATCH with an RFC-based change process:
| Tier | What changes | Process | Comment period |
|---|---|---|---|
| Patch (1.1.x) | Typos, clarifications, examples | PR directly | None |
| Minor (1.x.0) | New optional fields, new enum values | RFC required | 2 weeks |
| Major (x.0.0) | Breaking changes, removed/renamed fields | RFC + migration guide | 4 weeks |
v1.1 consolidates the format around a single-specification root and structured planning entities. It is published as a new versioned schema; v1.0 remains permanent at its existing URL, so nothing that already references v1.0 breaks.
openspec/
├── versions/
│ ├── v1.1/ # current
│ │ ├── openspec-schema.json # source of truth
│ │ ├── openspec-schema.yaml # generated mirror
│ │ └── examples/ # valid example specs
│ └── v1.0/ # retained, permanent (never changes)
├── packages/validator/ # @blacksmithers/openspec (npm)
├── site/ # openspec.tech
├── rfcs/ # accepted RFC documents
├── GOVERNANCE.md # change process
├── CONTRIBUTING.md # how to contribute
├── CHANGELOG.md # all schema changes
└── LICENSE # Apache 2.0
There are many ways to help, regardless of whether you use the OpenSpec engine:
| Contribution | Where | Process |
|---|---|---|
| Report a schema bug (wrong type, missing enum value) | GitHub Issues | Open an issue with the bug label |
| Propose a new field or entity | GitHub Issues | Open an RFC using the template |
| Add an example spec | versions/v1.1/examples/ |
PR directly |
| Improve documentation | site/src/ |
PR directly |
| Build tooling on the format | Your own repo | Let us know — we'll list it |
Read CONTRIBUTING.md for full guidelines.
The format is Apache 2.0-licensed and intentionally decoupled from any engine. You can build:
- Validators in any language (the JSON Schema is the source of truth)
- Converters between OpenSpec and your own task/ticket formats
- Generators that produce
.oschema.jsonfrom natural language, PRDs, or existing codebases - Visualizers that render the dependency graph
- Executors that consume specs and drive your own agents
If you build something, open an issue with the ecosystem label and we'll add it to the tooling list.
This section will grow as the community builds tooling. To add yours, open an issue with the
ecosystemlabel.
| Tool | Description | Author |
|---|---|---|
| @blacksmithers/openspec | Official offline schema validator (JSON, YAML, TOON) | Solutions Forge |
| crucible | Deterministic readiness validator — scores a spec against a rubric and reports a gate (pip install crucible-forge) |
Solutions Forge |
| SpecForge Engine | Spec-driven development platform with MCP tools | Solutions Forge |
These principles guide every RFC and schema change:
- Stability above features. Old schema URLs never break. Ever.
- Engine-agnostic. The format must not encode workflow concepts specific to any platform.
- LLM-first. Fields must be meaningful to an agent, not just a human reader.
- Minimal core. If in doubt, leave it out. The schema is strict (
additionalProperties: false); extensions go through an RFC. - Dependency-driven. Execution order comes from the graph, not from array position.
Is this just for the SpecForge engine? No. The format is Apache 2.0-licensed and designed to be consumed by any tool. The engine is one implementation — you can build your own.
Why not just use Jira exports or GitHub Issues? Those formats describe human workflows. OpenSpec Format describes agent-executable work with implementation instructions, code references, type definitions, and dependency graphs. Different problem.
Why three file formats? JSON for machines, YAML for humans, TOON for LLMs. Each optimizes for a different consumer. The schema is one — the encoding varies.
Can I extend the schema with custom fields?
v1.1 is strict (additionalProperties: false), so there are no free-form custom fields. Use apiContracts (on Epic) for interface contracts, and fieldDeclarations to explicitly mark a required field as N/A with a reason. For format-level changes, open an RFC.
Where is the TOON spec?
TOON (Token-Oriented Object Notation) is documented at openspec.tech/formats/toon. The reference implementation is @toon-format/toon.
Apache 2.0 — Solutions Forge LTDA.
The format is open. The engine is not.