OpenAPI repair

Rename components only with their references

OpenAPI component names and API Gateway model names have different restrictions.

Match the finding

These titles and messages come from this local checker. They are not AWS service error quotes.

Cause and scope

OpenAPI component keys use letters, digits, dots, underscores, and hyphens. API Gateway REST model names are more restrictive: letters and digits only. A model-name warning does not itself mean the OpenAPI name is invalid.

What to do

Choose a valid, unique name and update every reference and dependent mapping as one reviewed change. Recheck the whole document and generated clients after renaming.

  1. Identify whether the finding concerns the OpenAPI component key or the narrower AWS model-name rule.
  2. Choose a collision-free replacement and locate all references and external consumers.
  3. Rename consistently, check unresolved references, and test the import.

Schema fragment: an approved rename must update the reference too

# Previously: Pet-Record and #/components/schemas/Pet-Record
# After confirming PetRecord is unique, update both together.
components:
  schemas:
    PetRecord:
      type: object
      properties:
        id:
          type: string
    PetEnvelope:
      type: object
      properties:
        pet:
          $ref: '#/components/schemas/PetRecord'

Pet-Record is an allowed OpenAPI component name but triggers this checker’s AWS model-name warning. This example changes the name and its one caller together. A real rename must cover every caller and preserve the complete original schema.

Avoid a misleading fix

Do not strip punctuation mechanically: different names can collapse to the same result. Do not rename just the definition while leaving its references unchanged.

Check your complete file locally

Choose one OpenAPI 3.0 JSON or YAML file, diagnose the findings, and review any eligible security-copy preview before downloading. No file upload or account is needed.

Open the free OpenAPI checker →

Related findings

Sources and scope

Scope: this local checker, API Gateway REST APIs, and OpenAPI 3.0. Guidance reviewed 4 October 2026. A passing check does not guarantee import or runtime behavior.