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

Open
#5,190 0 comments 0 reactions 0 assignees View on GitHub

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.