validate reads your OpenAPI spec and reports what will break or degrade generation. Missing operationId? You'll get a warning — and that endpoint won't appear in api.op. Broken $ref? Error. Run this before blaming the generator.

The Validation screen in the interactive dashboard, showing per-category results and the offending endpoints. Same checks on the dashboard Validation screen — see the dashboard guide.

Usage

chowbea-axios validate [flags]

What it checks

Seven categories. Each issue has severity (error, warning, info) and a JSON Pointer to the offender.

Category	What it covers
`structure`	Top-level required fields — `openapi`/`swagger` version, `info`, `paths`.
`operations`	Every operation has an `operationId` and at least one response.
`references`	Every `$ref` resolves; no circular chains beyond the configured depth.
`parameters`	Path parameters declared in URLs are also declared in the operation. Query/header params are well-formed.
`responses`	Response definitions are present and reference resolvable schemas.
`type-quality`	Heuristics that affect generation quality — missing types, untyped `any`, `additionalProperties: true` patterns.
`schemas`	Component schemas are well-formed and referenced.

Flags

Flag	Short	Description	Default
`--config`	`-c`	Path to api.config.toml	Auto-detected
`--spec`	`-s`	Path to OpenAPI spec file	From cache
`--strict`	-	Treat warnings as errors	`false`
`--quiet`	`-q`	Suppress non-error output	`false`
`--verbose`	`-v`	Show detailed output	`false`

Examples

Validate cached spec

chowbea-axios validate

Validate specific file

chowbea-axios validate --spec ./openapi.json

Strict mode

chowbea-axios validate --strict

CI-friendly. Warnings fail the build. As they should if you care about api.op coverage.

Output

No issues

╭────────────────────────────────────────
│ chowbea-axios validate
├────────────────────────────────────────
│
│ ✓ Validating OpenAPI spec... (specPath=app/services/api/_internal/openapi.json)
│
╰────────────────────────────────────────
│
│ ✓ Validation complete (errors=0, warnings=0)
│ ✓ OpenAPI spec is valid

With warnings

╭────────────────────────────────────────
│ chowbea-axios validate
├────────────────────────────────────────
│
│ ✓ Validating OpenAPI spec...
│
├────────────────────────────────────────
│ Warnings
├────────────────────────────────────────
│
│ ⚠ Missing operationId - operation will be skipped during generation (path=/paths/users/get)
│ ⚠ Missing operationId - operation will be skipped during generation (path=/paths/users/post)
│
╰────────────────────────────────────────
│
│ ✓ Validation complete (errors=0, warnings=2)
│ ✓ OpenAPI spec is valid

Those endpoints still work on the path client. They won't get api.op methods.

With errors

╭────────────────────────────────────────
│ Errors
├────────────────────────────────────────
│
│ ✗ Missing 'openapi' or 'swagger' version field (path=/)
│ ✗ Missing required 'info' object (path=/info)
│
╰────────────────────────────────────────
│
│ ✓ Validation complete (errors=2, warnings=0)

Severity levels

Severity	When	Behavior
`error`	Spec malformed enough that generation fails or silently drops endpoints	Non-zero exit; always reported.
`warning`	Generation succeeds but quality suffers (missing `operationId`, untyped responses)	Reported; exits non-zero only under `--strict`.
`info`	Stylistic or low-impact notes	Reported; never fails.

Each category shows passed / failed / total checks.

Why operationId matters

Without it:

No api.op method generated
Yes path-based call still works (api.get("/path"))

paths:
  /users:
    get:
      summary: List users
      # missing operationId — skipped from api.operations.ts

With it:

paths:
  /users:
    get:
      operationId: listUsers
      summary: List users

If you're building The Query Layer, treat missing operationId as a spec bug, not a frontend workaround.

Use cases

Before deployment

chowbea-axios validate --strict

Debugging missing operations

chowbea-axios validate

"Why isn't api.op.createUser there?" — this answers that.

Validating external specs

chowbea-axios validate --spec ./external-api.json

Before you commit to generating against someone else's YAML.

Exit codes

Code	Meaning
0	Valid (no errors, warnings allowed)
1	Errors found, or warnings found with `--strict`

validate