Repro (surfaced via swagger-api/swagger-ui#10418): index.yaml with paths./test.$ref: test.yaml; test.yaml contains a response example with only externalValue: test.json. Dereferencing fails with ExampleElement value and externalValue fields are mutually exclusive. Inlining test.yaml into index.yaml dereferences fine, so the definition is valid — the $ref triggers the error.
# index.yaml
openapi: 3.1.0
info: {title: 'Bug test', version: 1.0.0}
paths:
/test:
$ref: test.yaml
# test.yaml
post:
responses:
'200':
content:
application/json:
examples:
testExample:
summary: Test example
externalValue: test.json
Expected: dereference succeeds (only externalValue is defined).
Actual: DereferenceError as above.
Root cause: the PathItemElement handler in packages/apidom-reference/src/dereference/strategies/openapi-3-1/visitor.ts dereferences an external fragment with a nested visitor, then link.replaceWiths the merged Path Item and lets the outer visitor descend into the already-dereferenced subtree. The nested pass transcludes externalValue into value while intentionally keeping externalValue (annotating value with ref-origin meta), so the outer pass re-visits an Example that now has both fields and trips the mutual-exclusion check (openapi-3-1/visitor.ts ~L975; same code exists in the 3-0 and 3-2 strategies). swagger-ui surfaces this via the resolve strategies, which delegate to dereference.
Suggested fix: in the ExampleElement handlers, before the mutual-exclusion check, skip elements whose value carries the ref-origin meta (i.e. already transcluded):
if (exampleElement.value?.meta.hasKey('ref-origin')) {
return undefined;
}
Verified against the repro with @swagger-api/apidom-reference@1.11.3 (and that a genuine value + externalValue violation in source still errors). I have this implemented with regression tests on a branch and will open a PR.
Repro (surfaced via swagger-api/swagger-ui#10418):
index.yamlwithpaths./test.$ref: test.yaml;test.yamlcontains a response example with onlyexternalValue: test.json. Dereferencing fails withExampleElement value and externalValue fields are mutually exclusive.Inliningtest.yamlintoindex.yamldereferences fine, so the definition is valid — the$reftriggers the error.Expected: dereference succeeds (only
externalValueis defined).Actual:
DereferenceErroras above.Root cause: the
PathItemElementhandler inpackages/apidom-reference/src/dereference/strategies/openapi-3-1/visitor.tsdereferences an external fragment with a nested visitor, thenlink.replaceWiths the merged Path Item and lets the outer visitor descend into the already-dereferenced subtree. The nested pass transcludesexternalValueintovaluewhile intentionally keepingexternalValue(annotatingvaluewithref-originmeta), so the outer pass re-visits an Example that now has both fields and trips the mutual-exclusion check (openapi-3-1/visitor.ts~L975; same code exists in the 3-0 and 3-2 strategies). swagger-ui surfaces this via the resolve strategies, which delegate to dereference.Suggested fix: in the
ExampleElementhandlers, before the mutual-exclusion check, skip elements whosevaluecarries theref-originmeta (i.e. already transcluded):Verified against the repro with
@swagger-api/apidom-reference@1.11.3(and that a genuinevalue+externalValueviolation in source still errors). I have this implemented with regression tests on a branch and will open a PR.