Validate It

Install the validator

The validator is a standalone CLI. Install it globally so you can use it from any project:

$ npm install -g @blacksmithers/openspec

Validate your spec

Point it at the file you created in Step 1:

$ openspec todo-api.oschema.json

✔ Schema valid (v1.1)
✔ 3 tickets, 0 errors
✔ Dependency graph: acyclic
✔ All ticket dependencies resolve

All three formats work

The validator auto-detects the format from the file extension. JSON, YAML, and TOON are all supported:

$ openspec todo-api.oschema.yaml$ openspec todo-api.oschema.toon$ openspec todo-api.oschema.json

What errors look like

The validator produces clear, actionable error messages. Here are three common mistakes and what the output looks like:

Missing required field

$ openspec bad-spec.oschema.json

✘ Validation failed

  error: epics[0].tickets[0] must have required property 'ticketType'

  at: /epics/0/tickets/0
  fix: Add a "ticketType" field with one of: implementation, verification

Circular dependency

$ openspec circular.oschema.json

✘ Validation failed

  error: Circular dependency detected
  cycle: ticket-a → ticket-b → ticket-c → ticket-a

  fix: Remove one dependency to break the cycle

Dangling dependency

$ openspec dangling.oschema.json

✘ Validation failed

  error: ticket "tkt-create-todo" depends on "tkt-missing" which does not exist

  at: /epics/0/tickets/0/dependencies
  fix: Point the dependency at an existing ticketId,
       or remove the dependency from the ticket

Validate in CI

Add validation to your CI pipeline so specs are always checked on push. Here is a GitHub Actions example:

name: Validate OpenSpec Spec
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm install -g @blacksmithers/openspec

      - run: openspec ./specs/*.oschema.json

Any validation error will fail the build and show up in the PR checks.

Beyond shape: validate readiness

The CLI above answers "is this a well-formed OpenSpec document?". To answer "is this spec actually ready to build?", use crucible — an open-source, deterministic readiness engine (Python). It scores a spec against a fixed rubric and reports a pass/fail gate, with no LLM calls, so the result is reproducible in CI.

$ pip install crucible-forge

from crucible import validate, load_defaults

result = validate(spec, {"phase": "planning_spec", "config": load_defaults()})
print(result.scoring.gate_result)   # 'pass' | 'fail'
print(result.scoring.local_score)   # e.g. 86.11

Use the schema validator to catch malformed specs and crucible to gate on readiness — they are complementary.