Diagnostic rule reference

This catalog lists every Diagnostic Typeship can emit. Rule IDs are stable control fields; wording may improve as the analyzer becomes more precise.

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

Recommended workflow

1. Retrieve the current report with typeship projects retrieve-diagnostics <project_id> 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 Definition, not generated output.
5. Refresh Diagnostics, confirm the exact rule and locations resolved, then review generated surface and compatibility changes.

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

OpenAPI rules (42)

The contract still uses Swagger 2.0

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

What it checks: Typeship converts Swagger 2.0 before generation, but OpenAPI 3.1 expresses modern request bodies, nullability, webhooks, and JSON Schema more precisely.

Why it matters: 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.

Examples contradict their declared schemas

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

What it checks: Update the example or schema so the documented payload is valid in its request, response, parameter, or property context.

Why it matters: 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.

Generated public names need collision resolution

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

What it checks: 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.

Why it matters: 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.

Generated surface effect: Resolving the collision can rename CLI commands, MCP tools, and SDK methods.

The API has no top-level description

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

What it checks: Add a short statement of purpose, audience, and important behavioral constraints to info.description.

Why it matters: 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.

Agent safety hints contradict each other

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

What it checks: An operation cannot be both read-only and destructive. Correct the advisory metadata to describe the operation's intended effect.

Why it matters: 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.

Deprecated operations do not identify a replacement

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

What it checks: Point callers to the supported operation or migration path in the description, external documentation, or an explicit replacement extension.

Why it matters: 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.

Generated surface effect: Removing the deprecated operation later will remove its CLI command, MCP tool, and SDK method.

Operations are missing behavioral descriptions

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

What it checks: Describe preconditions, side effects, important defaults, and when a caller should use the operation.

Why it matters: 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.

Destructive operations appear to be public

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

What it checks: Confirm that each DELETE operation intentionally has no authentication requirement.

Why it matters: 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.

Operation identifiers are not unique

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

What it checks: Every operationId must identify exactly one operation.

Why it matters: 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.

Operations are missing stable identifiers

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

What it checks: Give every operation a unique operationId. Typeship can derive names, but an authored identifier is the durable public method name.

Why it matters: 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.

Generated surface effect: Changing operationId can rename generated CLI commands, MCP tools, and SDK methods.

Pagination signals are incomplete

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

What it checks: Make the detected cursor, page, or offset shape unambiguous, or configure this operation's pagination interpretation explicitly.

Why it matters: 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.

Pagination appears present but Typeship cannot interpret it

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

What it checks: 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.

Why it matters: 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.

Path parameters do not match the URL template

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

What it checks: Every {parameter} in a path must have a required path parameter with the same name.

Why it matters: 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.

Request bodies have no schema

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

What it checks: Every declared request-body media type needs a schema.

Why it matters: 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.

Error correlation is inconsistent within an operation

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

What it checks: Use one request, trace, or correlation identifier convention across the operation's structured failures, or document why some failures cannot carry it.

Why it matters: 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.

One operation uses multiple error identity conventions

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

What it checks: Use one stable error discriminator convention across this operation's structured failures, or document why distinct error families are intentional.

Why it matters: 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.

Error bodies have no stable machine-readable identity

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

What it checks: 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.

Why it matters: 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.

Failure responses have no machine-readable schema

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

What it checks: Give each declared error-body media type a schema with a stable code and recovery detail. Omit content for intentionally bodyless errors.

Why it matters: 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.

Operations declare no failure responses

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

What it checks: Review the authentication, authorization, validation, conflict, not-found, throttling, and transient failures this operation can actually return, and document the applicable ones.

Why it matters: 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.

Non-2xx outcomes are not generated as success

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

What it checks: 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.

Why it matters: 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.

Rate-limit responses do not declare Retry-After

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

What it checks: If the server supplies retry timing, declare the Retry-After response header. If it intentionally does not, document the caller's recovery rule instead.

Why it matters: 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.

Successful response bodies have no schema

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

What it checks: Add a schema to each declared response media type that returns a body. Omit content when the response is intentionally bodyless.

Why it matters: 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.

Operations have no non-error response

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

What it checks: Declare a successful, redirect, or default response that describes a possible non-error outcome.

Why it matters: 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.

Structured validation issues do not identify the invalid input

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

What it checks: When a validation response exposes an issue array, give each issue a field, path, pointer, parameter, or location when the server can identify it.

Why it matters: 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.

Configured retries rely on unverified write safety

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

