v3.2.0 regression: self-referential `Reference.referredSemanticId` in Part1 breaks Swagger UI rendering across all SSPs (blocks #668)

[mdanish98]

Summary

Every v3.2.0 Service Specification renders a wall of Resolver error: Cannot read properties of undefined (reading '1') messages in Swagger UI as soon as any endpoint is expanded (see #668). The root cause is a regression in the v3.2.0 spec, not a viewer bug: the referredSemanticId self-reference was reintroduced into the Reference schema in Part1-MetaModel-Schemas/openapi.yaml, after having been deliberately removed in v3.0.3 and kept absent through five subsequent minor releases.

Issue #668 asks for the visible error wall to be fixed. This issue tracks the underlying spec change that #668 depends on.

Reproduction

1. Open the docs site at docs/swagger-ui.html?version=v3.2.0&url=../AssetAdministrationShellRegistryServiceSpecification/V3.2_SSP-001.yaml (or any other v3.2.0 SSP).
2. Click any endpoint, e.g. GET /shell-descriptors.
3. Observe a red "Errors" panel with ~20 repetitions of Resolver error: Cannot read properties of undefined (reading '1').

The endpoint content underneath still renders, but the panel is alarming and repeats for every operation the user opens.

What is actually going wrong

Part1-MetaModel-Schemas/openapi.yaml at v3.2.0 defines:

Reference:
  type: object
  required: [type, keys]
  properties:
    type:
      $ref: "#/components/schemas/ReferenceTypes"
    referredSemanticId:
      $ref: "#/components/schemas/Reference"     # ← self-referential
    keys:
      type: array
      minItems: 1
      items:
        $ref: "#/components/schemas/Key"

Every SSP transitively pulls in Reference through Part2-API-Schemas/openapi.yaml (via AssetAdministrationShellDescriptor, SubmodelDescriptor, SpecificAssetId, Extension, AdministrativeInformation.embeddedDataSpecifications, etc.).

When swagger-client (the resolver behind Swagger UI) inlines Reference from Part1 into an SSP document during subtree resolution, it evaluates the local pointer #/components/schemas/Reference against the host document (the SSP), which does not contain components/schemas/Reference. Resolution fails with JSONRefError: Could not resolve pointer: /components/schemas/Reference does not exist in document, and Swagger UI's JSON-Patch pipeline then surfaces that as the generic Cannot read properties of undefined (reading '1') message — once per failed sub-ref (13–22 per operation, depending on which schemas that operation touches).

The specifications themselves are valid OpenAPI 3.0.3 (@apidevtools/swagger-cli validate reports valid) and Redoc renders them without any warnings. But Swagger UI is the primary interactive viewer on the docs site, and it has a long-standing, recurring bug with cross-document recursive $refs that we cannot fix by upgrading — the same failure reproduces on swagger-ui-dist@5.32.5 and older versions all the way down to 4.19.1.

Upstream Swagger UI history confirms this is a well-known class of bugs, not a one-off:

• Swagger UI throws error if the api spec has circular references swagger-api/swagger-ui#7052 (identical stack trace, still reported on 5.10.3+)
• v3 - Resolver error - Cannot read property '1' of undefined swagger-api/swagger-ui#3366 (canonical thread — closed and reopened repeatedly)
• Circular reference in schema leads to Could not resolve reference: undefined undefined swagger-api/swagger-ui#5726 (reproducer is a recursive Person.parent, exactly our Reference.referredSemanticId shape)
• fix(resolve): fix infinite recursions and cycle detection in OpenAPI 3.1.0 resolution swagger-api/swagger-ui#9837 (2024 maintainer follow-up: recursion cycle detection still needs work)
• Recursive external JSON Schema refs can overflow resolveSubtree swagger-api/swagger-client#4221 / PR #4222 (2024 fix for recursive external JSON Schema refs — not yet in swagger-ui-dist)

Waiting on an upstream fix is not a viable path.

Version history — this looks like a regression

I checked Reference.referredSemanticId across every released version:

Tag	referredSemanticId on Reference	Endpoint expand in Swagger UI
v3.0	(property does not exist)	✅ clean
v3.0.1	(property does not exist)	✅ clean
v3.0.2	$ref → #/components/schemas/Reference	❌ same error wall
v3.0.3	(property does not exist)	✅ clean
v3.0.4	(property does not exist)	✅ clean (verified)
v3.1.0	(property does not exist)	✅ clean
v3.1.1	(property does not exist)	✅ clean
v3.1.2	(property does not exist)	✅ clean (verified)
v3.1.3	(property does not exist)	✅ clean
v3.2.0	$ref → #/components/schemas/Reference	❌ error wall (verified)

I verified v3.0.4, v3.1.2, and v3.2.0 end-to-end in a headless browser using the exact same viewer (docs/swagger-ui.html, swagger-ui-dist@5.32.5, no code changes). Only the spec version differs. v3.0.4 and v3.1.2 render endpoints with zero errors; v3.2.0 produces the wall reported in #668.

The property was removed between v3.0.2 and v3.0.3 (presumably in response to exactly this rendering problem) and stayed absent through five subsequent minor releases. It was reintroduced in v3.2.0 by PR #641, which resolved #521 ("Inconsistency in AAS Specification: ReferenceValue valueOnly serialization loses referredSemanticId in OpenAPI Spec"). PR #641 replaced the previous ReferenceValue schema with direct references to Part1's Reference — a semantically correct change per IDTA-01001, but it re-exposed the self-referential shape that had been carefully avoided since v3.0.3.

The problem is not that #641 was wrong — it fixed a real serialization gap. The problem is that reintroducing the direct Reference reference brought back the self-recursive referredSemanticId: $ref: '#/components/schemas/Reference' shape without a compensating change to keep the docs viewer working.

Impact

Every v3.2.0 SSP is affected — verified via transitive dependency: all nine service specifications (AasxFileServer, AssetAdministrationShellRegistry, AssetAdministrationShellRepository, AssetAdministrationShell, ConceptDescriptionRepository, Discovery, SubmodelRegistry, SubmodelRepository, Submodel) $ref Part2-API-Schemas/openapi.yaml, which $refs Part1-MetaModel-Schemas/openapi.yaml's Reference.

The docs site currently ships a hardcoded warning for SSP-004 ("Query Profile") acknowledging the problem, but the same root cause hits every SSP, not just Query Profile. That warning was correct in spirit but wrong in scope — this affects the entire v3.2.0 release.

Proposed fix

Change Reference in Part1-MetaModel-Schemas/openapi.yaml so it no longer contains a self-referential $ref, while preserving the semantic intent of referredSemanticId (the transitive semantic reference chain that PR #641 needed to expose).

Three concrete options, ordered from most conservative to most invasive:

1. Bounded-depth inline expansion. Define Reference and a companion ReferenceParent (identical shape minus referredSemanticId). Have Reference.referredSemanticId reference ReferenceParent. This preserves one level of the chain — the level IDTA-01001 valueOnly serialization actually needs — and terminates cleanly. No self-recursion, no rendering issue, and JSON round-tripping remains lossless for the depth that the specification requires.
2. Remove referredSemanticId from Reference entirely and restore the v3.1.x shape. This reverts the semantic gain from PR 521: Replace ReferenceValue with Reference to include referredSemanticId #641 and would reopen Inconsistency in AAS Specification: ReferenceValue valueOnly serialization loses referredSemanticId in OpenAPI Spec #521, so it is only viable as a short-term measure while option 1 is being reviewed.
3. Keep the self-reference but mark it explicitly. Add x-recursion: bounded or an equivalent extension and document it. This does not fix the docs viewer, so it is only useful in combination with a viewer-side filter (which Resolver Error for swagger documentation #668 would need instead).

Option 1 is my recommendation because it addresses both #521 and #668 without either regressing behavior or requiring a viewer-side workaround.

What this issue tracks

• Confirm the regression analysis above with @sebbader-sap (author of PR 521: Replace ReferenceValue with Reference to include referredSemanticId #641) and @BirgitBoss.
• Pick between options 1 / 2 / 3.
• Update Part1-MetaModel-Schemas/openapi.yaml and re-run the docs viewer against every SSP to confirm the error wall is gone with the untouched original viewer.
• Verify PR 521: Replace ReferenceValue with Reference to include referredSemanticId #641's original motivation (referredSemanticId round-tripping in valueOnly serialization) still holds after the change.
• Resolver Error for swagger documentation #668 depends on this issue — once the spec is fixed here, Resolver Error for swagger documentation #668's user-visible symptom is gone without needing any docs-viewer-layer workaround.

Verification method used

• swagger-cli validate on V3.2_SSP-001.yaml — reports valid.
• Redoc rendering of the same spec — clean, no warnings.
• Headless-Chrome test of docs/swagger-ui.html against v3.0.4, v3.1.2, and v3.2.0 — only v3.2.0 produces the error wall.
• Direct inspection of the resolver by calling window.ui.getSystem().fn.resolve() on the loaded spec — returned the underlying JSONRefError: Could not resolve pointer: /components/schemas/Reference does not exist in document messages with full fullPath traces pointing at every .../referredSemanticId/$ref reachable from each operation.

Happy to share the exact reproduction scripts and per-version screenshots on request.

Depends on / blocks: #668
Related: #521, #641

[BirgitBoss]

redundant to #668 but explains also the why