Reference

Diagnostic rule reference

Every deterministic Typeship Diagnostic, why it matters, and the safest way for a developer or agent to resolve it.

This catalog lists every Diagnostic Typeship can emit. Use rule IDs in automation; they do not change. Rule wording can change.

A catalog entry explains the general rule. A live project finding remains authoritative because it adds the exact Spec Revision, source file, coordinate, evidence, policy state, and authoring brief.

  1. Retrieve the Spec's latest revision with typeship spec-revisions get <spec_revision_id> --include diagnostics or open Console → Project → Diagnostics.
  2. Start with blocking or newly added findings. Read every affected location before editing.
  3. Apply an exact reviewed patch when Typeship provides one. When API-owner decision is yes, ask rather than inventing behavior.
  4. Change the source Spec, not generated output.
  5. Retrieve the Project's Spec ID, refresh the Spec, confirm the exact rule and locations resolved, then review generated surface and compatibility changes.
For AI agentsFor a live project, copy the finding's fix prompt in Console or use its authoring_brief. Those prompts are revision-bound and safer than the generic rule prompt below.

Diagnostics report contract quality before generation. If generation itself fails or prints a warning, use Errors and warnings.

OpenAPI rules (43)

The contract still uses Swagger 2.0

  • Rule ID: openapi.document.swagger2
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Typeship converts Swagger 2.0 before generation, but OpenAPI 3.1 expresses modern request bodies, nullability, webhooks, and JSON Schema more precisely. Conversion keeps generation working but cannot recover intent the older format cannot express.

How to fix: Upgrade the source contract to OpenAPI 3.1

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Examples contradict their declared schemas

  • Rule ID: openapi.example.schema_mismatch
  • Severity: error
  • Affected surfaces: API, CLI, MCP, SDK

Message: Update the example or schema so the documented payload is valid in its request, response, parameter, or property context. Humans, tests, and agents copy an example that generated validation rejects.

How to fix: Make the example and schema agree

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Generated public names need collision resolution

  • Rule ID: openapi.generated_surface.name_collision
  • Severity: warning
  • Affected surfaces: CLI, MCP, SDK

Message: An authored name collides with another authored name or a reserved generated resource, method, command, or tool name. Review the exact resolved names before publishing. Typeship keeps the package compilable by qualifying or suffixing names, but the resulting CLI, MCP, or SDK surface may be surprising and can change when neighboring operations move.

How to fix: Choose distinct stable operation and resource names

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

The API has no top-level description

  • Rule ID: openapi.info.description.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Add a short statement of purpose, audience, and important behavioral constraints to info.description. Humans and agents otherwise begin with operation names but no model of what the API is for.

How to fix: Author the API overview

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Agent safety hints contradict each other

  • Rule ID: openapi.operation.agent_hints.contradictory
  • Severity: warning
  • Affected surfaces: API, MCP

Message: An operation cannot be both read-only and destructive. Correct the advisory metadata to describe the operation's intended effect. Clients may show the wrong approval affordance. These hints remain advisory and are not proof that the API enforces the claimed behavior.

How to fix: Correct the contradictory safety hints

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Deprecated operations do not identify a replacement

  • Rule ID: openapi.operation.deprecation.replacement_missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Point callers to the supported operation or migration path in the description, external documentation, or an explicit replacement extension. Generated clients can mark the method deprecated, but users and agents cannot migrate safely without a named alternative.

How to fix: Document the supported replacement

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Operations are missing behavioral descriptions

  • Rule ID: openapi.operation.description.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Describe preconditions, side effects, important defaults, and when a caller should use the operation. A signature alone cannot tell a human or agent how to use an operation safely.

How to fix: Document operation behavior

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Destructive operations appear to be public

  • Rule ID: openapi.operation.destructive.security_missing
  • Severity: warning
  • Affected surfaces: API, CLI, MCP, SDK

Message: Confirm that each DELETE operation intentionally has no authentication requirement. An agent or client may expose a destructive action without any credential boundary.

How to fix: Declare the operation's authentication requirement

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Operation identifiers are not unique

  • Rule ID: openapi.operation.operation_id.duplicate
  • Severity: error
  • Affected surfaces: CLI, MCP, SDK

Message: Every operationId must identify exactly one operation. Generators must rename or overwrite methods, making the published API ambiguous.

How to fix: Choose one unique identifier per operation

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Operations are missing stable identifiers

  • Rule ID: openapi.operation.operation_id.missing
  • Severity: warning
  • Affected surfaces: CLI, MCP, SDK

Message: Give every operation a unique operationId. Typeship can derive names, but an authored identifier is the durable public method name. Derived CLI commands, MCP tools, SDK methods, and future diffs can change when paths are reorganized.

How to fix: Add deterministic operation identifiers

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Pagination signals are incomplete

  • Rule ID: openapi.operation.pagination.incomplete
  • Severity: warning
  • Affected surfaces: CLI, MCP, SDK

Message: Make the detected cursor, page, or offset shape unambiguous, or configure this operation's pagination interpretation explicitly. Generated pagination helpers may select the wrong style or be unable to continue a collection safely.

How to fix: Clarify the pagination contract

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Pagination appears present but Typeship cannot interpret it

  • Rule ID: openapi.operation.pagination.unsupported
  • Severity: suggestion
  • Affected surfaces: CLI, MCP, SDK

Message: Use a supported cursor, page, or offset shape, or configure this operation's pagination fields explicitly. This is a generation limitation, not proof that the API lacks pagination. Generated helpers expose a single call even though callers may need to continue the collection manually.

How to fix: Configure or document the pagination shape

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Path parameters do not match the URL template

  • Rule ID: openapi.operation.path_parameter.invalid
  • Severity: error
  • Affected surfaces: API, CLI, MCP, SDK

Message: Every {parameter} in a path must have a required path parameter with the same name. Generated methods cannot construct the request URL reliably.

How to fix: Align path templates and parameter declarations

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Request bodies have no schema

  • Rule ID: openapi.operation.request_body.schema_missing
  • Severity: error
  • Affected surfaces: CLI, MCP, SDK

Message: Every declared request-body media type needs a schema. Generated callers cannot validate or type the request payload.

How to fix: Model request bodies

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Error correlation is inconsistent within an operation

  • Rule ID: openapi.operation.response.error_correlation.inconsistent
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Use one request, trace, or correlation identifier convention across the operation's structured failures, or document why some failures cannot carry it. Operators and callers may be able to investigate one failure status but not another from the same generated method.

How to fix: Review error correlation coverage

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

One operation uses multiple error identity conventions

  • Rule ID: openapi.operation.response.error_identity.inconsistent
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Use one stable error discriminator convention across this operation's structured failures, or document why distinct error families are intentional. Callers otherwise need status-specific branching merely to discover the domain error identity.

How to fix: Review the operation's error family

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Error bodies have no stable machine-readable identity

  • Rule ID: openapi.operation.response.error_identity.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Expose a stable code, type, or equivalent domain error discriminator. RFC 9457 problem types are supported, but an existing sound domain format is equally valid. Callers must branch on status codes or human prose instead of a stable domain failure identity.

How to fix: Choose a stable error identity

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Failure responses have no machine-readable schema

  • Rule ID: openapi.operation.response.error_schema.missing
  • Severity: suggestion
  • Affected surfaces: CLI, MCP, SDK

Message: Give each declared error-body media type a schema with a stable code and recovery detail. Omit content for intentionally bodyless errors. Humans see prose while agents and SDKs receive an untyped failure body they cannot branch on.

How to fix: Model structured error bodies

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Operations declare no failure responses

  • Rule ID: openapi.operation.response.errors.missing
  • Severity: warning
  • Affected surfaces: API, CLI, MCP, SDK

Message: Review the authentication, authorization, validation, conflict, not-found, throttling, and transient failures this operation can actually return, and document the applicable ones. Generated software cannot distinguish expected recovery paths from unexpected transport failures.

How to fix: Define the operation's error contract

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Non-2xx outcomes are not generated as success

  • Rule ID: openapi.operation.response.non_2xx_success.unsupported
  • Severity: warning
  • Affected surfaces: CLI, MCP, SDK

Message: The informational or redirect response is valid HTTP/OpenAPI behavior. Typeship currently models generated success results from 2xx or a default-only response, so it cannot expose this contract as a typed success. Generated CLI, MCP, and SDK surfaces may treat the expected non-2xx outcome as an API error.

How to fix: Review the generator limitation without changing status codes

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Rate-limit responses do not declare Retry-After

  • Rule ID: openapi.operation.response.retry_after.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: If the server supplies retry timing, declare the Retry-After response header. If it intentionally does not, document the caller's recovery rule instead. Generated callers can retry with backoff, but cannot honor server-provided timing that the contract does not expose.

How to fix: Document rate-limit recovery timing

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Successful response bodies have no schema

  • Rule ID: openapi.operation.response.success_schema.missing
  • Severity: warning
  • Affected surfaces: CLI, MCP, SDK

