External references and single-file imports

Bundle referenced definitions locally before checking this file again.

Match the finding

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

External reference is blocked
External references are never fetched. Bundle the referenced definitions into this document before repairing it.

Cause and scope

References to other files are unsupported by AWS REST import. This checker never fetches remote URLs or local files and disables automatic repair when it encounters an external reference.

What to do

Use a trusted local bundling workflow with the actual referenced documents. Preserve their types, constraints, nested references, and security definitions; then recheck the complete bundled file.

Find the original file or URL named by the reported $ref and inspect it in your trusted environment.
Bring the referenced object into the matching components collection and update every affected reference. Resolve its nested references as well.
Validate the bundled document and compare it with the original before checking and importing it.

Schema fragment: after bundling the actual Pet definition

# Before: $ref: './models.yaml#/Pet'
# After: the original Pet schema is included below.
components:
  schemas:
    Pet:
      type: object
      required: [id]
      properties:
        id:
          type: string
paths:
  /pets:
    get:
      responses:
        '200':
          description: A pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

This is an illustrative fragment, not a replacement for your referenced schema. The internal reference must point to the exact object copied from the original source. Internal references alone do not guarantee AWS compatibility.

Avoid a misleading fix

Do not delete a reference, replace it with an empty object, or copy an unrelated example schema. Do not upload private definitions to an unknown online resolver.

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.