[BUG] Cannot parse OpenAPI 3.1 specs using $dynamicRef / $dynamicAnchor (blocked by swagger-parser)

[aqeelat]

Summary

OpenAPI Generator fails to parse any OpenAPI 3.1 spec that uses $dynamicRef / $dynamicAnchor (JSON Schema 2020-12). The parser throws SpecValidationException: Could not find /components/schemas/<name> because swagger-parser cannot resolve schemas containing $dynamicAnchor when the enclosing schema also has $id.

Reproduction

Minimal fixtures demonstrating the issue:

• Recursive category tree: https://github.com/aqeelat/openapi-dynamicref-adoption-tracker/blob/main/fixtures/recursive-category-tree.yaml
• Nested workspace resources: https://github.com/aqeelat/openapi-dynamicref-adoption-tracker/blob/main/fixtures/nested-workspace-resources.yaml
• Pagination/generic wrapper (named schemas): https://github.com/aqeelat/openapi-dynamicref-adoption-tracker/blob/main/fixtures/generic-schema-binding.yaml

npx @openapitools/openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/aqeelat/openapi-dynamicref-adoption-tracker/main/specs/recursive-category-tree/oas-3.1.2.json \
  -g typescript-fetch \
  -o /tmp/dynamicref-test

Result: SpecValidationException: Could not find /components/schemas/PaginatedTemplate

Note: The paginated-response.yaml variant (inline response binding, no named wrappers with $dynamicAnchor) parses successfully, but still produces unknown[] types — the $dynamicRef is not resolved to concrete types.

Root Cause

The failure occurs in swagger-parser (v2.1.41), not in openapi-generator's codegen layer. The OAS 3.1 dereferencer (OpenAPIDereferencer31) has two bugs:

1. $id hijacks $ref resolution: When a component schema has $id, the dereferencer resolves #/components/schemas/... refs against the $id URI instead of the document root, causing a crash.
2. $dynamicRef / $dynamicAnchor not preserved: These fields are deserialized but lost during the dereference cycle. $defs is stored as raw extensions and not traversed.

A fix PR is open: swagger-api/swagger-parser#2332

Expected Behavior

After the swagger-parser fix is merged and openapi-generator updates its dependency:

1. Specs with $dynamicRef / $dynamicAnchor should parse without errors.
2. The codegen layer should then be updated to preserve $dynamicRef semantics — resolving dynamic refs to concrete types instead of unknown[] / any.

Blocking Dependency

• fix(parser-v3): preserve $dynamicRef/$dynamicAnchor and fix $id scope leak in OAS 3.1 dereferencer swagger-api/swagger-parser#2332 — fixes $id/$ref interaction and preserves $dynamicRef/$dynamicAnchor through parsing

Once swagger-parser merges this fix, openapi-generator will need to:

1. Bump the swagger-parser dependency version
2. Add codegen-level changes to resolve $dynamicRef to concrete schema types during type emission

Compatibility Evidence

A cross-generator compatibility matrix is tracked at:
https://github.com/aqeelat/openapi-dynamicref-adoption-tracker

Related: #13087 (closed without implementation)

---

This issue was drafted with assistance from AI tooling. The submitter is responsible for reviewing and validating the contents before submission.