Message: Add a schema to each declared response media type that returns a body. Omit content when the response is intentionally bodyless. Generated clients return unknown data and MCP tools cannot publish a trustworthy output schema.

How to fix: Model successful response bodies

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Operations have no non-error response

  • Rule ID: openapi.operation.response.success.missing
  • Severity: error
  • Affected surfaces: API, CLI, MCP, SDK

Message: Declare a successful, redirect, or default response that describes a possible non-error outcome. Callers cannot know what a non-error outcome means or type its result.

How to fix: Describe the successful response

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Structured validation issues do not identify the invalid input

  • Rule ID: openapi.operation.response.validation_location.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: When a validation response exposes an issue array, give each issue a field, path, pointer, parameter, or location when the server can identify it. Callers can learn that validation failed but cannot reliably map the failure back to the request value that needs correction.

How to fix: Expose validation issue locations

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Configured retries rely on unverified write safety

  • Rule ID: openapi.operation.retry.non_idempotent_unverified
  • Severity: warning
  • Affected surfaces: CLI, MCP, SDK

Message: Project configuration retries this POST or PATCH operation, but the contract exposes no idempotency-key input. Confirm server deduplication or narrow the retry policy. A retry after an ambiguous transport failure could repeat a side effect.

How to fix: Verify or constrain non-idempotent retries

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Security requirements reference missing schemes

  • Rule ID: openapi.operation.security.reference_invalid
  • Severity: error
  • Affected surfaces: API, CLI, MCP, SDK

Message: Every name in a security requirement must exist in components.securitySchemes. Generated authentication configuration cannot satisfy the declared operation contract.

How to fix: Define or correct the referenced security scheme

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Operations require authentication generated clients cannot send

  • Rule ID: openapi.operation.security.scheme_unsupported
  • Severity: warning
  • Affected surfaces: CLI, MCP, SDK

Message: At least one security alternative must use a scheme generated clients support: bearer, Basic, a custom HTTP scheme, an API key in a header, query, or cookie, OAuth2, or OpenID Connect. HTTP Digest, mutual TLS, and other challenge-response schemes cannot be sent. Generated CLIs and MCP servers refuse the operation, and SDK callers must add the credential through a custom HTTP client.

How to fix: Add a supported security alternative

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

OAuth requirements reference undefined scopes

  • Rule ID: openapi.operation.security.scope_invalid
  • Severity: error
  • Affected surfaces: API, CLI, MCP, SDK

Message: Every OAuth scope named by a security requirement must be defined by that security scheme. A caller cannot request a scope the contract's authorization definition does not offer.

How to fix: Define or correct the OAuth scope

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Stream events have no declared event identity

  • Rule ID: openapi.operation.stream.event_identity.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, SDK

Message: If a stream carries multiple event kinds, expose a stable type, event, kind, name, or id discriminator. A single-kind raw stream may document that fact instead. Generated streaming callers can deliver events but cannot help consumers distinguish or resume them from the declared payload shape.

How to fix: Document stream event identity and resume behavior

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Operations are missing summaries

  • Rule ID: openapi.operation.summary.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Add a short action-oriented summary to each operation. Help output and tool discovery fall back to mechanical names instead of telling a caller what the operation does.

How to fix: Write concise operation summaries

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Operations are not grouped into resources

  • Rule ID: openapi.operation.tags.missing
  • Severity: suggestion
  • Affected surfaces: CLI, MCP, SDK

Message: Assign at least one stable resource tag to each operation. SDKs and command surfaces become a flat or mechanically grouped catalogue.

How to fix: Group operations by their first path resource

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Accepted work has no declared follow-up handle

  • Rule ID: openapi.operation.workflow.async_handoff.incomplete
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: A 202 response should tell callers how to observe accepted work when the operation is asynchronous, such as a Location header, status URL, or job identifier. Humans and agents may start work successfully but have no contract-declared way to learn its outcome.

How to fix: Document the asynchronous follow-up workflow

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Batch operations do not expose per-item outcomes

  • Rule ID: openapi.operation.workflow.batch_outcome.incomplete
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: For bulk or batch work, describe per-item success and failure results, or state that the operation is atomic. A caller cannot safely recover from partial success using only an aggregate response.

How to fix: Define batch completion and partial-failure semantics

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

List workflows have no discoverable retrieve operation

  • Rule ID: openapi.operation.workflow.collection_retrieve.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Review whether callers need a stable single-resource lookup after listing a collection. A list-only feed, report, or aggregate may be intentional. Humans and agents can discover identifiers in a collection but may have no typed path to fetch current details for one item.

