swagger-api / swagger-api/swagger-client

Recursive external JSON Schema refs can overflow resolveSubtree

Open
#4,221 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
2.7k
Forks
765
Avg merge
1d 1h
Merged PRs (30d)
6

Description

Summary

resolveSubtree can run into a stack overflow when resolving recursive external JSON Schema references.

This is related to earlier resolver issues such as #1362, but the case below is reproducible on current master with recursive external JSON Schema documents.

Problem

Swagger UI can hang or throw:

RangeError: Maximum call stack size exceeded

when rendering a schema that references an external JSON Schema document which recursively references itself through another external document.

The schema shape is valid JSON Schema recursion, for example:

object.json -> basic-types.json -> object.json

A real-world example is OGraf's GDD schema, where an object schema references basic types, and object/array child schemas can reference the object schema again.

Minimal shape

An OpenAPI 3.0.3 schema contains:

components:
  schemas:
    RenderTargetSchema:
      type: object
      properties:
        gdd:
          $ref: '#/components/schemas/ShallowGDDObjectSchema'

    ShallowGDDObjectSchema:
      allOf:
        - $ref: 'http://mock.swagger.test/gdd/object.json'

/gdd/object.json references /gdd/basic-types.json, and /gdd/basic-types.json references /gdd/object.json again from nested items / properties.

Expected behavior

resolveSubtree should terminate safely when it reaches a recursive external $ref.

At the recursive boundary, it should preserve a $ref or otherwise avoid expanding the same external reference path forever.

Actual behavior

The resolver can continue expanding the recursive external references until Swagger UI hangs or throws a stack overflow.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the resolveSubtree implementation and reproduce the provided OpenAPI 3.0.3 shape, following the object.json and basic-types.json external references. Trace how recursive external $refs are expanded and add coverage for the recursive boundary. Done means resolution terminates without hanging or overflowing while preserving a $ref or otherwise avoiding repeated expansion.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.