schemator

Schemator reviews a draft data model and pushes it toward a smaller, clearer schema.

It extracts fields from TypeScript, JSON Schema, YAML, JSON, or Markdown proposal snippets, asks independent reviewers to challenge each field, applies safe reductions, and repeats until the graph stabilizes.

Quick Start

Install the CLI:

npm install --global @dutifuldev/schemator

The npm package is scoped as @dutifuldev/schemator; it installs the schemator command.

Run a full review against a draft schema or proposal:

schemator run --source schema.md --context project-context.md --out .schemator

Schemator requires Node.js 22.13 or newer. The default review strategy runs the Codex CLI, so install and authenticate codex before semantic reviews.

If you are using a local checkout directly, run npm install once and prefix CLI commands with npm run dev --.

Then inspect the report and diff:

schemator report --run .schemator --out .schemator/final-report.md
schemator diff --run .schemator --out .schemator/graph-diff.md

Use --context for product and naming guidance. Good context explains what the schema is for, which fields are user-facing, which vocabulary is intentional, and what should stay stable.

Review Strategy

codex is the default strategy. It starts one independent codex exec reviewer per field, validates each JSON result, aggregates the decisions, and applies safe changes.

Use local mode only for smoke tests:

schemator run --strategy local --source schema.md --out .schemator-smoke

Local mode is conservative and does not make semantic field-specific rename or removal decisions.

Useful Commands

Generate the field graph:

schemator extract --source schema.ts --out .schemator/graph.iteration-1.json

Write review prompts without running reviewers:

schemator create-jobs --graph .schemator/graph.iteration-1.json --context project-context.md --out .schemator/jobs.iteration-1

Run review and aggregation manually:

schemator review --graph .schemator/graph.iteration-1.json --context project-context.md --out .schemator/reviews.iteration-1
schemator aggregate --graph .schemator/graph.iteration-1.json --reviews .schemator/reviews.iteration-1 --out .schemator/aggregate.iteration-1.json
schemator apply --graph .schemator/graph.iteration-1.json --aggregate .schemator/aggregate.iteration-1.json --out .schemator/patch.iteration-1.md

Reports

Run reports are based on reducer artifacts, not raw review totals. They separate applied changes, skipped proposals, manual structural proposals, consistency warnings, and the final graph.

Treat a converged result as a candidate schema, not automatic product truth. Do a manual naming and product-semantics pass before accepting the final model.

Bundled Agent Skills

Schemator exposes its agent skills through Skillflag:

schemator --skill list
schemator --skill show schemator
schemator --skill export schemator | npx skillflag install --agent codex

Bundled skills:

• schemator: how to run and interpret Schemator.
• final-report: how to publish a complete final run report.

More

• OpenClaw RFC review artifacts

License

MIT