swagger-api / swagger-api/apidom
False positive "ExampleElement value and externalValue fields are mutually exclusive" when Example Object sits inside an externally referenced Path Item Object
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 100
- Forks
- 26
- Avg merge
- 14h 36m
- Merged PRs (30d)
- 22
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in packages/apidom-reference/src/dereference/strategies/openapi-3-1/visitor.ts around the PathItemElement and ExampleElement handlers, then compare the corresponding 3-0 and 3-2 strategies. Run or inspect the regression tests mentioned in the issue and verify that the external reference succeeds while a genuine value plus externalValue violation still errors.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100