validate: [tracking] hard-rules spec-compliance subcommand

What

A new subcommand, oasdiff validate, that flags OpenAPI / JSON Schema spec violations. Strictly limited to hard rules: things the spec itself declares invalid. No style preferences, no team conventions, no config file.

Why

There is a quiet gap between two existing layers in the OpenAPI tooling stack:

1. Parsing layer: the underlying parser catches structural / syntax errors at load time.
2. Style / conventions layer: linters like Spectral and Redocly catch team-specific rules.

Between them sits a third layer of issues that are formally invalid per the OpenAPI / JSON Schema specs but get silently skipped at parse time and are not covered by style linters either. oasdiff validate fills that gap. Examples:

• multipleOf > 0 (JSON Schema §6.2.1)
• minimum ≤ maximum
• pattern is a valid regex
• info.title / info.version non-empty
• paths keys start with /
• parameter.in is one of query/header/path/cookie

Scope discipline

A rule belongs in oasdiff validate only if it can cite a specific clause of the OpenAPI spec or referenced JSON Schema draft. If a reasonable reader could disagree with the rule, it does not belong here.

This keeps validate out of territory linters already cover well. Style conventions, naming rules, description requirements, and anything that needs a config file should go to your team's linter of choice.

Usage

$ oasdiff validate spec.yaml
spec.yaml:14:9 error  parameter-name-required  parameter name is required
spec.yaml:42:17 error  schema-items-required   type: array requires items in 3.0
2 changes: 2 error, 0 warning, 0 info

$ echo $?
1

Exit codes: 0 if no findings at error or warning severity, 1 otherwise.

Flags:

• --format <fmt>: output format (text, yaml, or json; default text).
• --color <mode>: color mode for text output (auto, always, never; default auto). Matches changelog / breaking.

Default text output uses color highlighting per severity: error in red, warning in purple, info in cyan; rule IDs in yellow; HTTP method and path in green.

JSON / YAML output

Same shape as oasdiff changelog --format json|yaml. Numeric level matches the existing changelog and breaking-change conventions (1=info, 2=warning, 3=error).

[
  {
    "id": "schema-items-required",
    "text": "type: array requires items in 3.0",
    "level": 3,
    "operation": "POST",
    "path": "/users",
    "section": "paths",
    "source": {"file": "spec.yaml", "line": 22, "column": 17},
    "fingerprint": "g7h8i9"
  }
]

Listing the rules

oasdiff checks validate lists every rule ID and its message, parallel to oasdiff checks changelog.

$ oasdiff checks validate

Phase 1 coverage

Phase 1 wraps every validation check the underlying parser produces, mapped to descriptive, stable rule IDs. Categories:

• Required-field violations: info.title, info.version, paths (3.0), jsonSchemaDialect URI, parameter.name, responses non-empty per operation, and others.
• Mutually exclusive fields: example.value + externalValue; license.url + identifier; schema.readOnly + writeOnly; and others.
• Forbidden fields: header.name, header.in, OAuth flow auth / token URLs at unexpected sites.
• Either-or required: example must have value or externalValue; link must have operationId or operationRef.
• Schema items required: type: array requires items (3.0).
• Schema both-forms exclusive: additionalProperties, unevaluatedItems, unevaluatedProperties cannot be both boolean and schema.
• Exactly-one in content + schema: parameter / header must use content or schema, not both.
• Server URL templates: balanced braces; every templated variable declared.
• Version mismatches: 3.1-only fields used in 3.0 specs.
• Webhook integrity: nil path items in webhooks map.
• Structural baseline: $ref resolution, operationId uniqueness, path keys start with /, in: path parameters required.

Phase 2 coverage (post-v1)

Native rules that the parser does not catch today. Starter set, each citing a specific spec clause:

Numeric range integrity

• multipleOf > 0 (JSON Schema §6.2.1)
• minimum ≤ maximum when both set
• exclusiveMinimum < exclusiveMaximum (3.1, both set)

String constraints

• minLength ≤ maxLength
• pattern is a valid Go (RE2) regex
• pattern does not use unsupported features (lookahead, backreferences)

Array constraints

• minItems ≤ maxItems
• minContains ≤ maxContains (3.1)
• contains / minContains / maxContains / prefixItems / unevaluatedItems only meaningful on arrays

Object constraints

• minProperties ≤ maxProperties
• required names not in properties (and not covered by patternProperties or additionalProperties: true)
• discriminator.propertyName in required of every oneOf / anyOf member
• discriminator.mapping values resolve to schemas in the oneOf / anyOf set

Composition

• allOf / oneOf / anyOf arrays non-empty
• enum non-empty
• If const and enum both set, const is in enum
• All enum values match the declared type

Companion GitHub Action

A new oasdiff/oasdiff-action/validate action variant is planned, mirroring the existing breaking and changelog variants. It runs the validator in CI and exits non-zero on errors. Tracked separately in oasdiff/oasdiff-action.

Rule-ID stability

Rule IDs are stable API from v1. New rules may be added in later releases; existing IDs are never renamed or repurposed. CI dashboards and external tooling can depend on them.

Status

Phase 1 implementation is gated on a new release of the underlying parser containing the typed validation errors (kin-openapi #1166 + #1180, both merged upstream 2026-05-09). Once a kin release tag is cut, Phase 1 ships immediately.

How to engage

• Comment with use cases or specific violations you'd like flagged that are missing from the Phase 1 / Phase 2 lists.
• File examples of real-world specs that trigger silent panics today (each one becomes a Phase 2 rule).
• Suggest rule IDs you'd want suppressed by default if they tend to over-fire.