Validate It

Install the CLI validator and check your spec against the v1.0 schema. Catch errors before they reach your engine.

Install the validator

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

$ npm install -g @specforge/validator

Validate your spec

Point it at the file you created in Step 1:

$ specforge-validate todo-api.sf.json

✔ Schema valid (v1.0)
✔ 3 tickets, 0 errors
✔ Dependency graph: acyclic
✔ All patternRefs resolve
✔ All blueprintRefs resolve

All three formats work

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

$ specforge-validate todo-api.sf.yaml$ specforge-validate todo-api.sf.toml$ specforge-validate todo-api.sf.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

$ specforge-validate bad-spec.sf.json

✘ Validation failed

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

  at: /specifications/0/epics/0/tickets/0
  fix: Add a "status" field with one of: open, in-progress, done, blocked

Circular dependency

$ specforge-validate circular.sf.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 reference

$ specforge-validate dangling.sf.json

✘ Validation failed

  error: Unresolved patternRef "pattern-auth" in ticket "ticket-create-todo"
  available patterns: pattern-rest-conventions, pattern-error-format

  fix: Add pattern "pattern-auth" to the specification's patterns array,
       or remove the reference from the ticket

Why this matters: A ticket with status "in-progress" whose dependency is still "open" is a contradiction. The validator catches these so your engine never starts work that shouldn't exist yet. See: Work That Shouldn't Exist Yet →

Validate in CI

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

name: Validate SpecForge 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 @specforge/validator

      - run: specforge-validate ./specs/*.sf.json

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