[Bug]: Resolver error for array item refs in nested external OpenAPI documents

Author: htgylzhqCreated Aug 21, 2026Updated Aug 21, 2026

Describe the bug you're encountering

Swagger UI reports a resolver error when an operation is reached through an external Path Item and its request schema is in another external YAML file. The schema contains allOf/oneOf branches and an array whose items is a local $ref to an enum in that schema file.

All referenced YAML files are served successfully. Replacing the two items.$ref nodes with equivalent inline string enums removes the error, so this appears to be a resolver issue rather than an unavailable-file or invalid-schema issue.

This looks related to #5820, but this reproduction specifically requires the external Path Item -> external Schema reference chain.

Environment

Swagger UI: 5.32.14 (latest at the time of reporting)
OpenAPI: 3.0.3
Browser: Chromium
Installation: CDN assets from [email protected]

To reproduce

Serve the following three files from one directory, for example:

bash

python3 -m http.server 8080

Then open http://localhost:8080/index.html.

index.html

xml

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Swagger UI resolver reproduction</title>
  <link rel="stylesheet" href="https://unpkg.com/[email protected]/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/[email protected]/swagger-ui-bundle.js"></script>
<script src="https://unpkg.com/[email protected]/swagger-ui-standalone-preset.js"></script>
<script>
  window.ui = SwaggerUIBundle({
    url: 'openapi.yml',
    dom_id: '#swagger-ui',
    presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
    layout: 'StandaloneLayout'
  })
</script>
</body>
</html>

openapi.yml

yaml

openapi: 3.0.3
info:
  title: Chart configuration API
  version: 1.0.0
paths:
  /charts:
    $ref: './paths/charts.yml#/charts'

paths/charts.yml

yaml

charts:
  post:
    operationId: createChart
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../schemas/chart.yml#/ChartConfiguration'
    responses:
      '204':
        description: Chart created

schemas/chart.yml

yaml

ChartConfiguration:
  type: object
  additionalProperties: false
  required: [view]
  properties:
    view:
      type: string
    chartTypes:
      type: array
      items:
        $ref: '#/ChartType'
  allOf:
    - oneOf:
        - properties:
            view:
              type: string
              enum: [summary]
        - properties:
            view:
              type: string
              enum: [detail]
    - oneOf:
        - additionalProperties: true
          required: [chartTypes]
          properties:
            view:
              type: string
              enum: [summary]
            chartTypes:
              type: array
              minItems: 1
              items:
                $ref: '#/ChartType'
          allOf:
            - oneOf:
                - additionalProperties: true
                  properties:
                    includeLegend:
                      type: boolean
                      enum: [true]
                - additionalProperties: true
                  properties:
                    includeLegend:
                      type: boolean
                      enum: [false]
        - additionalProperties: true
          properties:
            view:
              type: string
              enum: [detail]

ChartType:
  type: string
  enum: [line, bar, pie]

Actual behavior

Swagger UI renders the operation but displays:

Resolver error
Cannot read properties of undefined (reading 'items')

The browser console points to applyOperation / applyPatch in swagger-ui-bundle.js.

Expected behavior

The local ChartType references in items should resolve without an error. The schema is valid OpenAPI 3.0.3, and every YAML file is accessible.

Workaround

Replacing both occurrences below with the equivalent inline schema removes all resolver errors:

yaml

items:
  type: string
  enum: [line, bar, pie]

Source: swagger-api/swagger-ui

View original on GitHub View discussion on GitHub