Skip to content

False positive "ExampleElement value and externalValue fields are mutually exclusive" when Example Object sits inside an externally referenced Path Item Object #5190

Description

@maruthang

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions