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.
Recommended workflow
- Retrieve the Spec's latest revision with
typeship spec-revisions get <spec_revision_id> --include diagnosticsor open Console → Project → Diagnostics. - Start with blocking or newly added findings. Read every affected location before editing.
- Apply an exact reviewed patch when Typeship provides one. When API-owner decision is yes, ask rather than inventing behavior.
- Change the source Spec, not generated output.
- Retrieve the Project's Spec ID, refresh the Spec, confirm the exact rule and locations resolved, then review generated surface and compatibility changes.
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.
Spec compatibility
What Typeship accepts: Swagger 2.0, OpenAPI 3.0 and 3.1, and GraphQL, and how each construct maps to the generated packages.
Spec errors and warnings
The messages the generator returns for a Spec it cannot use, and the warnings it attaches to a Generation, quoted verbatim with what to do next.