OpenAPI repair

Repair an internal reference without losing its target

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

Match the finding

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

Cause and scope

A same-document $ref is a URI fragment containing a JSON Pointer. This MVP additionally limits ordinary references to direct, named components of the matching kind. A pointer can resolve and still be outside the validated subset.

What to do

Check the reported pointer against the exact component name and collection. If moving an object into a named component is appropriate, preserve its complete contents and update all callers before validating again.

  1. For a missing target, compare spelling and case with the matching components entry.
  2. For malformed pointers, use #/ followed by tokens; escape ~ as ~0 and / as ~1 inside each token. URI percent escapes must also be valid.
  3. For unsupported target locations, review the object kind and migrate it deliberately to a direct named component, or use a workflow that supports the original layout.

Schema fragment: a direct target and a matching reference

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
  responses:
    PetResponse:
      description: A pet
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Pet'

PetResponse contains a schema reference, so it points into components/schemas. A response reference would instead point to #/components/responses/PetResponse. Component names in this tool cannot contain slash or tilde; correct pointer escaping does not make an invalid component name acceptable.

Avoid a misleading fix

Do not replace a missing target with {} or assume that a schema can reference a response, parameter, or extension payload. Do not rename a component without updating its references.

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.