Diagnostics reference

Looking up a GLOTTO_* code? Jump to config diagnostics, migration diagnostics, or fatal errors. Every code Glotto can emit has a row in this reference.

Glotto’s SDK-readiness ruleset describes spec shapes that produce awkward or incomplete SDKs — missing operationIds, anonymous schemas, undeclared errors or auth, missing idempotency advertisement. Resolving them is the cheapest way to raise the quality of every generated SDK at once, and the rule ids below are the ones diagnostics.rules accepts.

Where you see them: glotto generate prints every finding for your spec, alongside any problems in your glotto.yml. The ruleset runs as part of generation, so there is nothing separate to run and nothing to remember — if your spec has a readiness problem, you hear about it the next time you generate.

This page enumerates every rule in that ruleset, then links to every coded diagnostic Glotto reports. Each finding carries a Spectral-compatible shape:

{ "rule": "operation-id-missing", "severity": "error", "path": ["paths", "/pets", "post"], "message": "…" }

Severities

Every rule is error or warning, and the two mean different things: an error blocks correct SDK generation, a warning is a quality or developer-experience problem in the SDK that results. A rule’s default severity is listed with it below, and diagnostics.rules overrides it.

Release-gating guidance

Treat the two severities as a release ladder:

Resolve every error before your first published release — errors block correct SDK generation (e.g. a method with no name).
Resolve every warning before 1.0 — warnings are quality and DX issues that are cheap to fix early and awkward to change after consumers depend on the SDK.

To turn the second rung into a hard gate, cap the allowed warning count with diagnostics.max_warnings, then ratchet it down toward zero on the way to 1.0.

Errors

Errors block high-quality generation and should be fixed first.

`operation-id-missing`

Severity: error · Path: paths.<path>.<method>

An operation has no operationId. SDK method names derive from operationId, so without one the method name has to be synthesized from the path and verb — producing awkward, unstable names.

Fix: give every operation a unique, descriptive operationId (e.g. listPets, createPet).

Warnings

Warnings don’t block generation but degrade SDK quality, docs, or ergonomics.

`operation-undescribed`

Severity: warning · Path: paths.<path>.<method>

An operation has neither a summary nor a description. The generated SDK reference and the MCP tool descriptions both draw on this prose, so its absence yields thin docs and lower-quality MCP tool definitions.

Fix: add a summary (and ideally a description) to each operation.

`inline-object-schema`

Severity: warning · Path: the schema’s written location, usually paths.<path>.<method>.requestBody|responses.<code>.content.<mediaType>.schema, or inside the referenced path-item, request-body or response component. A shared operation is judged once.

A request body or response uses an anonymous inline object schema (a type: object / properties block, or an array of one) instead of a $ref to a named components.schemas entry. Inline objects generate unnamed, un-reusable SDK types.

Fix: hoist the schema into components.schemas and reference it with $ref.

`no-error-response`

Severity: warning · Path: paths.<path>.<method>.responses

An operation declares no 4xx, 5xx, or default response, so the SDK cannot model the errors the endpoint can return — callers get untyped failures.

Fix: declare the error responses the operation can produce (a shared default error response is a good baseline).

`mutation-no-idempotency-key`

Severity: warning · Path: paths.<path>.post

A POST operation does not advertise an Idempotency-Key header parameter. Glotto can auto-generate and inject idempotency keys so retries of a mutation are safe — but only when the endpoint accepts the header.

Fix: add an Idempotency-Key header parameter to the operation (or to the path item, shared across its operations). See Idempotency keys for the concept.

`required-header-param-not-client-scoped`

Severity: warning · Path: paths.<path>.<method>

An operation declares a required header parameter that only a minority of the document’s operations declare at all. Every generated SDK takes such a header as a normal call argument, so those are unaffected — but a target whose only home for it is client-scoped cannot express a value that varies from one operation to the next. The generated Terraform provider is the case in point: the header becomes a Required argument on the provider "glotto" block, and that single value is sent on every request the provider makes.

A header the whole API requires (a tenant id, an API-version date) is not flagged — one provider-block value is exactly right for it.

Fix: if the value really is constant for the whole client, declare the header on every operation that accepts it — or set it once with auto_populate in glotto.yml, which stamps it into the request and removes it from the generated signatures. If it genuinely varies per call, keep using it from the SDKs (where it is a per-call argument) and expect the Terraform provider to send one fixed value.

`no-security-defined`

Severity: warning · Path: (document root)

The API declares no security at all — no components.securitySchemes, no root security, and no per-operation security. The generated SDK has nothing to wire authentication to.

Fix: declare a security scheme under components.securitySchemes and apply it via a root or per-operation security requirement. See Authentication.

`unresolved-ref`

Severity: warning · Path: the node carrying the $ref, where it is written — paths.<path>, paths.<path>[.<method>].parameters.<i>, paths.<path>.<method>.requestBody, or paths.<path>.<method>.responses.<code>. When the path item is itself a $ref, what it shares is reported inside the component it is written in (components.pathItems.<name>.parameters.<i>), once, and the message names up to ten paths that lose it, with a count of any remaining paths.

A $ref on a path item, a parameter, a request body or a response points at nothing Glotto can use, so what it names is left out of every generated SDK, the CLI and the MCP server: a path item’s operations are not generated at all, a parameter is missing from the method, an operation is generated without its request body, and a response is generated untyped. The message says which $ref failed and why:

it names a location that does not exist in the document;
it names a location holding a different kind of object (a parameter $ref pointing at a schema, including one nested inside a parameter or another schema, such as #/components/parameters/Limit/schema);
it forms a cycle;
it is a same-document fragment that is not a pointer to anything inside the document: a plain name such as #Cursor, which OpenAPI does not resolve for a $ref, or # alone, which names the whole document;
it points into another file. Glotto reads one OpenAPI document and does not follow references across files.

A $ref may point anywhere in the document — #/components/parameters/Cursor, or #/paths/~1pets/get/parameters/0 — so only a reference that genuinely resolves to nothing is reported.

Fix: point the $ref at an existing object of the right kind, written as a JSON pointer (#/components/parameters/Cursor). For a multi-file spec, bundle it into a single document before generating (for example with redocly bundle or swagger-cli bundle).

Coded diagnostics

Every stable GLOTTO_* code remains documented in this reference, grouped by where it is raised:

Roadmap

Importing your existing Spectral ruleset, custom rules, one-click autofixes, and inline editor (LSP) diagnostics are tracked as follow-ons to the linter — they are not available yet. Per-rule severity overrides and suppression, and a release-gating warning budget, are available today via the diagnostics config block.