How to fix: Review the collection-to-resource workflow

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Ambiguous operation inputs are missing descriptions

  • Rule ID: openapi.parameter.description.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Describe identifier meaning, units, time-zone expectations, money representation, defaults, or constraints where the name and schema do not make them self-evident. A syntactically valid generated call can still send the wrong identifier, unit, currency, or time interpretation.

How to fix: Document the input semantics

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Schema properties are both read-only and write-only

  • Rule ID: openapi.schema.access_mode.contradictory
  • Severity: error
  • Affected surfaces: API, CLI, MCP, SDK

Message: A property cannot be excluded from both request and response shapes. Choose the direction in which it is present. Generated request and response types cannot expose the property consistently.

How to fix: Correct the readOnly/writeOnly annotations

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Object schemas leave their dictionary shape implicit

  • Rule ID: openapi.schema.object.unconstrained
  • Severity: suggestion
  • Affected surfaces: CLI, MCP, SDK

Message: If this is an intentional open dictionary, declare additionalProperties explicitly. Otherwise define the known properties. Generated SDKs expose an untyped dictionary and callers cannot tell whether arbitrary keys are intentional.

How to fix: Describe the object's allowed fields

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Ambiguous schema properties are missing descriptions

  • Rule ID: openapi.schema.property.description.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Document properties whose identifier, unit, time-zone, money, nullability, or enum semantics are not clear from their name and schema. Generated types carry the wire shape but not enough meaning to construct or interpret values reliably.

How to fix: Document the property semantics

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Server variables are missing defaults

  • Rule ID: openapi.server.variable.default_missing
  • Severity: error
  • Affected surfaces: API, CLI, MCP, SDK

Message: Every variable used in an OpenAPI server URL must declare a default value. The effective server URL is invalid under OpenAPI and cannot be resolved deterministically.

How to fix: Declare each server variable default

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Server selection needs client configuration

  • Rule ID: openapi.servers.missing
  • Severity: suggestion
  • Affected surfaces: CLI, MCP, SDK

Message: The OpenAPI server configuration is valid, but Typeship cannot turn this effective relative or operation-specific server into its one client-wide default. Pass the intended base URL when constructing the client, or author a compatible root server if one default is appropriate. Generated clients require an explicit base URL and do not silently apply a path- or operation-level override.

How to fix: Review client base URL configuration

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Webhook payloads have no stable event identity

  • Rule ID: openapi.webhook.event_identity.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Expose a stable type, event, kind, name, or id field when one endpoint delivers multiple event shapes, or document the single event kind. Consumers may need endpoint-specific prose or payload guessing to route verified deliveries.

How to fix: Document webhook event identity

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Webhook payloads have no usable request schema

  • Rule ID: openapi.webhook.request_schema.missing
  • Severity: warning
  • Affected surfaces: API, CLI, MCP, SDK

Message: Declare a request-body schema for every webhook event Typeship should expose. Typeship skips webhook entries whose payload cannot be typed, so generated verification helpers cannot return a useful event union.

How to fix: Model the webhook payload

API-owner decision: No, unless the live evidence conflicts with the API's intended behavior.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Webhook verification inputs are not declared

  • Rule ID: openapi.webhook.verification.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Declare the signature, timestamp, delivery identifier, token, or security requirement consumers use to authenticate webhook deliveries. A generated payload type does not prove that a delivery is authentic or protected against replay.

How to fix: Document webhook verification and replay protection

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

GraphQL rules (11)

Unions or interfaces are missing descriptions

  • Rule ID: graphql.abstract_type.description.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Describe why the variants share one return type and how callers should distinguish them. Generated union types are mechanically correct but difficult to use without domain context.

How to fix: Document abstract result types

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Operation arguments are missing descriptions

  • Rule ID: graphql.argument.description.missing
  • Severity: suggestion
  • Affected surfaces: CLI, MCP, SDK

Message: Document identifiers, units, formats, defaults, and constraints on root-field arguments. A type alone is often insufficient for a human or agent to construct a correct call.

How to fix: Describe operation arguments

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Enum values are missing descriptions

  • Rule ID: graphql.enum_value.description.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Explain values whose meaning is not completely captured by their names. Callers can enumerate allowed values but cannot reliably choose among them.

How to fix: Document enum semantics

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Input fields are missing descriptions

  • Rule ID: graphql.input_field.description.missing
  • Severity: suggestion
  • Affected surfaces: CLI, MCP, SDK

Message: Document the meaning and constraints of fields in mutation and filter inputs. Generated request types carry names and types but not the domain knowledge required to populate them.

