Validate your config

soxom validate runs the same diagnostics the Soxom build pipeline does, but locally. It’s fast, offline, and the right thing to wire into a pre-commit hook so spec-level mistakes never reach the server.

Usage

soxom validate

Run from the directory containing openapi.yaml and soxom.yaml. The CLI parses both files, resolves $ref chains, and reports every diagnostic it finds.

What it checks

Both files are valid YAML.
soxom.yaml matches the schema (required fields, enum values, target language support).
The OpenAPI spec is a valid 3.0 or 3.1 document, with all required keys present.
Every $ref resolves and points at the right kind of node.
Operations referenced from soxom.yaml exist in the spec.
Custom Soxom extensions (x-soxom-*) are well-formed.

No network calls are made and no files outside the working directory are read.

Output formats

soxom validate --format human   # default
soxom validate --format json    # machine-readable, schema'd

Human output groups diagnostics by file, prints a short summary at the end, and uses ANSI colors (suppressed if stdout isn’t a TTY, or if NO_COLOR is set).

JSON output emits a ValidationReport matching the diagnostics schema published in the soxom-cli repo. Use this in CI to feed diagnostics into other tools.

Exit codes

Code	Meaning
`0`	No errors (warnings may still be present).
`1`	At least one error diagnostic was emitted.
`2`	The CLI couldn’t run validation at all (missing files, invalid flags).

CI scripts can rely on these — soxom validate is safe to chain with &&.

Diagnostic codes

Each diagnostic carries a stable SOXOM<NNN> code, the same codes shown in the dashboard’s Builds view. The catalog (with explanations and remediation hints) is mirrored from crates/soxom-validate/diagnostics.rs in the CLI repo, and the Errors & Troubleshooting page covers the common cases.

Pre-commit hook

Wire soxom validate into pre-commit so it runs automatically on every commit that touches the spec or config:

repos:
  - repo: local
    hooks:
      - id: soxom-validate
        name: Soxom validate
        entry: soxom validate
        language: system
        pass_filenames: false
        files: ^(openapi\.yaml|soxom\.yaml)$

Timeout

Validation is bounded by SOXOM_VALIDATE_TIMEOUT_MS (default 30000). On very large specs you may need to raise this; see the reference for details.