Diagnostics

Diagnostics are findings about your API spec that can affect generated clients. Use them to find invalid schemas, unclear names, and missing behavior before generating or releasing a Target.

Typeship checks the complete Spec against a set of rules. Each finding includes a stable rule ID, severity, category, one message, affected surfaces, source locations, and an authoring brief for agents.

The Diagnostic rule reference lists every rule, why it matters, affected generated surfaces, and the safest general remediation. Use Errors and warnings instead when generation itself fails or prints a warning.

Findings are grouped by rule, so a repeated issue appears once with every location. OpenAPI and GraphQL use native source locations and source-edit guidance. In a multi-file Spec, every location names the source file path in addition to its resolved pointer.

Diagnostics belong to a Spec Revision. GET /spec-revisions/{spec_revision_id} returns a diagnostic_summary: passed or blocked under the Spec's Diagnostic policy, counts by severity, the number of blocking Diagnostics, and the baseline revision it compares with. Add include=diagnostics to receive each diagnostic object. Each one reports blocking, whether it fails the policy, and introduced, whether it is new since the baseline. One Diagnostic can mix locations, so each location also reports its own blocking, introduced, and suppressed (covered by a reviewed exception). Add filter=blocking to receive only the locations that fail the policy, or filter=introduced for only new locations. A filter omits Diagnostics with no matching location and never changes diagnostic_summary. The Spec's revision_latest_id names the current revision. Reading a revision never fetches the source. Call POST /specs/{spec_id}/refresh to fetch the configured source now and record a revision if its content changed. When automatic generation is enabled, refresh queues generation for active Targets even if the source is unchanged.

With include=diagnostics, patch_diagnostics contains warnings with a stable code and display message. The codes distinguish unsupported patch formats, invalid documents or patches, unmatched paths, incompatible append or rename targets, and rename conflicts.

Remediation

When an exact OpenAPI edit can be proved from the contract, Typeship shows a reviewable patch you can copy. Apply it to your source Spec, or add it as a Spec patch if you cannot edit the source. Typeship does not apply Diagnostic fixes. Changes that require product intent remain source-edit guidance and tell an agent when to ask the API owner.

For GraphQL, edit the SDL using the finding's source guidance. OpenAPI patches do not apply to GraphQL.

Developer workflow

1. Start with blocking or newly added findings.
2. Read the evidence and every affected source location. One card can group many occurrences of the same rule.
3. Review and apply the suggested patch yourself when Typeship provides one. If a finding says API-owner decision, decide the intended public behavior before editing.
4. Change the source Spec, not generated CLI, MCP, SDK, or documentation output.
5. Refresh the Spec and confirm the rule no longer reports those locations. If automatic generation is enabled, the refresh also queues generation for active Targets. Review compatibility and generated surface changes.

Each finding links to its rule guide. Use Copy fix prompt to give a coding agent the reported revision, affected source locations, evidence, correction instructions, and verification steps. The prompt identifies decisions that need your input rather than letting the agent guess your API’s intended behavior.

Policy and GitHub

The default policy blocks only new correctness errors. Teams can change the threshold, evaluate the complete current Spec instead of only new findings, or record reasoned rule/location exceptions.

Diagnostics are part of the Typeship API Review status on source pull requests. The comment separates compatibility from Diagnostics so reviewers can distinguish an intentional breaking change from an invalid or underspecified contract.

Free projects get Diagnostics across the complete Spec even though each generated Target contains only 25 operations.