What it checks: Project configuration retries this POST or PATCH operation, but the contract exposes no idempotency-key input. Confirm server deduplication or narrow the retry policy.

Why it matters: 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.

Security requirements reference missing schemes

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

What it checks: Every name in a security requirement must exist in components.securitySchemes.

Why it matters: 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.

OAuth requirements reference undefined scopes

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

What it checks: Every OAuth scope named by a security requirement must be defined by that security scheme.

Why it matters: 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.

Stream events have no declared event identity

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

What it checks: 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.

Why it matters: 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.

Operations are missing summaries

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

What it checks: Add a short action-oriented summary to each operation.

Why it matters: 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.

Operations are not grouped into resources

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

What it checks: Assign at least one stable resource tag to each operation.

Why it matters: 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.

Generated surface effect: Adding or changing the first tag can rename CLI commands and MCP tools and move methods between SDK resources.

Accepted work has no declared follow-up handle

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

What it checks: 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.

Why it matters: 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.

Batch operations do not expose per-item outcomes

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

What it checks: For bulk or batch work, describe per-item success and failure results, or state that the operation is atomic.

Why it matters: 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.

List workflows have no discoverable retrieve operation

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

What it checks: Review whether callers need a stable single-resource lookup after listing a collection. A list-only feed, report, or aggregate may be intentional.

Why it matters: 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.

Ambiguous operation inputs are missing descriptions

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

What it checks: Describe identifier meaning, units, time-zone expectations, money representation, defaults, or constraints where the name and schema do not make them self-evident.

Why it matters: 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.

Schema properties are both read-only and write-only

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

What it checks: A property cannot be excluded from both request and response shapes. Choose the direction in which it is present.

Why it matters: 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.

Object schemas leave their dictionary shape implicit

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

What it checks: If this is an intentional open dictionary, declare additionalProperties explicitly. Otherwise define the known properties.

Why it matters: 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.

Ambiguous schema properties are missing descriptions

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

What it checks: Document properties whose identifier, unit, time-zone, money, nullability, or enum semantics are not clear from their name and schema.

Why it matters: 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.

Server variables are missing defaults

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

What it checks: Every variable used in an OpenAPI server URL must declare a default value.

Why it matters: 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.

Server selection needs client configuration

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

What it checks: 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.

Why it matters: 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.

Webhook payloads have no stable event identity

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

What it checks: Expose a stable type, event, kind, name, or id field when one endpoint delivers multiple event shapes, or document the single event kind.

Why it matters: 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.

Webhook payloads have no usable request schema

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

What it checks: Declare a request-body schema for every webhook event Typeship should expose.

Why it matters: 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.

Webhook verification inputs are not declared

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

What it checks: Declare the signature, timestamp, delivery identifier, token, or security requirement consumers use to authenticate webhook deliveries.

Why it matters: 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.

GraphQL rules (11)

Unions or interfaces are missing descriptions

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

What it checks: Describe why the variants share one return type and how callers should distinguish them.

Why it matters: 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.

Operation arguments are missing descriptions

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

What it checks: Document identifiers, units, formats, defaults, and constraints on root-field arguments.

Why it matters: 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.

Enum values are missing descriptions

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

What it checks: Explain values whose meaning is not completely captured by their names.

Why it matters: 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.

Input fields are missing descriptions

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

What it checks: Document the meaning and constraints of fields in mutation and filter inputs.

Why it matters: 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.

Mutations have many top-level arguments

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

What it checks: Prefer one named input object for mutations with several fields.

Why it matters: 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.

Mutations return only a scalar

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

What it checks: Return a structured payload when callers need an identifier, resulting object, warnings, or domain errors.

Why it matters: 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.

Paginated fields return a bare list

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

What it checks: Fields accepting first/last/after/before should return a connection with pageInfo and stable cursors.

Why it matters: 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.

Review optional identifier arguments

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

What it checks: 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.

Why it matters: 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.

Deprecated root operations do not identify a replacement

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

What it checks: Name the supported query or mutation in the deprecation reason so generated callers have a migration path.

Why it matters: 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.

Generated surface effect: Removing the deprecated field later will remove its generated CLI command, MCP tool, and SDK method.

Root operations are missing descriptions

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

What it checks: Describe when each query or mutation should be used, including side effects and important constraints.

Why it matters: 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.

Custom scalars have no portable representation

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

What it checks: Map each custom scalar to string, integer, number, boolean, or JSON in project configuration.

Why it matters: 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.