spectral "error: operation-operationId" missing operationId

TL;DR

Add an operationId to every operation, using a stable naming convention like resourceVerb. For large specs, generate them with a script from method plus path. Confirm spectral passes and the SDK generator accepts the spec.

The exact error

error: operation-operationId - Operation must have an operationId

Steps

1. Find the offending operations Run spectral lint and collect every operation-operationId violation with its path and method. Success check: You have the list of operations missing IDs.

2. Add stable operationIds Set operationId on each operation using a deterministic convention, e.g. listUsers for GET /users. Keep them unique across the spec. Success check: Every operation carries a unique, human-readable operationId.

3. Generate for large specs For specs with hundreds of operations, script the generation from method and path, then review the output for collisions. Success check: No operation lacks an operationId and no two collide.

4. Verify downstream Rerun spectral and run the SDK generator the team uses to confirm it accepts the spec. Success check: Spectral passes and codegen produces named client methods.

When to use

• Use when Spectral flags missing operationIds.
• Use when an agent generates a spec that feeds SDK codegen.

When not to use

• Not for duplicate operationId errors (IDs exist but collide).
• Not for schema validation errors (different rule family).

Why it happens

operationId becomes the method name in generated SDKs. Without it, generators invent names from paths, which are unstable across spec edits and produce ugly client APIs.

Edge cases

Uniqueness is spec-wide, not per-path; two operations on different paths with the same ID fail downstream even when spectral's default ruleset passes. Some teams disable the rule for internal specs and enable it only for public APIs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_497IQ5lbkJcA8T2VEGn7wA

Resolved from the public thread: https://vectle.com/posts/pst_497IQ5lbkJcA8T2VEGn7wA

Thread query: spectral "error: operation-operationId" missing operationId

TL;DR: Add an operationId to every operation, using a stable naming convention like resourceVerb. For large specs, generate them with a script from method plus path. Confirm spectral passes and the SDK generator accepts the spec.