Skip to content

fix(index): treat $ref inside schema instance values as data - #708

Open
Tjmstudios wants to merge 1 commit into
pb33f:mainfrom
Tjmstudios:data-position-refs
Open

Tjmstudios wants to merge 1 commit into
pb33f:mainfrom
Tjmstudios:data-position-refs

Conversation

@Tjmstudios

@Tjmstudios Tjmstudios commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A $ref key inside a schema's enum, const, default or examples array is instance data, not a reference. The index and resolver treated it as a reference, so documents that carry such values failed to build.

Also, when ExcludeExtensionRefs is set, the resolver now skips x- extensions, as the index already does.

Problem

openapi: 3.1.0
info: {title: Instance values, version: "1"}
paths: {}
components:
  schemas:
    Data:
      type: object
      enum:
        - {$ref: '#/nope'}
      const: {$ref: 'gone.yaml#/x'}
      default: {$ref: '#/components/schemas/Target'}
      examples:
        - {$ref: '#/nope'}
    Target:
      type: string

On main, BuildV3Model fails with:

component `#/nope` does not exist in the specification
component `#/x` does not exist in the specification
cannot resolve reference `#/nope`, it's missing: $.nope [9:12]
cannot resolve reference `gone.yaml#/x`, it's missing: $.x [10:15]
cannot resolve reference `#/nope`, it's missing: $.nope [13:12]

None of those are references. In JSON Schema 2020-12, enum, const, default and examples hold instance values, and $ref is only a keyword inside a schema. OpenAPI 3.2 uses the same dialect. The index walk does not depend on the version, so enum and default hit the same errors in OpenAPI 3.0, whose Schema Object also treats them as values.

With ExcludeExtensionRefs: true, the index does not extract references under x- keys, but the resolver's relative walk still followed them and reported errors for them.

Fix

  • underSchemaInstanceValuePath recognizes a path inside one of those values. The index walk (walkChildExtractRefs, extractReferenceAt) and the resolver walk (extractRelativesWithState) stop there. This works the same way as the existing example-payload checks.
  • The keyword has to be a field name. isOpenAPIKeywordSegment, factored out of isOpenAPIExampleKeywordSegment, rejects names the document chose. So a property named default, the default response, and an OpenAPI examples map of Example Objects are still walked. examples counts only when it holds an array.
  • extractRelativesWithState skips x- keys when ExcludeExtensionRefs is set. A property named x-name is still a schema and is still walked.

Tests

  • TestUnderSchemaInstanceValuePath and TestIsOpenAPIKeywordSegment_OutOfRange: path classification, including properties, responses and Example Object maps named like the keywords.
  • TestExtractReferenceAt_IgnoresRefsInsideSchemaInstanceValues and TestSpecIndex_ExtractRefs_SchemaInstanceValueRefsIgnored: index extraction.
  • TestResolver_SchemaInstanceValueRefsNotResolved and TestResolver_ExcludeExtensionRefs: resolver walk, with exclusion on and off.
  • TestDocument_BuildV3Model_RefInSchemaInstanceValue: the document above builds, and default and const decode to their literal $ref objects.

Run against main, the document, index and resolver tests above fail with the errors shown in Problem, and the two classification tests do not compile, since they cover new helpers.

go test ./... passes go test -race . ./index ./datamodel/... ./utils passes.

The values of enum, const and default, and the elements of a schema's
examples array, are instance data. An object there with a $ref key is
a value, not a reference. The index extracted it anyway and the
resolver tried to resolve it, so a valid document failed to build with
errors such as "component `#/nope` does not exist in the specification".

Skip those values in the index walk, in extractReferenceAt and in the
resolver's relative walk. A keyword only counts where it is a field
name: a property named "default", a response keyed "default" or an
Example Object map called "examples" is still walked.

The resolver also walked x- extensions when ExcludeExtensionRefs was
set, so it reported references the index had deliberately skipped. It
now skips extension keys too. A property named x-... is still a schema.
@codecov

codecov Bot commented Nov 12, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (88615e4) to head (7eae375).

Additional details and impacted files
@@            Coverage Diff            @@
##              main      #708   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          315       315           
  Lines        39758     39788   +30     
=========================================
+ Hits         39758     39788   +30     
Flag Coverage Δ
unittests 100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@Tjmstudios

Copy link
Copy Markdown
Contributor Author

#710 now overlaps with this one. It applies the same "data, not schema" rule to $anchor registration (an $anchor inside default/enum/const/examples/extensions declares nothing). The two are independent and can merge in either order. Whichever lands second, I'll rebase it and fold the two classifiers into one helper. The only conflict between them is adjacent tests in document_test.go.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant