operationId and tags in OpenAPI: naming conventions that keep generated SDKs and docs usable

OpenAPI's operationId and tag fields are crucial naming conventions that ensure generated SDKs and documentation remain usable and stable.

A poorly chosen operationId leads to immediate problems - methods may be named getV1UsersByIdGet, postV1UsersPost, or usersGet2. Changing an operationId later breaks every caller, while unhelpful tags result in 200 operations listed in a single flat sidebar.

The operationId becomes the method/function name after code generation, while tags organize operations into sections or SDK classes. It must be unique across the entire document, using lowerCamelCase with ASCII characters, and avoid hyphens, dots, or spaces. The id should be verb-first, resource-oriented, and specific enough to be unambiguous without the path.

Tags should form a small, stable taxonomy aligned to business domains, not URLs. Aim for 3-4 tags max per operation, and name them as customers would recognize, like Billing or Orders. Summary and description fields aid both human readability and AI tool generation - they should disambiguate operations and provide necessary details.

Linter rules should enforce these conventions, flagging issues like missing operationIds, duplicate tags, or version numbers in the id. Integrating these checks into CI pipelines prevents breaking changes. Consistent naming conventions ensure clean client APIs (e.g., client.users.list()), smooth mocking, and stable AI tool generation.