How to fix: Describe GraphQL input fields

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Mutations have many top-level arguments

  • Rule ID: graphql.mutation.arguments.unstructured
  • Severity: suggestion
  • Affected surfaces: CLI, MCP, SDK

Message: Prefer one named input object for mutations with several fields. A stable input type is easier to document, evolve, validate, and pass through SDKs and tools.

How to fix: Introduce a mutation input object

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Mutations return only a scalar

  • Rule ID: graphql.mutation.result.scalar
  • Severity: warning
  • Affected surfaces: API, CLI, MCP, SDK

Message: Return a structured payload when callers need an identifier, resulting object, warnings, or domain errors. A Boolean or scalar result cannot explain partial success or provide a useful next action.

How to fix: Model a structured mutation payload

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Paginated fields return a bare list

  • Rule ID: graphql.pagination.connection.incomplete
  • Severity: warning
  • Affected surfaces: CLI, MCP, SDK

Message: Fields accepting first/last/after/before should return a connection with pageInfo and stable cursors. Generated pagination helpers and agents cannot know whether or how to request another page.

How to fix: Return a complete connection type

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Review optional identifier arguments

  • Rule ID: graphql.query.identifier.nullable
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Confirm whether omission means a broader lookup, current subject, filter, or invalid call. Make the identifier non-null only when the schema's intended behavior requires it. Generated callers correctly preserve nullability, but the contract alone may not explain what omission means.

How to fix: Review identifier nullability

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Deprecated root operations do not identify a replacement

  • Rule ID: graphql.root_field.deprecation.replacement_missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Name the supported query or mutation in the deprecation reason so generated callers have a migration path. Generated clients preserve the deprecation marker, but users and agents cannot safely migrate from a generic reason.

How to fix: Name the replacement GraphQL operation

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Root operations are missing descriptions

  • Rule ID: graphql.root_field.description.missing
  • Severity: suggestion
  • Affected surfaces: API, CLI, MCP, SDK

Message: Describe when each query or mutation should be used, including side effects and important constraints. Generated methods and tools have a signature but no behavioral guidance.

How to fix: Add GraphQL field descriptions

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

Custom scalars have no portable representation

  • Rule ID: graphql.scalar.mapping.missing
  • Severity: warning
  • Affected surfaces: CLI, MCP, SDK

Message: Map each custom scalar to string, integer, number, boolean, or JSON in project configuration. Generated SDKs must expose unknown values instead of a useful native type.

How to fix: Declare scalar mappings in the Typeship project

API-owner decision: Yes. The contract identifies the concern but cannot prove the intended replacement.

Copy a starting prompt for this rule. Live findings include revision-specific evidence.

On this page

Recommended workflowOpenAPI rules (43)The contract still uses Swagger 2.0Examples contradict their declared schemasGenerated public names need collision resolutionThe API has no top-level descriptionAgent safety hints contradict each otherDeprecated operations do not identify a replacementOperations are missing behavioral descriptionsDestructive operations appear to be publicOperation identifiers are not uniqueOperations are missing stable identifiersPagination signals are incompletePagination appears present but Typeship cannot interpret itPath parameters do not match the URL templateRequest bodies have no schemaError correlation is inconsistent within an operationOne operation uses multiple error identity conventionsError bodies have no stable machine-readable identityFailure responses have no machine-readable schemaOperations declare no failure responsesNon-2xx outcomes are not generated as successRate-limit responses do not declare Retry-AfterSuccessful response bodies have no schemaOperations have no non-error responseStructured validation issues do not identify the invalid inputConfigured retries rely on unverified write safetySecurity requirements reference missing schemesOperations require authentication generated clients cannot sendOAuth requirements reference undefined scopesStream events have no declared event identityOperations are missing summariesOperations are not grouped into resourcesAccepted work has no declared follow-up handleBatch operations do not expose per-item outcomesList workflows have no discoverable retrieve operationAmbiguous operation inputs are missing descriptionsSchema properties are both read-only and write-onlyObject schemas leave their dictionary shape implicitAmbiguous schema properties are missing descriptionsServer variables are missing defaultsServer selection needs client configurationWebhook payloads have no stable event identityWebhook payloads have no usable request schemaWebhook verification inputs are not declaredGraphQL rules (11)Unions or interfaces are missing descriptionsOperation arguments are missing descriptionsEnum values are missing descriptionsInput fields are missing descriptionsMutations have many top-level argumentsMutations return only a scalarPaginated fields return a bare listReview optional identifier argumentsDeprecated root operations do not identify a replacementRoot operations are missing descriptionsCustom scalars have no portable representation