sourcey validate

Parses, dereferences, and normalizes an OpenAPI spec to check for errors. No output files are generated.

Usage

sourcey validate <spec>

The <spec> argument is required. It can be a local file path or a URL.

Success

sourcey validate ./openapi.yaml

  Valid: My API v1.0.0
  Operations: 24
  Schemas:    12

Exit code: 0

Failure

  Invalid: [error message describing the issue]

Exit code: 1

What it checks

Validation performs the same parsing pipeline as a full build:

Parse the spec file (YAML or JSON)
Dereference all $ref pointers
Normalize the spec to sourcey's internal format
Report the operation and schema count

If any step fails, the error message identifies the issue: missing references, invalid schema definitions, unsupported spec versions, or malformed YAML/JSON.

Tip

Run sourcey validate in CI to catch spec errors before they break your docs build. It's fast (no rendering) and exits non-zero on failure. See OpenAPI Integration for how specs are used in the full build.

MCP specs

sourcey validate is for OpenAPI specs. To validate an mcp.json file, use mcp-parser:

npx mcp-parser validate ./mcp.json