Skip to content

fix(index): resolve plain-name $anchor fragments - #710

Open
Tjmstudios wants to merge 2 commits into
pb33f:mainfrom
Tjmstudios:schema-anchor
Open

Tjmstudios wants to merge 2 commits into
pb33f:mainfrom
Tjmstudios:schema-anchor

Conversation

@Tjmstudios

Copy link
Copy Markdown
Contributor

Summary

A $ref to a plain-name fragment such as #foo fails to resolve, so the document doesn't build. This registers $anchor values and resolves those fragments against them.

Problem

Name:
  $anchor: name
  type: string
Pet:
  type: object
  properties:
    name: {$ref: '#name'}
component `#name` does not exist in the specification
cannot resolve reference `#name`, it's missing: $.['#name']

2020-12 defines #name as the schema with $anchor: name in the same resource. A resource is the nearest $id, or the document. Only $id was registered, so #name, #bar inside an $id resource, and https://example.com/r#bar all fail.

Changes

  • handleExtractRefsKey registers $anchor next to $id. The entry is keyed by <base URI>#<name>, where the base is the enclosing $id or the document path. Names that don't match ^[A-Za-z_][-A-Za-z0-9._]*$ and anchors in example payloads are skipped. When a name is declared twice, the first one wins, same as $id.
  • The rolodex aggregates anchors across indexes, as it does for $id (RegisterIdsFromIndex).
  • ResolveRefViaSchemaId looks up a plain-name fragment as an anchor before trying $id. This covers FindComponent, SearchIndexForReference and extraction. The resolved ref is named after the schema it lands on (Name), as a pointer ref is.
  • extractReferenceAt keys a #name ref by its resource (<base URI>#name). The same text in two $id resources names two schemas, so keying by the raw value dropped the second ref and let a document anchor shadow a scoped one.
  • SearchIndexForReferenceByReferenceWithContext caches #name under the resource it was resolved in, for the same reason.
  • buildRelativeLookupDefinitions resolves #name against the parent's document, so #name inside pet.yaml finds pet.yaml's anchor and not one in the root.

Not covered: a cross-file other.yaml#name. The rolodex splits on #/ to open files, so the fragment stays attached to the file name. Fixing that is a separate change.

libopenapi-validator still fails an anchor referenced from inside its $id resource with duplicate anchor: RenderInline copies the $anchor into the inlined copy. $id already fails the same way on main (duplicate id).

Tests

  • New: index/schema_anchor_test.go and TestDocument_BuildV3Model_SchemaAnchorRefs in document_test.go. All fail on main, except the subtests that check what must not resolve (an anchor outside its resource, an invalid name, an example payload, an undeclared name) and TestRegisterSchemaAnchorAt_Skips.
  • Extended: the Release tests in index/index_model_test.go and index/rolodex_test.go also check that the new registries are cleared.

go test ./... passes.

A $ref such as "#foo" never resolved: only $id was registered, so the
index reported the component as missing and the document failed to
build. That covers "#foo", "#bar" inside an $id resource and
"https://example.com/r#bar".

Register $anchor during extraction, keyed by the enclosing $id or the
document path, with the same validity, example-payload and first-wins
rules as $id. The rolodex aggregates the anchors like it does $id.
ResolveRefViaSchemaId tries a plain-name fragment as an anchor first.

The same "#foo" text names different schemas in different resources,
so extracted refs and the search cache key it by resource rather than
by the raw value. The resolver resolves "#foo" against the parent's
document, so an anchor ref inside an external file finds that file's
anchor.

Cross-file "other.yaml#foo" is not covered; the rolodex still opens
files by splitting on "#/".
@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 (b56d5f8).

Additional details and impacted files
@@            Coverage Diff             @@
##              main      #710    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files          315       317     +2     
  Lines        39758     39902   +144     
==========================================
+ Hits         39758     39902   +144     
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.

