How can I use OpenAPI overlays to rename operationIds for SDK consistency? #

The operationId field directly determines the name of the generated method in most client SDK generators. When an OpenAPI document has been built incrementally by multiple teams, operationId values often end up inconsistent — some verb-first, some resource-first, some abbreviated. Renaming them wholesale in the canonical document can be risky if other tooling (routing, telemetry, contract tests) already depends on the existing values. The OpenAPI Overlay Specification provides a safer path: rename operationId only in the copy used for SDK generation.

Identifying Inconsistent Naming #

paths:
  /users/{id}:
    get:
      operationId: fetchUser
  /orders:
    get:
      operationId: list_orders
    post:
      operationId: OrdersCreate

Three different naming conventions in three operations will produce an inconsistent, unpolished-feeling SDK.

Normalizing With an Overlay #

overlay: 1.0.0
info:
  title: SDK OperationId Normalization Overlay
  version: 1.0.0
actions:
  - target: $.paths['/users/{id}'].get
    update:
      operationId: "getUser"
  - target: $.paths['/orders'].get
    update:
      operationId: "listOrders"
  - target: $.paths['/orders'].post
    update:
      operationId: "createOrder"

Establishing a Naming Convention Going Forward #

Document the convention your overlay enforces (for example, camelCase, verb-first: get, list, create, update, delete followed by the resource name) so that future overlay entries stay consistent as new operations are added.

Automating the Rename With a Script #

For large APIs, hand-writing dozens of rename actions is tedious. A short script can read the base document, apply a naming convention transformation, and emit the overlay file automatically:

const yaml = require('js-yaml');
const fs = require('node:fs');

const spec = yaml.load(fs.readFileSync('openapi.yaml', 'utf8'));
const actions = [];

for (const [path, methods] of Object.entries(spec.paths)) {
  for (const [method, operation] of Object.entries(methods)) {
    const normalized = normalizeOperationId(method, path);
    if (operation.operationId !== normalized) {
      actions.push({
        target: `$.paths['${path}'].${method}`,
        update: { operationId: normalized }
      });
    }
  }
}

fs.writeFileSync('sdk-naming-overlay.yaml', yaml.dump({
  overlay: '1.0.0',
  info: { title: 'SDK OperationId Normalization Overlay', version: '1.0.0' },
  actions
}));

Applying the Overlay Before Generation #

redocly join openapi.yaml --overlay sdk-naming-overlay.yaml -o build/openapi.sdk.yaml
openapi-generator-cli generate -i build/openapi.sdk.yaml -g typescript-fetch -o clients/typescript

Keeping the Canonical Document Untouched #

Because routing configuration, contract tests, and telemetry dashboards may already reference the original operationId values, leaving the base document unchanged avoids a much larger, riskier migration across unrelated systems. The overlay isolates the blast radius of the rename to SDK generation only.

Related Reading #

See What is the OpenAPI Overlay Specification? and How can I use OpenAPI overlays to inject vendor extensions for SDK generation? for related SDK tooling techniques.

Last updated on July 16, 2026.