From 535cf2419ad317558f8550171c8a0227332c7723 Mon Sep 17 00:00:00 2001 From: Thomas Date: Fri, 13 Nov 2026 01:28:10 +1100 Subject: [PATCH 1/2] fix(index): resolve plain-name $anchor fragments 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 "#/". --- document_test.go | 51 ++++++ index/extract_refs_ref.go | 13 +- index/extract_refs_walk.go | 4 + index/index_model.go | 4 +- index/index_model_test.go | 2 + index/resolver_relatives.go | 8 + index/rolodex.go | 27 ++- index/rolodex_test.go | 2 + index/schema_anchor.go | 91 ++++++++++ index/schema_anchor_test.go | 338 ++++++++++++++++++++++++++++++++++++ index/schema_id_resolve.go | 9 +- index/search_index.go | 29 ++-- 12 files changed, 562 insertions(+), 16 deletions(-) create mode 100644 index/schema_anchor.go create mode 100644 index/schema_anchor_test.go diff --git a/document_test.go b/document_test.go index f5d7b9f2..02b4c9c7 100644 --- a/document_test.go +++ b/document_test.go @@ -2600,3 +2600,54 @@ func TestDocument_BuildV3Model_NoVersionNode(t *testing.T) { require.Error(t, buildErr) assert.Contains(t, buildErr.Error(), "no openapi version/tag found") } + +// A plain-name fragment such as "#foo" names an $anchor in the schema resource +// it appears in, not a JSON Pointer. +func TestDocument_BuildV3Model_SchemaAnchorRefs(t *testing.T) { + spec := `openapi: 3.1.0 +info: {title: anchors, version: "1"} +paths: {} +components: + schemas: + A: + $anchor: foo + type: string + B: + type: object + properties: + local: {$ref: '#foo'} + R: + $id: https://example.com/r + type: object + $defs: + X: {$anchor: bar, type: integer} + properties: + scoped: {$ref: '#bar'} + absolute: {$ref: 'https://example.com/r#bar'} + U: + type: object + properties: + outside: {$ref: 'https://example.com/r#bar'} +` + doc, err := NewDocument([]byte(spec)) + require.NoError(t, err) + m, err := doc.BuildV3Model() + require.NoError(t, err) + assert.Empty(t, m.Index.GetReferenceIndexErrors()) + + schemas := m.Model.Components.Schemas + for _, tc := range []struct{ schema, property, kind string }{ + {"B", "local", "string"}, + {"R", "scoped", "integer"}, + {"R", "absolute", "integer"}, + {"U", "outside", "integer"}, + } { + t.Run(tc.schema+"."+tc.property, func(t *testing.T) { + prop := schemas.GetOrZero(tc.schema).Schema().Properties.GetOrZero(tc.property) + require.NotNil(t, prop) + s := prop.Schema() + require.NotNil(t, s, prop.GetBuildError()) + assert.Equal(t, []string{tc.kind}, s.Type) + }) + } +} diff --git a/index/extract_refs_ref.go b/index/extract_refs_ref.go index 713e3026..f5680dc7 100644 --- a/index/extract_refs_ref.go +++ b/index/extract_refs_ref.go @@ -66,6 +66,17 @@ func (index *SpecIndex) extractReferenceAt( } fullDefinitionPath, componentName := index.resolveReferenceTarget(value) + refKey := value + if isSchemaAnchorFragment(value) { + // "#foo" names an $anchor in the enclosing resource, so the same text can + // point at different schemas. key it by the resource. + base := index.specAbsolutePath + if scope != nil && scope.BaseUri != "" { + base = scope.BaseUri + } + fullDefinitionPath = base + value + refKey = fullDefinitionPath + } _, path := utils.ConvertComponentIdIntoFriendlyPathSearch(componentName) siblingProps, siblingKeys := extractSiblingRefProperties(node) @@ -107,7 +118,7 @@ func (index *SpecIndex) extractReferenceAt( return nil } - if index.allRefs[value] != nil { + if index.allRefs[refKey] != nil { return nil } diff --git a/index/extract_refs_walk.go b/index/extract_refs_walk.go index 02fd53c9..c2a6e3cb 100644 --- a/index/extract_refs_walk.go +++ b/index/extract_refs_walk.go @@ -154,6 +154,10 @@ func (index *SpecIndex) handleExtractRefsKey( index.registerSchemaIDAt(node, keyIndex, state.seenPath, state.parentBaseURI) } + if keyNode.Value == "$anchor" { + index.registerSchemaAnchorAt(node, keyIndex, state.seenPath, state.scope.BaseUri) + } + if keyNode.Value != "$ref" && keyNode.Value != "$id" && keyNode.Value != "" { action := index.extractNodeMetadata(node, parent, state.seenPath, keyIndex) state.lastAppended = action.appendSegment diff --git a/index/index_model.go b/index/index_model.go index b0a81c01..b11097e9 100644 --- a/index/index_model.go +++ b/index/index_model.go @@ -441,7 +441,8 @@ type SpecIndex struct { pendingResolve []refMap highModelCache Cache schemaIdRegistry map[string]*SchemaIdEntry // registry of $id declarations for JSON Schema 2020-12 - schemaIdRegistryLock sync.RWMutex // lock for concurrent access to schemaIdRegistry + schemaAnchorRegistry map[string]*SchemaIdEntry // $anchor declarations, keyed by resource base URI + "#" + name + schemaIdRegistryLock sync.RWMutex // lock for concurrent access to schemaIdRegistry and schemaAnchorRegistry } // GetResolver returns the resolver for this index. @@ -635,6 +636,7 @@ func (index *SpecIndex) releaseDerivedState() { index.cache = nil index.highModelCache = nil index.schemaIdRegistry = nil + index.schemaAnchorRegistry = nil index.pendingResolve = nil index.uri = nil index.logger = nil diff --git a/index/index_model_test.go b/index/index_model_test.go index 401b66bf..c5c813b7 100644 --- a/index/index_model_test.go +++ b/index/index_model_test.go @@ -158,6 +158,7 @@ func TestSpecIndex_Release(t *testing.T) { allExternalDocuments: map[string]*Reference{"ext": {}}, externalSpecIndex: map[string]*SpecIndex{"ext": {}}, schemaIdRegistry: map[string]*SchemaIdEntry{"id": {}}, + schemaAnchorRegistry: map[string]*SchemaIdEntry{"#a": {}}, uri: []string{"test"}, globalLinksCount: 2, globalCallbacksCount: 3, @@ -203,6 +204,7 @@ func TestSpecIndex_Release(t *testing.T) { // schema ID registry, uri, logger assert.Nil(t, idx.schemaIdRegistry) + assert.Nil(t, idx.schemaAnchorRegistry) assert.Nil(t, idx.uri) assert.Nil(t, idx.logger) assert.Zero(t, idx.globalLinksCount) diff --git a/index/resolver_relatives.go b/index/resolver_relatives.go index 41f1ea72..c060f332 100644 --- a/index/resolver_relatives.go +++ b/index/resolver_relatives.go @@ -296,6 +296,14 @@ func (resolver *Resolver) buildRelativeLookupDefinitions(ref *Reference, value, fullDef = fmt.Sprintf("%s#/%s", fileDef[0], exp[1]) } } + } else if isSchemaAnchorFragment(value) { + // plain-name fragment (e.g. "#foo") — an $anchor in the parent's document. + baseLocation := ref.FullDefinition + if ref.RemoteLocation != "" { + baseLocation = ref.RemoteLocation + } + fileDef, _ := SplitRefFragment(baseLocation) + fullDef = fileDef + value } else if strings.HasPrefix(value, "http") { // No fragment, absolute HTTP URL — use as-is. fullDef = value diff --git a/index/rolodex.go b/index/rolodex.go index 46249e01..6477cc73 100644 --- a/index/rolodex.go +++ b/index/rolodex.go @@ -89,6 +89,7 @@ type Rolodex struct { logger *slog.Logger id string // unique ID for the rolodex, can be used to identify it in logs or other contexts. globalSchemaIdRegistry map[string]*SchemaIdEntry + globalSchemaAnchorRegistry map[string]*SchemaIdEntry schemaIdRegistryLock sync.RWMutex } @@ -119,6 +120,7 @@ func (r *Rolodex) Release() { r.infiniteCircularReferences = nil r.ignoredCircularReferences = nil r.globalSchemaIdRegistry = nil + r.globalSchemaAnchorRegistry = nil r.indexConfig = nil r.indexingDuration = 0 r.indexed = false @@ -1116,7 +1118,7 @@ func (r *Rolodex) GetAllGlobalSchemaIds() map[string]*SchemaIdEntry { return copySchemaIdRegistry(r.globalSchemaIdRegistry) } -// RegisterIdsFromIndex aggregates all $id registrations from an index into the global registry. +// RegisterIdsFromIndex aggregates all $id and $anchor registrations from an index into the global registry. // Called after each index is built to populate the Rolodex global registry. func (r *Rolodex) RegisterIdsFromIndex(idx *SpecIndex) { if r == nil || idx == nil { @@ -1127,4 +1129,27 @@ func (r *Rolodex) RegisterIdsFromIndex(idx *SpecIndex) { for _, entry := range entries { _ = r.RegisterGlobalSchemaId(entry) } + + idx.schemaIdRegistryLock.RLock() + anchors := copySchemaIdRegistry(idx.schemaAnchorRegistry) + idx.schemaIdRegistryLock.RUnlock() + if len(anchors) == 0 { + return + } + r.schemaIdRegistryLock.Lock() + defer r.schemaIdRegistryLock.Unlock() + if r.globalSchemaAnchorRegistry == nil { + r.globalSchemaAnchorRegistry = make(map[string]*SchemaIdEntry) + } + for key, entry := range anchors { + if _, ok := r.globalSchemaAnchorRegistry[key]; !ok { + r.globalSchemaAnchorRegistry[key] = entry + } + } +} + +func (r *Rolodex) lookupSchemaAnchor(uri string) *SchemaIdEntry { + r.schemaIdRegistryLock.RLock() + defer r.schemaIdRegistryLock.RUnlock() + return r.globalSchemaAnchorRegistry[uri] } diff --git a/index/rolodex_test.go b/index/rolodex_test.go index fc4ccbc0..a57556ad 100644 --- a/index/rolodex_test.go +++ b/index/rolodex_test.go @@ -2940,6 +2940,7 @@ func TestRolodex_Release(t *testing.T) { rolodex.debouncedSafeCircRefs = []*CircularReferenceResult{{}} rolodex.debouncedIgnoredCircRefs = []*CircularReferenceResult{{}} rolodex.globalSchemaIdRegistry = map[string]*SchemaIdEntry{"test": {}} + rolodex.globalSchemaAnchorRegistry = map[string]*SchemaIdEntry{"#a": {}} rolodex.indexed = true rolodex.built = true rolodex.manualBuilt = true @@ -2964,6 +2965,7 @@ func TestRolodex_Release(t *testing.T) { assert.Nil(t, rolodex.debouncedSafeCircRefs) assert.Nil(t, rolodex.debouncedIgnoredCircRefs) assert.Nil(t, rolodex.globalSchemaIdRegistry) + assert.Nil(t, rolodex.globalSchemaAnchorRegistry) assert.Nil(t, rolodex.indexConfig) assert.Zero(t, rolodex.indexingDuration) assert.False(t, rolodex.indexed) diff --git a/index/schema_anchor.go b/index/schema_anchor.go new file mode 100644 index 00000000..0de495c6 --- /dev/null +++ b/index/schema_anchor.go @@ -0,0 +1,91 @@ +// Copyright 2023-2026 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package index + +import ( + "regexp" + "strings" + + "github.com/pb33f/go-yaml" + "github.com/pb33f/libopenapi/utils" +) + +// schemaAnchorName is the plain-name form JSON Schema 2020-12 allows for $anchor. +var schemaAnchorName = regexp.MustCompile(`^[A-Za-z_][-A-Za-z0-9._]*$`) + +// isSchemaAnchorFragment reports whether a fragment such as "#foo" names an $anchor +// rather than a JSON pointer. +func isSchemaAnchorFragment(fragment string) bool { + return len(fragment) > 1 && fragment[0] == '#' && fragment[1] != '/' +} + +// 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 { + return + } + anchorNode := node.Content[keyIndex+1] + if !utils.IsNodeStringValue(anchorNode) || !schemaAnchorName.MatchString(anchorNode.Value) { + return + } + + definitionPath := "#" + if len(seenPath) > 0 { + definitionPath = "#/" + strings.Join(seenPath, "/") + } + entry := &SchemaIdEntry{ + Id: anchorNode.Value, + ResolvedUri: baseUri + "#" + anchorNode.Value, + SchemaNode: node, + ParentId: baseUri, + Index: index, + DefinitionPath: definitionPath, + Line: anchorNode.Line, + Column: anchorNode.Column, + } + + index.schemaIdRegistryLock.Lock() + defer index.schemaIdRegistryLock.Unlock() + if index.schemaAnchorRegistry == nil { + index.schemaAnchorRegistry = make(map[string]*SchemaIdEntry) + } + if _, ok := index.schemaAnchorRegistry[entry.ResolvedUri]; !ok { + index.schemaAnchorRegistry[entry.ResolvedUri] = entry + } +} + +func (index *SpecIndex) getSchemaAnchor(uri string) *SchemaIdEntry { + index.schemaIdRegistryLock.RLock() + defer index.schemaIdRegistryLock.RUnlock() + return index.schemaAnchorRegistry[uri] +} + +// resolveRefViaSchemaAnchor resolves a ref whose fragment is a plain-name $anchor. A ref +// with no base URI, such as "#foo", is looked up in this document. +func (index *SpecIndex) resolveRefViaSchemaAnchor(ref, baseUri, fragment string) *Reference { + if baseUri == "" { + baseUri = index.specAbsolutePath + } + key := baseUri + fragment + entry := index.getSchemaAnchor(key) + if entry == nil && index.rolodex != nil { + entry = index.rolodex.lookupSchemaAnchor(key) + } + if entry == nil { + return nil + } + + resolved := buildSchemaIdResolvedReference(index, entry, ref, baseUri, "") + // name it after the schema it lands on, as a pointer ref would be. + resolved.Name = entry.Id + if i := strings.LastIndexByte(entry.DefinitionPath, '/'); i >= 0 && i+1 < len(entry.DefinitionPath) { + resolved.Name = entry.DefinitionPath[i+1:] + } + if entry.Index != nil && entry.ParentId == entry.Index.GetSpecAbsolutePath() { + // the anchor's resource is the document, not an $id. + resolved.SchemaIdBase = "" + } + return resolved +} diff --git a/index/schema_anchor_test.go b/index/schema_anchor_test.go new file mode 100644 index 00000000..458854eb --- /dev/null +++ b/index/schema_anchor_test.go @@ -0,0 +1,338 @@ +// Copyright 2023-2026 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package index + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/pb33f/go-yaml" + "github.com/pb33f/testify/assert" + "github.com/pb33f/testify/require" +) + +const schemaAnchorSpec = `openapi: 3.1.0 +info: {title: anchors, version: '1'} +paths: {} +components: + schemas: + A: + $anchor: foo + type: string + First: + $anchor: dup + type: boolean + Second: + $anchor: dup + type: number + Invalid: + $anchor: 1bad + type: string + Example: + type: object + example: + $anchor: payload + R: + $id: https://example.com/r + type: object + $defs: + X: {$anchor: bar, type: integer} + properties: + scoped: {$ref: '#bar'} + absolute: {$ref: 'https://example.com/r#bar'} + Self: + $id: https://example.com/self + $anchor: self + type: array + B: + type: object + properties: + local: {$ref: '#foo'} + outside: {$ref: 'https://example.com/r#bar'} +` + +func schemaNodeType(node *yaml.Node) string { + for i := 0; node != nil && i+1 < len(node.Content); i += 2 { + if node.Content[i].Value == "type" { + return node.Content[i+1].Value + } + } + return "" +} + +func TestSchemaAnchorResolution(t *testing.T) { + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(schemaAnchorSpec), &root)) + idx := NewSpecIndexWithConfig(&root, CreateClosedAPIIndexConfig()) + + for _, tc := range []struct{ name, ref, kind string }{ + {"document anchor", "#foo", "string"}, + {"anchor in $id resource", "https://example.com/r#bar", "integer"}, + {"anchor beside $id", "https://example.com/self#self", "array"}, + {"first duplicate wins", "#dup", "boolean"}, + {"scoped anchor outside its resource", "#bar", ""}, + {"document anchor under an $id", "https://example.com/r#foo", ""}, + {"invalid name", "#1bad", ""}, + {"example payload", "#payload", ""}, + {"undeclared", "#missing", ""}, + } { + t.Run(tc.name, func(t *testing.T) { + for _, lookup := range []struct { + name string + call func() *Reference + }{ + {"registry", func() *Reference { return idx.ResolveRefViaSchemaId(tc.ref) }}, + {"component", func() *Reference { return idx.FindComponent(context.Background(), tc.ref) }}, + {"search", func() *Reference { + ref, _ := idx.SearchIndexForReference(tc.ref) + return ref + }}, + } { + t.Run(lookup.name, func(t *testing.T) { + ref := lookup.call() + if tc.kind == "" { + assert.Nil(t, ref) + return + } + require.NotNil(t, ref) + assert.Equal(t, tc.kind, schemaNodeType(ref.Node)) + }) + } + }) + } +} + +func TestSchemaAnchorResolvedReference(t *testing.T) { + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(schemaAnchorSpec), &root)) + idx := NewSpecIndexWithConfig(&root, CreateClosedAPIIndexConfig()) + + ref := idx.ResolveRefViaSchemaId("#foo") + require.NotNil(t, ref) + assert.Equal(t, "A", ref.Name) + assert.Equal(t, "#/components/schemas/A", ref.Definition) + assert.Equal(t, "#foo", ref.RawRef) + assert.Empty(t, ref.SchemaIdBase) + + // an anchor inside an $id resource keeps that resource as the base for its own refs. + ref = idx.ResolveRefViaSchemaId("https://example.com/r#bar") + require.NotNil(t, ref) + assert.Equal(t, "X", ref.Name) + assert.Equal(t, "#/components/schemas/R/$defs/X", ref.Definition) + assert.Equal(t, "https://example.com/r", ref.SchemaIdBase) +} + +func TestSchemaAnchorExtractedRefs(t *testing.T) { + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(schemaAnchorSpec), &root)) + idx := NewSpecIndexWithConfig(&root, CreateClosedAPIIndexConfig()) + + assert.Empty(t, idx.GetReferenceIndexErrors()) + mapped := idx.GetMappedReferences() + require.Contains(t, mapped, "#/components/schemas/A") + assert.Equal(t, "#foo", mapped["#/components/schemas/A"].RawRef) + require.Contains(t, mapped, "#/components/schemas/R/$defs/X") + assert.Equal(t, "integer", schemaNodeType(mapped["#/components/schemas/R/$defs/X"].Node)) +} + +func TestSchemaAnchorResolver(t *testing.T) { + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(schemaAnchorSpec), &root)) + idx := NewSpecIndexWithConfig(&root, CreateClosedAPIIndexConfig()) + + resolver := NewResolver(idx) + assert.Empty(t, resolver.Resolve()) + assert.Empty(t, resolver.GetResolvingErrors()) +} + +func TestSchemaAnchorAcrossIndexes(t *testing.T) { + const shared = `components: + schemas: + S: + $id: https://example.com/shared + $defs: + Name: {$anchor: name, type: string} +` + const local = `openapi: 3.1.0 +info: {title: anchors, version: '1'} +paths: {} +components: + schemas: + Local: {$anchor: name, type: integer} +` + cfg := CreateClosedAPIIndexConfig() + rolodex := NewRolodex(cfg) + + var sharedRoot, localRoot yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(shared), &sharedRoot)) + require.NoError(t, yaml.Unmarshal([]byte(local), &localRoot)) + + sharedCfg := CreateClosedAPIIndexConfig() + sharedCfg.SpecAbsolutePath = "/specs/shared.yaml" + sharedIdx := NewSpecIndexWithConfig(&sharedRoot, sharedCfg) + rolodex.AddExternalIndex(sharedIdx, "/specs/shared.yaml") + + localCfg := CreateClosedAPIIndexConfig() + localCfg.SpecAbsolutePath = "/specs/root.yaml" + localIdx := NewSpecIndexWithConfig(&localRoot, localCfg) + localIdx.rolodex = rolodex + + ref := localIdx.ResolveRefViaSchemaId("https://example.com/shared#name") + require.NotNil(t, ref) + assert.Equal(t, "string", schemaNodeType(ref.Node)) + assert.True(t, ref.IsRemote) + assert.Same(t, sharedIdx, ref.Index) + + // a document anchor of the same name stays local. + ref = localIdx.ResolveRefViaSchemaId("#name") + require.NotNil(t, ref) + assert.Equal(t, "integer", schemaNodeType(ref.Node)) + assert.False(t, ref.IsRemote) + + // first registration wins in the global registry too. + var otherRoot yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(strings.Replace(shared, "type: string", "type: integer", 1)), &otherRoot)) + otherCfg := CreateClosedAPIIndexConfig() + otherCfg.SpecAbsolutePath = "/specs/other.yaml" + rolodex.AddExternalIndex(NewSpecIndexWithConfig(&otherRoot, otherCfg), "/specs/other.yaml") + ref = localIdx.ResolveRefViaSchemaId("https://example.com/shared#name") + require.NotNil(t, ref) + assert.Same(t, sharedIdx, ref.Index) +} + +// the same "#bar" in different resources points at different schemas. +func TestSchemaAnchorScopedByResource(t *testing.T) { + const spec = `openapi: 3.1.0 +info: {title: anchors, version: '1'} +paths: {} +components: + schemas: + R1: + $id: https://example.com/r1 + $defs: {X: {$anchor: bar, type: integer}} + properties: {p: {$ref: '#bar'}} + D: {$anchor: bar, type: boolean} + U: + properties: {p: {$ref: '#bar'}} + R2: + $id: https://example.com/r2 + $defs: {X: {$anchor: bar, type: string}} + properties: {p: {$ref: '#bar'}} +` + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(spec), &root)) + cfg := CreateClosedAPIIndexConfig() + cfg.SpecAbsolutePath = "/specs/root.yaml" + idx := NewSpecIndexWithConfig(&root, cfg) + + assert.Empty(t, idx.GetReferenceIndexErrors()) + mapped := idx.GetMappedReferences() + for def, kind := range map[string]string{ + "/specs/root.yaml#/components/schemas/R1/$defs/X": "integer", + "/specs/root.yaml#/components/schemas/D": "boolean", + "/specs/root.yaml#/components/schemas/R2/$defs/X": "string", + } { + require.Contains(t, mapped, def) + assert.Equal(t, kind, schemaNodeType(mapped[def].Node), def) + } + + // repeat lookups must not share a cache entry across resources. + for _, tc := range []struct{ base, kind string }{ + {"https://example.com/r1", "integer"}, + {"https://example.com/r2", "string"}, + {"", "boolean"}, + {"https://example.com/r1", "integer"}, + } { + ref, _, _ := idx.SearchIndexForReferenceByReferenceWithContext(context.Background(), + &Reference{FullDefinition: "#bar", RawRef: "#bar", SchemaIdBase: tc.base}) + require.NotNil(t, ref, tc.base) + assert.Equal(t, tc.kind, schemaNodeType(ref.Node), tc.base) + + ctx := context.Background() + if tc.base != "" { + ctx = WithSchemaIdScope(ctx, NewSchemaIdScope(tc.base)) + } + ref, _, _ = idx.SearchIndexForReferenceWithContext(ctx, "#bar") + require.NotNil(t, ref, tc.base) + assert.Equal(t, tc.kind, schemaNodeType(ref.Node), tc.base) + } +} + +func TestRegisterSchemaAnchorAt_Skips(t *testing.T) { + idx := NewTestSpecIndex().Load().(*SpecIndex) + parse := func(src string) *yaml.Node { + var n yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(src), &n)) + return n.Content[0] + } + + idx.registerSchemaAnchorAt(parse("$anchor: a"), 0, []string{"components", "examples", "Sample", "value"}, "test.yaml") + idx.registerSchemaAnchorAt(parse("$anchor: [a]"), 0, nil, "test.yaml") + idx.registerSchemaAnchorAt(parse("$anchor: 'a b'"), 0, nil, "test.yaml") + truncated := parse("$anchor: a") + truncated.Content = truncated.Content[:1] + idx.registerSchemaAnchorAt(truncated, 0, nil, "test.yaml") + assert.Empty(t, idx.schemaAnchorRegistry) + + idx.registerSchemaAnchorAt(parse("$anchor: a"), 0, nil, "test.yaml") + require.Contains(t, idx.schemaAnchorRegistry, "test.yaml#a") + assert.Equal(t, "#", idx.schemaAnchorRegistry["test.yaml#a"].DefinitionPath) +} + +// "#foo" inside an external file names an anchor in that file, not in the root document. +func TestSchemaAnchorInExternalFile(t *testing.T) { + dir := t.TempDir() + const root = `openapi: 3.1.0 +info: {title: anchors, version: '1'} +paths: {} +components: + schemas: + Root: + $anchor: name + type: integer + Pet: + $ref: 'pet.yaml#/components/schemas/Pet' +` + const pet = `components: + schemas: + Name: + $anchor: name + type: string + Pet: + type: object + properties: + name: {$ref: '#name'} +` + require.NoError(t, os.WriteFile(filepath.Join(dir, "root.yaml"), []byte(root), 0o600)) + require.NoError(t, os.WriteFile(filepath.Join(dir, "pet.yaml"), []byte(pet), 0o600)) + + var rootNode yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(root), &rootNode)) + + cfg := CreateOpenAPIIndexConfig() + cfg.BasePath = dir + cfg.SpecAbsolutePath = filepath.Join(dir, "root.yaml") + rolodex := NewRolodex(cfg) + rolodex.SetRootNode(&rootNode) + fileFS, err := NewLocalFSWithConfig(&LocalFSConfig{BaseDirectory: dir, IndexConfig: cfg}) + require.NoError(t, err) + rolodex.AddLocalFS(dir, fileFS) + + require.NoError(t, rolodex.IndexTheRolodex(context.Background())) + rolodex.Resolve() + assert.Empty(t, rolodex.GetCaughtErrors()) + + petIdx := rolodex.GetRootIndex().GetRolodex().GetIndexes() + var found *Reference + for _, idx := range petIdx { + if idx.GetSpecAbsolutePath() == filepath.Join(dir, "pet.yaml") { + found, _ = idx.SearchIndexForReference("#name") + } + } + require.NotNil(t, found) + assert.Equal(t, "string", schemaNodeType(found.Node)) +} diff --git a/index/schema_id_resolve.go b/index/schema_id_resolve.go index 3ae0cdca..bae242dd 100644 --- a/index/schema_id_resolve.go +++ b/index/schema_id_resolve.go @@ -195,7 +195,8 @@ func buildSchemaIdResolvedReference(index *SpecIndex, entry *SchemaIdEntry, orig // 1. Split ref into base URI and fragment // 2. Look up base URI in $id registry // 3. Navigate to fragment within found schema if present -// Returns nil if the ref cannot be resolved via $id. +// A plain-name fragment such as "#foo" is looked up as an $anchor first. +// Returns nil if the ref cannot be resolved via $id or $anchor. func (index *SpecIndex) ResolveRefViaSchemaId(ref string) *Reference { if ref == "" { return nil @@ -203,6 +204,12 @@ func (index *SpecIndex) ResolveRefViaSchemaId(ref string) *Reference { baseUri, fragment := SplitRefFragment(ref) + if isSchemaAnchorFragment(fragment) { + if resolved := index.resolveRefViaSchemaAnchor(ref, baseUri, fragment); resolved != nil { + return resolved + } + } + // Local fragment refs are not $id-based if baseUri == "" { return nil diff --git a/index/search_index.go b/index/search_index.go index 699192ec..60db1da0 100644 --- a/index/search_index.go +++ b/index/search_index.go @@ -108,13 +108,6 @@ func (index *SpecIndex) SearchIndexForReferenceWithContext(ctx context.Context, } func (index *SpecIndex) SearchIndexForReferenceByReferenceWithContext(ctx context.Context, searchRef *Reference) (*Reference, *SpecIndex, context.Context) { - if index.cache != nil { - if v, ok := index.cache.Load(searchRef.FullDefinition); ok { - idx := index.extractIndex(v.(*Reference)) - return v.(*Reference), idx, context.WithValue(ctx, CurrentPathKey, v.(*Reference).RemoteLocation) - } - } - // --- Step 1: JSON Schema $id resolution --- // Resolve the ref against JSON Schema $id values first. Specs using JSON Schema 2020-12 // register schemas by their $id URI (e.g. "$id: https://example.com/a.json"), so a bare @@ -125,6 +118,18 @@ func (index *SpecIndex) SearchIndexForReferenceByReferenceWithContext(ctx contex schemaIdBase = scope.BaseUri } } + // "#foo" names an $anchor in the current resource, so cache it under that resource. + cacheKey := searchRef.FullDefinition + if isSchemaAnchorFragment(cacheKey) && schemaIdBase != "" { + cacheKey = resolveRefWithSchemaBase(cacheKey, schemaIdBase) + } + + if index.cache != nil { + if v, ok := index.cache.Load(cacheKey); ok { + idx := index.extractIndex(v.(*Reference)) + return v.(*Reference), idx, context.WithValue(ctx, CurrentPathKey, v.(*Reference).RemoteLocation) + } + } rawRef := searchRef.FullDefinition if searchRef.RawRef != "" && schemaIdBase != "" { @@ -132,7 +137,7 @@ func (index *SpecIndex) SearchIndexForReferenceByReferenceWithContext(ctx contex } normalizedRef := resolveRefWithSchemaBase(rawRef, schemaIdBase) - if index.cache != nil && normalizedRef != searchRef.FullDefinition { + if index.cache != nil && normalizedRef != cacheKey { if v, ok := index.cache.Load(normalizedRef); ok { idx := index.extractIndex(v.(*Reference)) return v.(*Reference), idx, context.WithValue(ctx, CurrentPathKey, v.(*Reference).RemoteLocation) @@ -142,8 +147,8 @@ func (index *SpecIndex) SearchIndexForReferenceByReferenceWithContext(ctx contex // Try the $id registry for an exact match, then fall back to path-only matching. if resolved := index.ResolveRefViaSchemaId(normalizedRef); resolved != nil { if index.cache != nil { - index.cache.Store(searchRef.FullDefinition, resolved) - if normalizedRef != searchRef.FullDefinition { + index.cache.Store(cacheKey, resolved) + if normalizedRef != cacheKey { index.cache.Store(normalizedRef, resolved) } } @@ -158,8 +163,8 @@ func (index *SpecIndex) SearchIndexForReferenceByReferenceWithContext(ctx contex if pathRef != "" { if resolved := index.resolveRefViaSchemaIdPath(pathRef); resolved != nil { if index.cache != nil { - index.cache.Store(searchRef.FullDefinition, resolved) - if normalizedRef != searchRef.FullDefinition { + index.cache.Store(cacheKey, resolved) + if normalizedRef != cacheKey { index.cache.Store(normalizedRef, resolved) } } From b56d5f89a8c26831cbb58c4a7c5d36b3881aed4a Mon Sep 17 00:00:00 2001 From: Thomas Date: Sun, 15 Nov 2026 21:39:23 +1100 Subject: [PATCH 2/2] fix(index): register $anchor only at schema locations 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. --- bundler/bundler_composer_test.go | 46 +++++ document_test.go | 268 +++++++++++++++++++++++++ index/extract_refs.go | 12 +- index/extract_refs_alias_limit_test.go | 12 +- index/extract_refs_ref.go | 13 +- index/extract_refs_test.go | 12 +- index/extract_refs_walk.go | 31 ++- index/schema_anchor.go | 50 +++-- index/schema_anchor_test.go | 244 +++++++++++++++++++++- index/schema_anchor_values_test.go | 220 ++++++++++++++++++++ index/schema_id_resolve.go | 4 +- index/schema_id_types.go | 9 +- index/schema_identifier_path.go | 76 +++++++ 13 files changed, 948 insertions(+), 49 deletions(-) create mode 100644 index/schema_anchor_values_test.go create mode 100644 index/schema_identifier_path.go diff --git a/bundler/bundler_composer_test.go b/bundler/bundler_composer_test.go index b14edb63..64b6ae70 100644 --- a/bundler/bundler_composer_test.go +++ b/bundler/bundler_composer_test.go @@ -3196,3 +3196,49 @@ func TestBuildSchema_UnresolvedReferenceReturnsError(t *testing.T) { require.ErrorContains(t, err, "#/missing") require.Nil(t, schema) } + +// TestBundleBytesComposed_AnchorRefsIntoPrefixItems checks that plain-name $anchor refs +// into a tuple are rewritten to pointers at each prefixItems element, not at the array. +func TestBundleBytesComposed_AnchorRefsIntoPrefixItems(t *testing.T) { + spec := []byte(`openapi: 3.1.0 +info: + title: t + version: '1' +paths: {} +components: + schemas: + Tuple: + type: array + prefixItems: + - $anchor: first + type: boolean + - $anchor: second + type: number + T: + type: object + properties: + first: + $ref: '#first' + second: + $ref: '#second' +`) + + schemaAt := func(t *testing.T, bundled []byte, prop string) map[string]any { + t.Helper() + var doc map[string]any + require.NoError(t, yaml.Unmarshal(bundled, &doc)) + schemas := doc["components"].(map[string]any)["schemas"].(map[string]any) + props := schemas["T"].(map[string]any)["properties"].(map[string]any) + return props[prop].(map[string]any) + } + + composed, err := BundleBytesComposed(spec, &datamodel.DocumentConfiguration{}, nil) + require.NoError(t, err) + assert.Equal(t, "#/components/schemas/Tuple/prefixItems/0", schemaAt(t, composed, "first")["$ref"]) + assert.Equal(t, "#/components/schemas/Tuple/prefixItems/1", schemaAt(t, composed, "second")["$ref"]) + + inlined, err := BundleBytes(spec, &datamodel.DocumentConfiguration{}) + require.NoError(t, err) + assert.Equal(t, "boolean", schemaAt(t, inlined, "first")["type"]) + assert.Equal(t, "number", schemaAt(t, inlined, "second")["type"]) +} diff --git a/document_test.go b/document_test.go index 02b4c9c7..603fc212 100644 --- a/document_test.go +++ b/document_test.go @@ -2616,6 +2616,7 @@ components: type: object properties: local: {$ref: '#foo'} + encoded: {$ref: '#f%6Fo'} R: $id: https://example.com/r type: object @@ -2624,10 +2625,22 @@ components: properties: scoped: {$ref: '#bar'} absolute: {$ref: 'https://example.com/r#bar'} + encoded: {$ref: '#b%61r'} U: type: object properties: outside: {$ref: 'https://example.com/r#bar'} + encodedOutside: {$ref: 'https://example.com/r#b%61r'} + Tuple: + type: array + prefixItems: + - {$anchor: first, type: boolean} + - {$anchor: second, type: number} + T: + type: object + properties: + first: {$ref: '#first'} + second: {$ref: '#second'} ` doc, err := NewDocument([]byte(spec)) require.NoError(t, err) @@ -2638,9 +2651,14 @@ components: schemas := m.Model.Components.Schemas for _, tc := range []struct{ schema, property, kind string }{ {"B", "local", "string"}, + {"B", "encoded", "string"}, {"R", "scoped", "integer"}, {"R", "absolute", "integer"}, + {"R", "encoded", "integer"}, {"U", "outside", "integer"}, + {"U", "encodedOutside", "integer"}, + {"T", "first", "boolean"}, + {"T", "second", "number"}, } { t.Run(tc.schema+"."+tc.property, func(t *testing.T) { prop := schemas.GetOrZero(tc.schema).Schema().Properties.GetOrZero(tc.property) @@ -2650,4 +2668,254 @@ components: assert.Equal(t, []string{tc.kind}, s.Type) }) } + + mapped := m.Index.GetMappedReferences() + assert.Contains(t, mapped, "#/components/schemas/Tuple/prefixItems/0") + assert.Contains(t, mapped, "#/components/schemas/Tuple/prefixItems/1") +} + +// a default payload is an instance, not a schema, so its $anchor does not take the name from the +// schema declared after it. +func TestDocument_BuildV3Model_SchemaAnchorAfterDefaultPayload(t *testing.T) { + spec := `openapi: 3.1.0 +info: {title: anchors, version: "1"} +paths: {} +components: + schemas: + Choice: + type: object + default: {$anchor: selected, type: integer} + Selected: + $anchor: selected + type: string + Uses: + type: object + properties: + pick: {$ref: '#selected'} +` + doc, err := NewDocument([]byte(spec)) + require.NoError(t, err) + m, err := doc.BuildV3Model() + require.NoError(t, err) + assert.Empty(t, m.Index.GetReferenceIndexErrors()) + + prop := m.Model.Components.Schemas.GetOrZero("Uses").Schema().Properties.GetOrZero("pick") + require.NotNil(t, prop) + s := prop.Schema() + require.NotNil(t, s, prop.GetBuildError()) + assert.Equal(t, []string{"string"}, s.Type) +} + +// an $id under an extension or a default payload still sets the base URI for the refs inside it. +func TestDocument_BuildV3Model_SchemaIdInExtensionAndDefault(t *testing.T) { + const head = "openapi: 3.1.0\ninfo: {title: ids, version: \"1\"}\npaths: {}\n" + build := func(t *testing.T, spec string) { + doc, err := NewDocument([]byte(head + spec)) + require.NoError(t, err) + m, err := doc.BuildV3Model() + require.NoError(t, err) + assert.Empty(t, m.Index.GetReferenceIndexErrors()) + } + + t.Run("ref inside an $id resource under an extension", func(t *testing.T) { + build(t, `x-vendor: + Resource: + $id: 'https://example.com/vendor' + type: object + $defs: + S: {type: string} + properties: + s: {$ref: '#/$defs/S'} +`) + }) + + t.Run("ref inside an $id resource under a default", func(t *testing.T) { + build(t, `components: + schemas: + Holder: + type: object + default: + $id: 'https://example.com/default' + type: object + $defs: + S: {type: string} + properties: + s: {$ref: '#/$defs/S'} +`) + }) +} + +// a Link Object's parameter values and request body, and an extension on an operation's Responses +// Object, are data, so an $anchor there does not shadow the schema that declares it. +func TestDocument_BuildV3Model_SchemaAnchorInLinkAndResponsesExtension(t *testing.T) { + const link = ` + links: + L: + operationId: getP +` + for name, c := range map[string]struct{ paths, links string }{ + "link parameter value": {paths: link + ` parameters: + p: {$anchor: thing, type: integer} +`}, + "link request body": {paths: link + ` requestBody: {$anchor: thing, type: integer} +`}, + "responses extension": {paths: ` + x-shadow: + content: + application/json: + schema: {$anchor: thing, type: integer} +`}, + "component link parameter value": {links: ` links: + L: + operationId: getP + parameters: + p: {$anchor: thing, type: integer} +`}, + } { + t.Run(name, func(t *testing.T) { + spec := `openapi: 3.1.0 +info: {title: anchors, version: "1"} +paths: + /p: + get: + operationId: getP + responses: + "200": + description: ok` + c.paths + ` +components: +` + c.links + ` schemas: + Thing: {$anchor: thing, type: string} + Uses: + type: object + properties: + thing: {$ref: '#thing'} +` + doc, err := NewDocument([]byte(spec)) + require.NoError(t, err) + m, err := doc.BuildV3Model() + require.NoError(t, err) + assert.Empty(t, m.Index.GetReferenceIndexErrors()) + + prop := m.Model.Components.Schemas.GetOrZero("Uses").Schema().Properties.GetOrZero("thing") + require.NotNil(t, prop) + s := prop.Schema() + require.NotNil(t, s, prop.GetBuildError()) + assert.Equal(t, []string{"string"}, s.Type) + }) + } +} + +// a key holding "~" or "/" is escaped in the definition path, and a ref to an anchor beneath it +// still resolves. +func TestDocument_BuildV3Model_SchemaAnchorUnderTildeKey(t *testing.T) { + spec := `openapi: 3.1.0 +info: {title: anchors, version: "1"} +paths: {} +components: + schemas: + A: + type: object + properties: + a~b: {$anchor: tilde, type: string} + c/d~1e: {$anchor: slash, type: integer} + Uses: + type: object + properties: + t: {$ref: '#tilde'} + s: {$ref: '#slash'} +` + doc, err := NewDocument([]byte(spec)) + require.NoError(t, err) + m, err := doc.BuildV3Model() + require.NoError(t, err) + assert.Empty(t, m.Index.GetReferenceIndexErrors()) + + for ref, want := range map[string]struct{ path, prop, kind string }{ + "#tilde": {path: "#/components/schemas/A/properties/a~0b", prop: "t", kind: "string"}, + "#slash": {path: "#/components/schemas/A/properties/c~1d~01e", prop: "s", kind: "integer"}, + } { + resolved := m.Index.ResolveRefViaSchemaId(ref) + require.NotNil(t, resolved, ref) + assert.Equal(t, want.path, resolved.Definition, ref) + + prop := m.Model.Components.Schemas.GetOrZero("Uses").Schema().Properties.GetOrZero(want.prop) + require.NotNil(t, prop, ref) + s := prop.Schema() + require.NotNil(t, s, prop.GetBuildError()) + assert.Equal(t, []string{want.kind}, s.Type, ref) + } + props := m.Model.Components.Schemas.GetOrZero("A").Schema().Properties + assert.Equal(t, []string{"string"}, props.GetOrZero("a~b").Schema().Type) + assert.Equal(t, []string{"integer"}, props.GetOrZero("c/d~1e").Schema().Type) +} + +// an $anchor inside an $id resource is classified by its path from the resource's root, so a +// resource under an extension or a default keeps its anchors, while data inside the resource still +// declares none. +func TestDocument_BuildV3Model_SchemaAnchorInsideIdResource(t *testing.T) { + const head = "openapi: 3.1.0\ninfo: {title: anchors, version: \"1\"}\npaths: {}\n" + build := func(t *testing.T, spec string) *DocumentModel[v3high.Document] { + doc, err := NewDocument([]byte(head + spec)) + require.NoError(t, err) + m, err := doc.BuildV3Model() + require.NoError(t, err) + assert.Empty(t, m.Index.GetReferenceIndexErrors()) + return m + } + kind := func(t *testing.T, m *DocumentModel[v3high.Document], property string) []string { + prop := m.Model.Components.Schemas.GetOrZero("Uses").Schema().Properties.GetOrZero(property) + require.NotNil(t, prop, property) + s := prop.Schema() + require.NotNil(t, s, prop.GetBuildError()) + return s.Type + } + + t.Run("resource under an extension", func(t *testing.T) { + m := build(t, `x-vendor: + Thing: {$id: 'https://example.com/thing', type: object, $defs: {S: {$anchor: s, type: string}}} +components: + schemas: + Uses: + type: object + properties: + byId: {$ref: 'https://example.com/thing'} + byPointer: {$ref: 'https://example.com/thing#/$defs/S'} + byAnchor: {$ref: 'https://example.com/thing#s'} +`) + assert.Equal(t, []string{"object"}, kind(t, m, "byId")) + assert.Equal(t, []string{"string"}, kind(t, m, "byPointer")) + assert.Equal(t, []string{"string"}, kind(t, m, "byAnchor")) + }) + + t.Run("default inside a resource under an extension", func(t *testing.T) { + m := build(t, `x-vendor: + Thing: + $id: 'https://example.com/thing' + default: {$anchor: s, type: integer} + $defs: + S: {$anchor: s, type: string} +components: + schemas: + Uses: + type: object + properties: + byAnchor: {$ref: 'https://example.com/thing#s'} +`) + assert.Equal(t, []string{"string"}, kind(t, m, "byAnchor")) + }) + + t.Run("resource in a default payload", func(t *testing.T) { + m := build(t, `components: + schemas: + Holder: + type: object + default: {$id: 'https://example.com/payload', $anchor: thing, type: integer} + Thing: {$anchor: thing, type: string} + Uses: + type: object + properties: + thing: {$ref: '#thing'} +`) + assert.Equal(t, []string{"string"}, kind(t, m, "thing")) + }) } diff --git a/index/extract_refs.go b/index/extract_refs.go index 984bff0b..b88f50dd 100644 --- a/index/extract_refs.go +++ b/index/extract_refs.go @@ -128,7 +128,11 @@ func (index *SpecIndex) ExtractRefs(ctx context.Context, node, parent *yaml.Node if index.config != nil && index.config.AllowExcessiveAliases { walk.limits = unlimitedExtractRefsLimits } - return index.extractRefs(ctx, node, parent, seenPath, level, poly, pName, walk) + // pointer gets its own array, so the walk's appends never write into seenPath's, and spare + // capacity for a typical document's depth, so those appends rarely reallocate. + pointer := make([]string, len(seenPath), len(seenPath)+64) + copy(pointer, seenPath) + return index.extractRefs(ctx, node, parent, seenPath, pointer, level, poly, pName, walk) } type extractRefsTraversal struct { @@ -155,7 +159,9 @@ func (walk *extractRefsTraversal) visit() error { // Ancestry tracks canonical source nodes, not the shallow views created during // merge expansion. A shared anchor is visited again at each distinct path. -func (index *SpecIndex) extractRefs(ctx context.Context, node, parent *yaml.Node, seenPath []string, level int, poly bool, pName string, walk *extractRefsTraversal) []*Reference { +// pointer holds the JSON pointer segments to node. Unlike seenPath it has every sequence index and +// every key, and a value reached through a merge key sits under the mapping that merges it. +func (index *SpecIndex) extractRefs(ctx context.Context, node, parent *yaml.Node, seenPath, pointer []string, level int, poly bool, pName string, walk *extractRefsTraversal) []*Reference { if node == nil || walk.stopped { return nil } @@ -198,7 +204,7 @@ func (index *SpecIndex) extractRefs(ctx context.Context, node, parent *yaml.Node } walk.ancestry[node] = struct{}{} } - state := index.initializeExtractRefsState(ctx, nodeID, seenPath, level, poly, pName) + state := index.initializeExtractRefsState(ctx, nodeID, seenPath, pointer, level, poly, pName) state.mergeStart = len(view.Content) if view != node { // Merge views retain explicit pairs first, then append inherited pairs. diff --git a/index/extract_refs_alias_limit_test.go b/index/extract_refs_alias_limit_test.go index 956fceee..2780dc26 100644 --- a/index/extract_refs_alias_limit_test.go +++ b/index/extract_refs_alias_limit_test.go @@ -18,7 +18,7 @@ func TestExtractRefsStopsAtAliasLimit(t *testing.T) { ancestry: make(map[*yaml.Node]struct{}), nodes: 1000, aliasNodes: 1000, aliasDepth: 1, } - require.Nil(t, idx.extractRefs(context.Background(), root.Content[0], &root, []string{"x-shared"}, 0, false, "", walk)) + require.Nil(t, idx.extractRefs(context.Background(), root.Content[0], &root, []string{"x-shared"}, []string{"x-shared"}, 0, false, "", walk)) require.True(t, walk.stopped) require.Len(t, idx.GetReferenceIndexErrors(), 1) err := idx.GetReferenceIndexErrors()[0].(*ResolvingError) @@ -26,7 +26,7 @@ func TestExtractRefsStopsAtAliasLimit(t *testing.T) { require.Same(t, root.Content[0], err.Node) require.Equal(t, "$.x-shared", err.Path) // Once stopped, later siblings do not continue work or add duplicate errors. - require.Nil(t, idx.extractRefs(context.Background(), root.Content[0], &root, nil, 0, false, "", walk)) + require.Nil(t, idx.extractRefs(context.Background(), root.Content[0], &root, nil, nil, 0, false, "", walk)) require.Len(t, idx.GetReferenceIndexErrors(), 1) require.Equal(t, 1001, walk.nodes) } @@ -44,7 +44,7 @@ func TestExtractRefsMergeCycleWithoutAliasInWalk(t *testing.T) { require.NoError(t, yaml.Unmarshal([]byte("x: &x {b: {<<: *x}}\n"), &root)) idx := NewSpecIndex(nil) walk := &extractRefsTraversal{} - idx.extractRefs(context.Background(), &root, nil, nil, 0, false, "", walk) + idx.extractRefs(context.Background(), &root, nil, nil, nil, 0, false, "", walk) require.False(t, walk.stopped) require.Empty(t, idx.GetReferenceIndexErrors()) require.Empty(t, walk.ancestry) @@ -62,7 +62,7 @@ components: `), &root)) idx := NewSpecIndex(nil) walk := &extractRefsTraversal{} - refs := idx.extractRefs(context.Background(), &root, nil, nil, 0, false, "", walk) + refs := idx.extractRefs(context.Background(), &root, nil, nil, nil, 0, false, "", walk) require.Len(t, refs, 1) require.Nil(t, walk.ancestry) require.Zero(t, walk.aliasNodes) @@ -81,7 +81,7 @@ target: t.Run("only inherited descendants", func(t *testing.T) { idx := NewSpecIndex(nil) walk := &extractRefsTraversal{ancestry: make(map[*yaml.Node]struct{}), nodes: 1000} - idx.extractRefs(context.Background(), target, nil, nil, 0, false, "", walk) + idx.extractRefs(context.Background(), target, nil, nil, nil, 0, false, "", walk) require.False(t, walk.stopped) require.Empty(t, idx.GetReferenceIndexErrors()) require.Equal(t, 1005, walk.nodes) @@ -91,7 +91,7 @@ target: t.Run("inherited descendants reach limit", func(t *testing.T) { idx := NewSpecIndex(nil) walk := &extractRefsTraversal{ancestry: make(map[*yaml.Node]struct{}), nodes: 997, aliasNodes: 997} - idx.extractRefs(context.Background(), target, nil, []string{"target"}, 0, false, "", walk) + idx.extractRefs(context.Background(), target, nil, []string{"target"}, []string{"target"}, 0, false, "", walk) require.True(t, walk.stopped) require.Len(t, idx.GetReferenceIndexErrors(), 1) require.ErrorContains(t, idx.GetReferenceIndexErrors()[0], "document contains excessive aliasing") diff --git a/index/extract_refs_ref.go b/index/extract_refs_ref.go index f5680dc7..f79d89a0 100644 --- a/index/extract_refs_ref.go +++ b/index/extract_refs_ref.go @@ -145,21 +145,20 @@ func (index *SpecIndex) extractReferenceAt( return ref } -func (index *SpecIndex) registerSchemaIDAt(node *yaml.Node, keyIndex int, seenPath []string, parentBaseUri string) { +// registerSchemaIDAt records the $id at node.Content[keyIndex], where pointer is the JSON pointer +// segments to node and seenPath is the walk's path to it. +func (index *SpecIndex) registerSchemaIDAt(node *yaml.Node, keyIndex int, seenPath, pointer []string, parentBaseUri string) { if underOpenAPIExamplePath(seenPath) { return } - if len(node.Content) <= keyIndex+1 || !utils.IsNodeStringValue(node.Content[keyIndex+1]) { + // in a sequence, such as required: [$id, name], "$id" is an entry, not a key. + if len(node.Content) <= keyIndex+1 || utils.IsNodeArray(node) || !utils.IsNodeStringValue(node.Content[keyIndex+1]) { return } idValue := node.Content[keyIndex+1].Value idNode := node.Content[keyIndex+1] - - definitionPath := "#" - if len(seenPath) > 0 { - definitionPath = "#/" + strings.Join(seenPath, "/") - } + definitionPath := schemaPointer(pointer) if err := ValidateSchemaId(idValue); err != nil { index.errorLock.Lock() diff --git a/index/extract_refs_test.go b/index/extract_refs_test.go index 271064bb..67a5f4c4 100644 --- a/index/extract_refs_test.go +++ b/index/extract_refs_test.go @@ -945,19 +945,20 @@ func TestRegisterSchemaIDAt_HelperBranches(t *testing.T) { var invalidNode yaml.Node _ = yaml.Unmarshal([]byte(`$id: '#/bad'`), &invalidNode) - idx.registerSchemaIDAt(invalidNode.Content[0], 0, []string{"components", "schemas", "Pet"}, "test.yaml") + pet := []string{"components", "schemas", "Pet"} + idx.registerSchemaIDAt(invalidNode.Content[0], 0, pet, pet, "test.yaml") assert.NotEmpty(t, idx.refErrors) var nonStringNode yaml.Node _ = yaml.Unmarshal([]byte(`$id: type: string`), &nonStringNode) errorsBefore := len(idx.refErrors) - idx.registerSchemaIDAt(nonStringNode.Content[0], 0, nil, "test.yaml") + idx.registerSchemaIDAt(nonStringNode.Content[0], 0, nil, nil, "test.yaml") assert.Len(t, idx.refErrors, errorsBefore) var fallbackNode yaml.Node _ = yaml.Unmarshal([]byte(`$id: schema.json`), &fallbackNode) - idx.registerSchemaIDAt(fallbackNode.Content[0], 0, []string{"components", "schemas", "Pet"}, "://bad-base") + idx.registerSchemaIDAt(fallbackNode.Content[0], 0, pet, pet, "://bad-base") entry := idx.schemaIdRegistry["schema.json"] assert.NotNil(t, entry) assert.Equal(t, "schema.json", entry.ResolvedUri) @@ -971,7 +972,8 @@ func TestRegisterSchemaIDAt_SkipsExamplePaths(t *testing.T) { var node yaml.Node _ = yaml.Unmarshal([]byte(`$id: https://example.com/schema.json`), &node) - idx.registerSchemaIDAt(node.Content[0], 0, []string{"components", "examples", "Sample", "value"}, "test.yaml") + sample := []string{"components", "examples", "Sample", "value"} + idx.registerSchemaIDAt(node.Content[0], 0, sample, sample, "test.yaml") assert.Empty(t, idx.schemaIdRegistry) assert.Empty(t, idx.refErrors) @@ -1088,7 +1090,7 @@ properties: func TestExtractRefs_WalkHelpers(t *testing.T) { idx := NewTestSpecIndex().Load().(*SpecIndex) - state := idx.initializeExtractRefsState(context.Background(), "", nil, 0, false, "") + state := idx.initializeExtractRefsState(context.Background(), "", nil, nil, 0, false, "") node := &yaml.Node{ Kind: yaml.MappingNode, diff --git a/index/extract_refs_walk.go b/index/extract_refs_walk.go index c2a6e3cb..212ed79c 100644 --- a/index/extract_refs_walk.go +++ b/index/extract_refs_walk.go @@ -5,6 +5,7 @@ package index import ( "context" + "strconv" "strings" "github.com/pb33f/go-yaml" @@ -17,6 +18,7 @@ type extractRefsState struct { scope *SchemaIdScope parentBaseURI string seenPath []string + pointer []string // JSON pointer segments to the node being walked; never stored lastAppended bool level int poly bool @@ -27,7 +29,7 @@ type extractRefsState struct { func (index *SpecIndex) initializeExtractRefsState( ctx context.Context, nodeID string, - seenPath []string, + seenPath, pointer []string, level int, poly bool, pName string, @@ -46,6 +48,7 @@ func (index *SpecIndex) initializeExtractRefsState( } scope = scope.Copy() scope.PushId(resolvedNodeID) + scope.resourceDepth = len(pointer) ctx = WithSchemaIdScope(ctx, scope) } @@ -54,6 +57,7 @@ func (index *SpecIndex) initializeExtractRefsState( scope: scope, parentBaseURI: parentBaseURI, seenPath: seenPath, + pointer: pointer, level: level, poly: poly, polyName: pName, @@ -66,6 +70,7 @@ func (index *SpecIndex) walkExtractRefs(node, parent *yaml.Node, state *extractR } var found []*Reference + sequence := utils.IsNodeArray(node) for i, n := range node.Content { // In YAML mapping nodes, Content alternates key-value: even indices (0, 2, 4...) // are keys, odd indices (1, 3, 5...) are values. @@ -80,7 +85,7 @@ func (index *SpecIndex) walkExtractRefs(node, parent *yaml.Node, state *extractR if inherited { walk.aliasDepth++ } - found = append(found, index.walkChildExtractRefs(n, node, state, walk)...) + found = append(found, index.walkChildExtractRefs(n, node, childPointer(node, state.pointer, i, sequence), state, walk)...) if inherited { walk.aliasDepth-- } @@ -95,7 +100,21 @@ func (index *SpecIndex) walkExtractRefs(node, parent *yaml.Node, state *extractR return found } -func (index *SpecIndex) walkChildExtractRefs(node, parent *yaml.Node, state *extractRefsState, walk *extractRefsTraversal) []*Reference { +// childPointer returns the pointer to node.Content[i]. In a sequence it appends the index. In a +// mapping it appends the key to a value, with "~" written as "~0" and "/" as "~1", and returns +// pointer unchanged for the key node itself. The result shares pointer's array, which is safe +// because the walk is depth first and turns a pointer into a string before descending further. +func childPointer(node *yaml.Node, pointer []string, i int, sequence bool) []string { + if sequence { + return append(pointer, strconv.Itoa(i)) + } + if i%2 == 1 && node.Content[i-1] != nil { + return append(pointer, strings.ReplaceAll(strings.ReplaceAll(node.Content[i-1].Value, "~", "~0"), "/", "~1")) + } + return pointer +} + +func (index *SpecIndex) walkChildExtractRefs(node, parent *yaml.Node, pointer []string, state *extractRefsState, walk *extractRefsTraversal) []*Reference { if underOpenAPIExamplePayloadPath(state.seenPath) { return nil } @@ -109,7 +128,7 @@ func (index *SpecIndex) walkChildExtractRefs(node, parent *yaml.Node, state *ext state.polyName = state.prev } } - return index.extractRefs(state.ctx, node, parent, state.seenPath, state.level, state.poly, state.polyName, walk) + return index.extractRefs(state.ctx, node, parent, state.seenPath, pointer, state.level, state.poly, state.polyName, walk) } func isDirectOpenAPIExampleRefNode(node *yaml.Node) bool { @@ -151,11 +170,11 @@ func (index *SpecIndex) handleExtractRefsKey( } if keyNode.Value == "$id" { - index.registerSchemaIDAt(node, keyIndex, state.seenPath, state.parentBaseURI) + index.registerSchemaIDAt(node, keyIndex, state.seenPath, state.pointer, state.parentBaseURI) } if keyNode.Value == "$anchor" { - index.registerSchemaAnchorAt(node, keyIndex, state.seenPath, state.scope.BaseUri) + index.registerSchemaAnchorAt(node, keyIndex, state.pointer, state.scope) } if keyNode.Value != "$ref" && keyNode.Value != "$id" && keyNode.Value != "" { diff --git a/index/schema_anchor.go b/index/schema_anchor.go index 0de495c6..b79a557d 100644 --- a/index/schema_anchor.go +++ b/index/schema_anchor.go @@ -4,6 +4,7 @@ package index import ( + "net/url" "regexp" "strings" @@ -17,31 +18,54 @@ var schemaAnchorName = regexp.MustCompile(`^[A-Za-z_][-A-Za-z0-9._]*$`) // isSchemaAnchorFragment reports whether a fragment such as "#foo" names an $anchor // rather than a JSON pointer. func isSchemaAnchorFragment(fragment string) bool { - return len(fragment) > 1 && fragment[0] == '#' && fragment[1] != '/' + _, ok := schemaAnchorFragmentName(fragment) + return ok +} + +// schemaAnchorFragmentName returns the anchor name a fragment such as "#foo" names. A URI +// fragment is percent-encoded, so "#f%6Fo" names foo as well, and "#%2Ffoo" is the JSON +// pointer "/foo", not an anchor. +func schemaAnchorFragmentName(fragment string) (string, bool) { + if len(fragment) < 2 || fragment[0] != '#' { + return "", false + } + name, err := url.PathUnescape(fragment[1:]) + if err != nil || !schemaAnchorName.MatchString(name) { + return "", false + } + return name, true } // 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 { +// that declares it: the nearest $id, or the document itself. pointer is the JSON pointer +// segments to node, and scope is the walk's $id scope there. +func (index *SpecIndex) registerSchemaAnchorAt(node *yaml.Node, keyIndex int, pointer []string, scope *SchemaIdScope) { + // in a sequence, such as required: [$anchor, name], "$anchor" is an entry, not a key. + if len(node.Content) <= keyIndex+1 || utils.IsNodeArray(node) { return } anchorNode := node.Content[keyIndex+1] if !utils.IsNodeStringValue(anchorNode) || !schemaAnchorName.MatchString(anchorNode.Value) { return } - - definitionPath := "#" - if len(seenPath) > 0 { - definitionPath = "#/" + strings.Join(seenPath, "/") + // within an $id resource, whose root is a schema, the path from that root decides, so a + // resource under an extension or a default keeps its anchors. + if depth := scope.resourceDepth; depth > 0 && depth <= len(pointer) { + if underSchemaDataPath(pointer[depth:], true) { + return + } + } else if underSchemaDataPath(pointer, false) { + return } + baseUri := scope.BaseUri + entry := &SchemaIdEntry{ Id: anchorNode.Value, ResolvedUri: baseUri + "#" + anchorNode.Value, SchemaNode: node, ParentId: baseUri, Index: index, - DefinitionPath: definitionPath, + DefinitionPath: schemaPointer(pointer), Line: anchorNode.Line, Column: anchorNode.Column, } @@ -62,13 +86,13 @@ func (index *SpecIndex) getSchemaAnchor(uri string) *SchemaIdEntry { return index.schemaAnchorRegistry[uri] } -// resolveRefViaSchemaAnchor resolves a ref whose fragment is a plain-name $anchor. A ref -// with no base URI, such as "#foo", is looked up in this document. -func (index *SpecIndex) resolveRefViaSchemaAnchor(ref, baseUri, fragment string) *Reference { +// resolveRefViaSchemaAnchor resolves ref to the $anchor called name, already decoded from the +// ref's fragment. A ref with no base URI, such as "#foo", is looked up in this document. +func (index *SpecIndex) resolveRefViaSchemaAnchor(ref, baseUri, name string) *Reference { if baseUri == "" { baseUri = index.specAbsolutePath } - key := baseUri + fragment + key := baseUri + "#" + name entry := index.getSchemaAnchor(key) if entry == nil && index.rolodex != nil { entry = index.rolodex.lookupSchemaAnchor(key) diff --git a/index/schema_anchor_test.go b/index/schema_anchor_test.go index 458854eb..6ee0baf3 100644 --- a/index/schema_anchor_test.go +++ b/index/schema_anchor_test.go @@ -48,11 +48,18 @@ components: $id: https://example.com/self $anchor: self type: array + Tuple: + type: array + prefixItems: + - {$anchor: first, type: string} + - {$anchor: second, type: integer} B: type: object properties: local: {$ref: '#foo'} outside: {$ref: 'https://example.com/r#bar'} + first: {$ref: '#first'} + second: {$ref: '#second'} ` func schemaNodeType(node *yaml.Node) string { @@ -74,6 +81,10 @@ func TestSchemaAnchorResolution(t *testing.T) { {"anchor in $id resource", "https://example.com/r#bar", "integer"}, {"anchor beside $id", "https://example.com/self#self", "array"}, {"first duplicate wins", "#dup", "boolean"}, + {"percent-encoded name", "#f%6Fo", "string"}, + {"percent-encoded name in $id resource", "https://example.com/r#b%61r", "integer"}, + {"invalid percent-encoding", "#f%zzo", ""}, + {"array entry", "#second", "integer"}, {"scoped anchor outside its resource", "#bar", ""}, {"document anchor under an $id", "https://example.com/r#foo", ""}, {"invalid name", "#1bad", ""}, @@ -124,6 +135,17 @@ func TestSchemaAnchorResolvedReference(t *testing.T) { assert.Equal(t, "X", ref.Name) assert.Equal(t, "#/components/schemas/R/$defs/X", ref.Definition) assert.Equal(t, "https://example.com/r", ref.SchemaIdBase) + + ref = idx.ResolveRefViaSchemaId("#second") + require.NotNil(t, ref) + assert.Equal(t, "1", ref.Name) + assert.Equal(t, "#/components/schemas/Tuple/prefixItems/1", ref.Definition) + + // the encoded spelling finds the same anchor, and keeps the ref as written. + ref = idx.ResolveRefViaSchemaId("#f%6Fo") + require.NotNil(t, ref) + assert.Equal(t, "#/components/schemas/A", ref.Definition) + assert.Equal(t, "#f%6Fo", ref.RawRef) } func TestSchemaAnchorExtractedRefs(t *testing.T) { @@ -137,6 +159,207 @@ func TestSchemaAnchorExtractedRefs(t *testing.T) { assert.Equal(t, "#foo", mapped["#/components/schemas/A"].RawRef) require.Contains(t, mapped, "#/components/schemas/R/$defs/X") assert.Equal(t, "integer", schemaNodeType(mapped["#/components/schemas/R/$defs/X"].Node)) + + // anchors on two entries of one array are two targets, told apart by the index. + require.Contains(t, mapped, "#/components/schemas/Tuple/prefixItems/0") + assert.Equal(t, "string", schemaNodeType(mapped["#/components/schemas/Tuple/prefixItems/0"].Node)) + require.Contains(t, mapped, "#/components/schemas/Tuple/prefixItems/1") + assert.Equal(t, "integer", schemaNodeType(mapped["#/components/schemas/Tuple/prefixItems/1"].Node)) + assert.NotContains(t, mapped, "#/components/schemas/Tuple/prefixItems") +} + +func TestSchemaAnchorFragmentName(t *testing.T) { + for fragment, want := range map[string]string{ + "#foo": "foo", + "#f%6Fo": "foo", + "#": "", + "foo": "", + "#/foo": "", + "#%2Ffoo": "", // the JSON pointer "/foo" + "#f%zzo": "", + "#1bad": "", + "#a%20b": "", + "#_a-b.c9": "_a-b.c9", + } { + name, ok := schemaAnchorFragmentName(fragment) + assert.Equal(t, want, name, fragment) + assert.Equal(t, want != "", ok, fragment) + assert.Equal(t, want != "", isSchemaAnchorFragment(fragment), fragment) + } +} + +func TestSchemaIdentifierDefinitionPath(t *testing.T) { + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(`a: + b/c: + - {$id: 'https://example.com/x'} + - - {$id: 'https://example.com/y'} + - {$anchor: z} + alias: &shared {$anchor: w} + ref: *shared + merged: + <<: *shared + v: {$id: 'https://example.com/v'} + top: {$anchor: u, other: 1} + t~/: {$anchor: tl} + named: + properties: + $id: {$anchor: d} + $ref: {properties: {o: {$id: 'https://example.com/o'}}} + self: &self + $anchor: s + loop: *self +m: + <<: {$anchor: mw, type: string} + k: 1 +`), &root)) + cfg := CreateClosedAPIIndexConfig() + cfg.SpecAbsolutePath = "/specs/root.yaml" + idx := NewSpecIndexWithConfig(&root, cfg) + anchor := func(name string) string { + entry := idx.schemaAnchorRegistry["/specs/root.yaml#"+name] + require.NotNil(t, entry, name) + return entry.DefinitionPath + } + id := func(uri string) string { + entry := idx.GetSchemaById(uri) + require.NotNil(t, entry, uri) + return entry.DefinitionPath + } + + // the path in the tree, with the sequence indices, and each key with "~" written as "~0" and + // "/" as "~1". + assert.Equal(t, "#/a/b~1c/0", id("https://example.com/x")) + assert.Equal(t, "#/a/b~1c/1/0", id("https://example.com/y")) + assert.Equal(t, "#/a/b~1c/1/1", anchor("z")) + assert.Equal(t, "#/a/top", anchor("u")) + assert.Equal(t, "#/a/t~0~1", anchor("tl")) + // a property named $id or $ref is a segment like any other. + assert.Equal(t, "#/a/named/properties/$id", anchor("d")) + assert.Equal(t, "#/a/named/properties/$ref/properties/o", id("https://example.com/o")) + // a key beside a merge key keeps its own segment. + assert.Equal(t, "#/a/merged/v", id("https://example.com/v")) + // a value reached three times, at its declaration and through an alias and a merge key, + // registers at its declaration. + assert.Equal(t, "#/a/alias", anchor("w")) + // a mapping that holds an alias of itself, at its declaration rather than through the loop. + assert.Equal(t, "#/a/self", anchor("s")) + // an identifier written under a merge key belongs to the mapping that merges it, the one a + // reader of m sees; the merged-in mapping has no pointer of its own. + assert.Equal(t, "#/m", anchor("mw")) + resolved := idx.ResolveRefViaSchemaId("#mw") + require.NotNil(t, resolved) + assert.Equal(t, "#/m", resolved.Definition) + assert.Equal(t, "string", schemaNodeType(resolved.Node)) +} + +func TestUnderSchemaDataPath(t *testing.T) { + for _, path := range []string{ + "components/schemas/A/default", + "components/schemas/A/const", + "components/schemas/A/enum/0", + "components/schemas/A/examples/0", + "components/schemas/A/example", + "components/schemas/A/x-data", + "components/x-ext/A", + "components/examples/A/value", + "x-ext", + "paths/~1p/get/responses/200/content/application~1json/examples/E/value", + "components/schemas/default/default", + "components/schemas/A/properties/default/default", + "components/schemas/A/properties/x-named/x-data", + "components/parameters/P/schema/default", + "paths/~1p/get/parameters/0/schema/x-data", + "paths/~1p/get/responses/200/links/L/parameters", + "paths/~1p/get/responses/200/links/L/parameters/p", + "paths/~1p/get/responses/200/links/L/requestBody", + "paths/~1p/get/responses/200/links/parameters/requestBody", + "components/responses/R/links/L/parameters/p", + "components/links/L/parameters/p", + "components/links/L/requestBody", + "paths/~1p/get/responses/x-shadow/content/application~1json/schema", + "components/pathItems/P/get/responses/x-shadow", + "webhooks/hook/post/responses/x-shadow/content/application~1json/schema", + } { + assert.True(t, underSchemaDataPath(strings.Split(path, "/"), false), path) + } + for _, path := range []string{ + "", + "components/schemas/A", + "components/schemas/default", + "components/schemas/x-Named", + "components/schemas/x-Named/properties/x-named", + "components/schemas/A/properties/default", + "components/schemas/A/properties/enum/items", + "components/schemas/A/patternProperties/x-", + "components/schemas/A/$defs/const", + "components/schemas/A/definitions/example", + "components/schemas/A/dependentSchemas/examples", + "components/schemas/A/dependencies/x-dep", + "components/schemas/A/prefixItems/0", + "components/responses/default/content/application~1json/schema", + "components/headers/x-rate/schema", + "paths/~1p/get/responses/default/content/application~1json/schema", + "paths/~1p/get/responses/200/headers/x-rate/schema", + "paths/~1p/get/requestBody/content/x-custom/schema", + "paths/~1p/post/requestBody/content/multipart~1form-data/encoding/x-part/headers/h/schema", + "paths/~1p/get/callbacks/x-cb", + "paths/~1p/get/responses/200/links/default", + "webhooks/x-hook/post", + "definitions/default", + "parameters/x-param/schema", + "responses/default/schema", + "paths/~1p/get/parameters/0/schema", + "paths/~1p/get/responses/200/links/parameters", + "paths/~1p/get/responses/200/links/requestBody/server", + "components/links/parameters", + "components/links/requestBody", + "components/schemas/A/properties/links/properties/parameters", + "components/responses/x-foo/content/application~1json/schema", + "paths/~1p/get/responses/default/links/x-link", + "responses/x-foo/schema", + } { + segments := strings.Split(path, "/") + if path == "" { + segments = nil + } + assert.False(t, underSchemaDataPath(segments, false), path) + } + + // from the root of an $id resource, which is a schema, only the schema's keywords count. + for _, path := range []string{ + "default", + "const", + "enum/0", + "examples/0", + "example", + "x-data", + "properties/p/default", + "$defs/S/x-data", + "components/schemas/x-A", + "headers/x-h", + "content/x-c", + "responses/x-r", + "parameters/x-p", + } { + assert.True(t, underSchemaDataPath(strings.Split(path, "/"), true), path) + } + for _, path := range []string{ + "$defs/S", + "$defs/default", + "properties/x-named", + "properties/default/properties/enum", + "patternProperties/x-", + "definitions/example", + "dependentSchemas/const", + "dependencies/x-dep", + "prefixItems/0", + "items/properties/links/properties/parameters", + "links/L/parameters", + "links/L/requestBody", + } { + assert.False(t, underSchemaDataPath(strings.Split(path, "/"), true), path) + } } func TestSchemaAnchorResolver(t *testing.T) { @@ -270,17 +493,28 @@ func TestRegisterSchemaAnchorAt_Skips(t *testing.T) { return n.Content[0] } - idx.registerSchemaAnchorAt(parse("$anchor: a"), 0, []string{"components", "examples", "Sample", "value"}, "test.yaml") - idx.registerSchemaAnchorAt(parse("$anchor: [a]"), 0, nil, "test.yaml") - idx.registerSchemaAnchorAt(parse("$anchor: 'a b'"), 0, nil, "test.yaml") + scope := NewSchemaIdScope("test.yaml") + idx.registerSchemaAnchorAt(parse("$anchor: a"), 0, []string{"components", "examples", "Sample", "value"}, scope) + idx.registerSchemaAnchorAt(parse("$anchor: [a]"), 0, nil, scope) + idx.registerSchemaAnchorAt(parse("$anchor: 'a b'"), 0, nil, scope) truncated := parse("$anchor: a") truncated.Content = truncated.Content[:1] - idx.registerSchemaAnchorAt(truncated, 0, nil, "test.yaml") + idx.registerSchemaAnchorAt(truncated, 0, nil, scope) + // inside the $id resource at x-vendor/Thing, its default is data. + resource := NewSchemaIdScope("test.yaml") + resource.PushId("https://example.com/thing") + resource.resourceDepth = 2 + idx.registerSchemaAnchorAt(parse("$anchor: d"), 0, []string{"x-vendor", "Thing", "default"}, resource) assert.Empty(t, idx.schemaAnchorRegistry) - idx.registerSchemaAnchorAt(parse("$anchor: a"), 0, nil, "test.yaml") + idx.registerSchemaAnchorAt(parse("$anchor: a"), 0, nil, scope) require.Contains(t, idx.schemaAnchorRegistry, "test.yaml#a") assert.Equal(t, "#", idx.schemaAnchorRegistry["test.yaml#a"].DefinitionPath) + + // the extension holding the resource does not count, only the path within it. + idx.registerSchemaAnchorAt(parse("$anchor: s"), 0, []string{"x-vendor", "Thing", "$defs", "S"}, resource) + require.Contains(t, idx.schemaAnchorRegistry, "https://example.com/thing#s") + assert.Equal(t, "#/x-vendor/Thing/$defs/S", idx.schemaAnchorRegistry["https://example.com/thing#s"].DefinitionPath) } // "#foo" inside an external file names an anchor in that file, not in the root document. diff --git a/index/schema_anchor_values_test.go b/index/schema_anchor_values_test.go new file mode 100644 index 00000000..3629b2d2 --- /dev/null +++ b/index/schema_anchor_values_test.go @@ -0,0 +1,220 @@ +// Copyright 2023-2026 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package index + +import ( + "testing" + + "github.com/pb33f/go-yaml" + "github.com/pb33f/testify/assert" + "github.com/pb33f/testify/require" +) + +// an $anchor inside an instance value is data, not a declaration, so it must not claim the name +// before the schema that declares it. +func TestSchemaAnchorInInstanceValues(t *testing.T) { + const spec = `openapi: 3.1.0 +info: {title: anchors, version: '1'} +paths: + /p: + get: + responses: + default: + description: a response named default + content: + application/json: + schema: {$anchor: defaultResponse, type: string} + examples: + Sample: + value: {$anchor: viaMediaExample, type: integer} +x-root: {$anchor: viaRootExtension, type: integer} +components: + x-ext: + Store: {$anchor: viaComponentsExtension, type: integer} + schemas: + AnchorPayloads: + type: object + default: {$anchor: viaDefault, type: integer} + const: {$anchor: viaConst, type: integer} + enum: + - {$anchor: viaEnum, type: integer} + examples: + - {$anchor: viaExamples, type: integer} + x-data: {$anchor: viaExtension, type: integer} + MergedPayloads: + <<: {default: {$anchor: viaMergedDefault, type: integer}} + type: object + Default: {$anchor: viaDefault, type: string} + Const: {$anchor: viaConst, type: string} + Enum: {$anchor: viaEnum, type: string} + Examples: {$anchor: viaExamples, type: string} + Extension: {$anchor: viaExtension, type: string} + MediaExample: {$anchor: viaMediaExample, type: string} + RootExtension: {$anchor: viaRootExtension, type: string} + ComponentsExtension: {$anchor: viaComponentsExtension, type: string} + MergedDefault: {$anchor: viaMergedDefault, type: string} + Named: + properties: + x-named: {$anchor: namedProperty, type: string} + default: {$anchor: defaultProperty, type: string} + enum: {$id: 'https://example.com/enumProperty', type: string} + x-Named: + properties: + id: {$id: 'https://example.com/namedComponent', type: string} + x-named: {$anchor: namedPropertyOfNamedComponent, type: string} + default: {$anchor: defaultComponent, type: string} +` + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(spec), &root)) + cfg := CreateClosedAPIIndexConfig() + cfg.SpecAbsolutePath = "/specs/root.yaml" + idx := NewSpecIndexWithConfig(&root, cfg) + + for _, ref := range []string{ + "#viaDefault", "#viaConst", "#viaEnum", "#viaExamples", "#viaExtension", + "#viaMediaExample", "#viaRootExtension", "#viaComponentsExtension", "#viaMergedDefault", + } { + resolved := idx.ResolveRefViaSchemaId(ref) + require.NotNil(t, resolved, ref) + assert.Equal(t, "string", schemaNodeType(resolved.Node), ref) + } + + // a component, property or response may be named "default" or "x-...": that is a name, not + // a value or an extension. + for ref, definition := range map[string]string{ + "#namedProperty": "#/components/schemas/Named/properties/x-named", + "#defaultProperty": "#/components/schemas/Named/properties/default", + "https://example.com/enumProperty": "#/components/schemas/Named/properties/enum", + "https://example.com/namedComponent": "#/components/schemas/x-Named/properties/id", + "#namedPropertyOfNamedComponent": "#/components/schemas/x-Named/properties/x-named", + "#defaultComponent": "#/components/schemas/default", + "#defaultResponse": "#/paths/~1p/get/responses/default/content/application~1json/schema", + } { + resolved := idx.ResolveRefViaSchemaId(ref) + require.NotNil(t, resolved, ref) + assert.Equal(t, "string", schemaNodeType(resolved.Node), ref) + assert.Equal(t, definition, resolved.Definition, ref) + } +} + +// in a sequence such as required, "$anchor" and "$id" are entries, not keys, so the entry after +// them is not an identifier. +func TestSchemaIdentifierInSequence(t *testing.T) { + const spec = `openapi: 3.1.0 +info: {title: t, version: '1'} +paths: {} +components: + schemas: + Thing: + type: object + required: [$anchor, kind, $id, 'https://example.com/thing'] + properties: + $anchor: {type: string} + kind: {type: string} + $id: {type: string} + Ref: + $ref: '#kind' +` + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(spec), &root)) + cfg := CreateClosedAPIIndexConfig() + cfg.SpecAbsolutePath = "/specs/root.yaml" + idx := NewSpecIndexWithConfig(&root, cfg) + + assert.Nil(t, idx.ResolveRefViaSchemaId("#kind")) + assert.NotContains(t, idx.GetAllSchemaIds(), "https://example.com/thing") +} + +// a schema declared under an extension, where its $anchor declares nothing, and aliased into +// components is anchored there. +func TestSchemaAnchorAliasedFromDataToSchema(t *testing.T) { + const spec = `openapi: 3.1.0 +info: {title: t, version: '1'} +x-templates: + Str: &str + $anchor: str + type: string +paths: {} +components: + schemas: + Str: *str + Uses: + type: object + properties: + s: {$ref: '#str'} +` + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(spec), &root)) + cfg := CreateClosedAPIIndexConfig() + cfg.SpecAbsolutePath = "/specs/root.yaml" + idx := NewSpecIndexWithConfig(&root, cfg) + assert.Empty(t, idx.GetReferenceIndexErrors()) + + anchor := idx.schemaAnchorRegistry["/specs/root.yaml#str"] + require.NotNil(t, anchor) + assert.Equal(t, "#/components/schemas/Str", anchor.DefinitionPath) + resolved := idx.ResolveRefViaSchemaId("#str") + require.NotNil(t, resolved) + assert.Equal(t, "string", schemaNodeType(resolved.Node)) +} + +// an $anchor in an $id resource is judged by its path from the mapping that holds the $id, +// whether or not that $id registers. Under an $id at the document root, the document's own rules +// still apply. +func TestSchemaAnchorResourceDepth(t *testing.T) { + build := func(spec string) *SpecIndex { + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(spec), &root)) + cfg := CreateClosedAPIIndexConfig() + cfg.SpecAbsolutePath = "/specs/root.yaml" + return NewSpecIndexWithConfig(&root, cfg) + } + path := func(t *testing.T, idx *SpecIndex, uri string) string { + entry := idx.schemaAnchorRegistry[uri] + require.NotNil(t, entry, uri) + return entry.DefinitionPath + } + + t.Run("document root", func(t *testing.T) { + idx := build(`$id: 'https://example.com/root' +$defs: + S: {$anchor: s, type: string} +x-ext: + E: {$anchor: e, type: integer} +`) + assert.Equal(t, "#/$defs/S", path(t, idx, "https://example.com/root#s")) + assert.NotContains(t, idx.schemaAnchorRegistry, "https://example.com/root#e") + }) + + t.Run("duplicate $id", func(t *testing.T) { + idx := build(`components: + schemas: + First: {$id: 'https://example.com/dup', $defs: {A: {$anchor: a, type: string}}} +x-vendor: + Second: + $id: 'https://example.com/dup' + default: {$anchor: d, type: integer} + $defs: + B: {$anchor: b, type: integer} +`) + assert.Equal(t, "#/components/schemas/First", idx.GetSchemaById("https://example.com/dup").DefinitionPath) + assert.Equal(t, "#/components/schemas/First/$defs/A", path(t, idx, "https://example.com/dup#a")) + assert.Equal(t, "#/x-vendor/Second/$defs/B", path(t, idx, "https://example.com/dup#b")) + assert.NotContains(t, idx.schemaAnchorRegistry, "https://example.com/dup#d") + }) + + t.Run("refused $id", func(t *testing.T) { + // an $id holding a fragment is not registered, but it is still the base its anchors join. + idx := build(`x-vendor: + Bad: + $id: 'https://example.com/bad#frag' + default: {$anchor: d, type: integer} + $defs: + C: {$anchor: c, type: string} +`) + assert.Nil(t, idx.GetSchemaById("https://example.com/bad#frag")) + assert.Equal(t, "#/x-vendor/Bad/$defs/C", path(t, idx, "https://example.com/bad#frag#c")) + assert.NotContains(t, idx.schemaAnchorRegistry, "https://example.com/bad#frag#d") + }) +} diff --git a/index/schema_id_resolve.go b/index/schema_id_resolve.go index bae242dd..050578d0 100644 --- a/index/schema_id_resolve.go +++ b/index/schema_id_resolve.go @@ -204,8 +204,8 @@ func (index *SpecIndex) ResolveRefViaSchemaId(ref string) *Reference { baseUri, fragment := SplitRefFragment(ref) - if isSchemaAnchorFragment(fragment) { - if resolved := index.resolveRefViaSchemaAnchor(ref, baseUri, fragment); resolved != nil { + if name, ok := schemaAnchorFragmentName(fragment); ok { + if resolved := index.resolveRefViaSchemaAnchor(ref, baseUri, name); resolved != nil { return resolved } } diff --git a/index/schema_id_types.go b/index/schema_id_types.go index 4e80d825..70b16b6f 100644 --- a/index/schema_id_types.go +++ b/index/schema_id_types.go @@ -34,6 +34,10 @@ func (e *SchemaIdEntry) GetKey() string { type SchemaIdScope struct { BaseUri string // Current base URI for relative $id and $ref resolution Chain []string // Stack of $id URIs from root to current location + + // resourceDepth is the length of the JSON pointer to the mapping holding the innermost $id the + // extract-refs walk has entered, or 0 at the document root or outside any $id. + resourceDepth int } // NewSchemaIdScope initializes scope tracking for base URI resolution during schema tree traversal. @@ -67,7 +71,8 @@ func (s *SchemaIdScope) Copy() *SchemaIdScope { chainCopy := make([]string, len(s.Chain)) copy(chainCopy, s.Chain) return &SchemaIdScope{ - BaseUri: s.BaseUri, - Chain: chainCopy, + BaseUri: s.BaseUri, + Chain: chainCopy, + resourceDepth: s.resourceDepth, } } diff --git a/index/schema_identifier_path.go b/index/schema_identifier_path.go new file mode 100644 index 00000000..637927c6 --- /dev/null +++ b/index/schema_identifier_path.go @@ -0,0 +1,76 @@ +// Copyright 2023-2026 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package index + +import ( + "strings" +) + +// schemaPointer joins path segments into a local JSON pointer. +func schemaPointer(path []string) string { + if len(path) == 0 { + return "#" + } + return "#/" + strings.Join(path, "/") +} + +// underSchemaDataPath reports whether path, the pointer segments to a schema, runs through a value +// that is data rather than schema, where an $anchor declares nothing: an example, the value of +// enum, const or default, a Link Object's parameter values or request body, or a specification +// extension. A segment is data only where it is a field name; a property, component or response +// named "default" or "x-foo" is a name. When inSchema is set, path starts at a schema, the root of +// an $id resource, and only the schema's own keywords apply. +func underSchemaDataPath(path []string, inSchema bool) bool { + // slotField is the field whose map the next segment names an entry of, and link is set when the + // previous segment named a Link Object. + slotField, link := "", false + for i, segment := range path { + if slotField != "" { + field := slotField + slotField = "" + // an operation's Responses Object may carry extensions beside its status codes. Neither + // components/responses nor Swagger 2.0's root responses (here i is 1) may. + if field == "responses" && i > 1 && strings.HasPrefix(segment, "x-") { + return true + } + link = field == "links" + continue + } + if link { + link = false + if segment == "parameters" || segment == "requestBody" { + return true + } + } + switch segment { + case "example", "examples", "enum", "const", "default": + return true + } + if strings.HasPrefix(segment, "x-") { + return true + } + if !inSchema && i == 1 && path[0] == "components" { + // a component name. components/links holds Link Objects, as a response's links does. + slotField = "components/" + segment + if segment == "links" { + slotField = segment + } + continue + } + switch segment { + case "properties", "patternProperties", "definitions", "$defs", "dependentSchemas", "dependencies": + slotField = segment + case "headers", "links", "callbacks", "content", "encoding", "webhooks", "responses": + if !inSchema { + slotField = segment + } + case "parameters": + // Swagger 2.0 keeps reusable parameters in a root map. Elsewhere it is an array. + if !inSchema && i == 0 { + slotField = segment + } + } + } + return false +}