Comment thread index/schema_anchor.go Outdated
// registerSchemaAnchorAt records an $anchor under the base URI of the schema resource
// that declares it: the nearest $id, or the document itself.
func (index *SpecIndex) registerSchemaAnchorAt(node *yaml.Node, keyIndex int, seenPath []string, baseUri string) {
if underOpenAPIExamplePath(seenPath) || len(node.Content) <= keyIndex+1 {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Register anchors only at schema locations. A default payload containing {$anchor: selected, type: integer} claimed the name before a string schema declared $anchor: selected. BuildV3Model() succeeded, and a property referencing #selected acquired type integer. Please restrict registration to schema nodes and cover a default payload that precedes the real declaration.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in b56d5f8. Anchors under default, const, enum, example(s), Link parameters/requestBody and x- extensions (including x- on Responses) are skipped now. Inside an $id resource the path is checked from the resource root. A property/component/response actually named default or x-foo still registers.

Added TestDocument_BuildV3Model_SchemaAnchorAfterDefaultPayload with your example. #selected resolves to the string schema now, it was integer before.

Comment thread index/schema_anchor.go Outdated

definitionPath := "#"
if len(seenPath) > 0 {
definitionPath = "#/" + strings.Join(seenPath, "/")

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Include the array index in the target pointer. I put distinct anchors on two adjacent prefixItems entries and referenced both. Each resolved to its own node, but both reported #/components/schemas/Tuple/prefixItems, so GetMappedReferences() retained only one target. Please carry the sequence index into the pointer and check that the mapped targets end in /0 and /1.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in b56d5f8. The existing walk builds the full pointer now, indices included and ~// escaped. TestDocument_BuildV3Model_SchemaAnchorRefs checks GetMappedReferences() has both .../Tuple/prefixItems/0 and .../prefixItems/1, and TestBundleBytesComposed_AnchorRefsIntoPrefixItems covers bundling. Note SchemaIdEntry.DefinitionPath has indices now too.

Comment thread index/schema_anchor.go Outdated
if baseUri == "" {
baseUri = index.specAbsolutePath
}
key := baseUri + fragment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Decode the URI fragment before anchor lookup. With $anchor: name, BuildV3Model() reports a missing component for $ref: '#na%6De'. The registry stores #name, but this lookup uses the encoded spelling. Please decode the fragment once, preserve the resource URI, and cover the encoded spelling in a document-build test.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in b56d5f8. schemaAnchorFragmentName decodes the fragment once with url.PathUnescape. Lookup is base URI + #name, ref text is left as written. #%2Ffoo still counts as a JSON pointer. TestDocument_BuildV3Model_SchemaAnchorRefs builds #f%6Fo, #b%61r and https://example.com/r#b%61r.

An $anchor inside a default, enum, const or example payload, a Link's
parameters or requestBody, or a specification extension registered as
a declaration, so a payload earlier in the document took the name from
the schema declared after it. Skip an $anchor whose path runs through
data, judged from the root of its enclosing $id resource, or from the
document root outside any $id. $id keeps its existing rule.

The definition path of an $anchor or $id came from the walk's own path,
which has no sequence indices and drops some keys, so a ref into
prefixItems pointed at the array. Build the JSON pointer during the
extract-refs walk instead, with every key and index, writing "~" as
"~0" and "/" as "~1".

Decode a fragment once with url.PathUnescape before matching the anchor
name, so "#f%6Fo" names foo and "#%2Ffoo" stays a JSON pointer. An
"$anchor" or "$id" entry in a sequence such as required is no longer
read as a key.
@Tjmstudios

Copy link
Copy Markdown
Contributor Author

Thanks! All three are fixed in b56d5f8, tests are linked in each thread.

Also in that commit:

  • $anchor/$id as an entry in a list (e.g. required: [$anchor, kind]) no longer registers the next entry as an anchor/id. Same bug existed for $id on main, so I fixed both.
  • DefinitionPath includes sequence indices

Not handled here, can do a follow-up if you want:

  • an $id inside a default can still shadow a real one ($id still only skips examples)
  • cross-file anchor refs like other.yaml#foo

This overlaps a bit with #708, which does the same thing for $ref inside enum/const/default/examples. They don't depend on each other, but both add a similar path check (underSchemaDataPath here, underSchemaInstanceValuePath there). I'll merge them into one helper when I rebase whichever goes in second. Only conflict is tests next to each other 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.

2 participants