OpenAPI error guides for API Gateway REST

Match a finding from this checker, understand its cause, and work through a minimal example. These guides separate OpenAPI errors, API Gateway REST compatibility warnings, and this checker’s processing limits. They do not reproduce every possible AWS import error.

Diagnose your file with the free local checker →

• Root-level security is not applied by API Gateway

  Make inherited security explicit without changing operation overrides.

  Checker finding: Root security is ignored by API Gateway

• External references and single-file imports

  Bundle referenced definitions locally before checking this file again.

  Checker finding: External reference is blocked

• Repair an internal reference without losing its target

  Check pointer spelling, target existence, and the kind of component referenced.

  Checker finding: Invalid internal reference

• The nullable keyword is not supported by API Gateway

  Decide explicitly how the API should handle null and omitted values.

  Checker finding: Schema nullable is unsupported

• Review unsupported schema keywords

  Preserve the contract while choosing where unsupported behavior is enforced.

  Checker finding: Schema readOnly is unsupported

• Resolve security schemes and review AWS authorizers

  A security requirement must name a valid scheme, and import needs the intended authorizer.

  Checker finding: Security scheme cannot be resolved

• Review security on callbacks and referenced Path Items

  Shared or callback operations need manual security review before any repair.

  Checker finding: Callback security needs manual review

• Rename components only with their references

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

  Checker finding: Invalid OpenAPI component name

• Review API Gateway path segments

  Changing a path changes the URL that clients use.

  Checker finding: Path needs manual review

• Correct the reported OpenAPI structure

  Resolve schema and object-shape errors before requesting a repair.

  Checker finding: Invalid OpenAPI structure

• Use a supported OpenAPI version

  This checker supports OpenAPI 3.0.0 through 3.0.4 only.

  Checker finding: Unsupported OpenAPI version

• Make the input an unambiguous JSON or YAML document

  Start with one nonempty document and fix syntax without discarding data.

  Checker finding: Duplicate mapping keys are not accepted.

• Use explicit, JSON-compatible YAML values

  Aliases, merge keys, tags, directives, and non-string keys are outside this parser’s subset.

  Checker finding: YAML aliases and merge expansion are disabled. Use explicit values instead.

• Preserve numeric values exactly

  Some numeric literals cannot survive this tool’s serialization unchanged.

  Checker finding: Numbers must be finite and integers must fit exactly within JavaScript’s safe integer range.

• Stay within local processing limits

  A safety budget was reached; no partial automatic repair is produced.

  Checker finding: Document exceeds the 1 MiB local processing limit.

• A safe preview could not be produced

  Keep the original and review why the complete repair was rejected.

  Checker finding: Safe preview could not be produced

Manual review may be needed even when a safe security-copy repair is available. Always review the output and test the imported API in a non-production environment.

Check your file locally