From 7eae375d1b19a95cecbf3ff2de01265aab0bf04a Mon Sep 17 00:00:00 2001 From: Thomas Date: Thu, 12 Nov 2026 23:22:31 +1100 Subject: [PATCH] fix(index): treat $ref inside schema instance values as data 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. --- document_test.go | 33 +++++++++ index/extract_refs.go | 42 +++++++++++- index/extract_refs_ref.go | 2 +- index/extract_refs_test.go | 130 ++++++++++++++++++++++++++++++++++++ index/extract_refs_walk.go | 3 + index/resolver_relatives.go | 14 ++++ index/resolver_test.go | 65 ++++++++++++++++++ 7 files changed, 287 insertions(+), 2 deletions(-) diff --git a/document_test.go b/document_test.go index f5d7b9f2..ec6fae8c 100644 --- a/document_test.go +++ b/document_test.go @@ -2600,3 +2600,36 @@ func TestDocument_BuildV3Model_NoVersionNode(t *testing.T) { require.Error(t, buildErr) assert.Contains(t, buildErr.Error(), "no openapi version/tag found") } + +func TestDocument_BuildV3Model_RefInSchemaInstanceValue(t *testing.T) { + spec := `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 +` + doc, err := NewDocument([]byte(spec)) + require.NoError(t, err) + model, err := doc.BuildV3Model() + require.NoError(t, err) + + schema := model.Model.Components.Schemas.GetOrZero("Data").Schema() + var def map[string]string + require.NoError(t, schema.Default.Decode(&def)) + assert.Equal(t, map[string]string{"$ref": "#/components/schemas/Target"}, def, "default is data and is not inlined") + var con map[string]string + require.NoError(t, schema.Const.Decode(&con)) + assert.Equal(t, map[string]string{"$ref": "gone.yaml#/x"}, con) + require.Len(t, schema.Enum, 1) + require.Len(t, schema.Examples, 1) +} diff --git a/index/extract_refs.go b/index/extract_refs.go index 984bff0b..e5a9e2fc 100644 --- a/index/extract_refs.go +++ b/index/extract_refs.go @@ -57,6 +57,16 @@ func isOpenAPIExampleKeywordSegment(seenPath []string, idx int) bool { if seenPath[idx] != "example" && seenPath[idx] != "examples" { return false } + return isOpenAPIKeywordSegment(seenPath, idx) +} + +// isOpenAPIKeywordSegment reports whether seenPath[idx] is a field name rather than a name the +// document chose: a component, property, response code or Example Object name. A property named +// "default" or a response keyed "default" is a name; the "default" field of a schema is not. +func isOpenAPIKeywordSegment(seenPath []string, idx int) bool { + if idx < 0 || idx >= len(seenPath) { + return false + } // A component or schema name cannot itself introduce another named map. // For example, properties/definitions/example ends at a payload keyword. nameSlot := false @@ -71,13 +81,43 @@ func isOpenAPIExampleKeywordSegment(seenPath []string, idx int) bool { } switch segment { case "properties", "patternProperties", "definitions", "$defs", "dependentSchemas", - "headers", "links", "callbacks", "encoding", "webhooks": + "headers", "links", "callbacks", "encoding", "webhooks", "responses", "examples": nameSlot = true + case "parameters": + // Swagger 2.0 keeps reusable parameters in a root map. Elsewhere it is an array. + nameSlot = i == 0 } } return !nameSlot } +// underSchemaInstanceValuePath reports whether path, the location of node, is inside a value +// JSON Schema treats as instance data: the value of enum, const or default, or the examples array. +// A $ref key there is part of the data, not a reference. An OpenAPI examples field is a map of +// Example Objects, so examples counts only when it holds an array. The resolver marks array +// elements with "[]"; the index walk does not, so node, when not nil, is the value at path. +func underSchemaInstanceValuePath(path []string, node *yaml.Node) bool { + for i, segment := range path { + switch segment { + case "enum", "const", "default": + case "examples": + if i+1 < len(path) { + if path[i+1] != "[]" { + continue + } + } else if node == nil || !utils.IsNodeArray(node) { + continue + } + default: + continue + } + if isOpenAPIKeywordSegment(path, i) { + return true + } + } + return false +} + // underOpenAPIExamplePayloadPath reports whether seenPath points to raw example payload content. // A bare `example` path is not payload by itself because libopenapi still supports a direct // `$ref` wrapper there for bundling. Once traversal moves below `example`, or into an Example diff --git a/index/extract_refs_ref.go b/index/extract_refs_ref.go index 713e3026..3f35fb0b 100644 --- a/index/extract_refs_ref.go +++ b/index/extract_refs_ref.go @@ -26,7 +26,7 @@ func (index *SpecIndex) extractReferenceAt( if len(node.Content) <= keyIndex+1 { return nil } - if underOpenAPIExamplePayloadPath(seenPath) { + if underOpenAPIExamplePayloadPath(seenPath) || underSchemaInstanceValuePath(seenPath, nil) { return nil } diff --git a/index/extract_refs_test.go b/index/extract_refs_test.go index 271064bb..5c62735f 100644 --- a/index/extract_refs_test.go +++ b/index/extract_refs_test.go @@ -1270,3 +1270,133 @@ components: } } } + +func TestUnderSchemaInstanceValuePath(t *testing.T) { + var seq, mapping yaml.Node + require.NoError(t, yaml.Unmarshal([]byte("[{$ref: '#/a'}]"), &seq)) + require.NoError(t, yaml.Unmarshal([]byte("{named: {$ref: '#/a'}}"), &mapping)) + tests := []struct { + name string + path []string + node *yaml.Node + want bool + }{ + {"empty", nil, nil, false}, + {"enum", []string{"components", "schemas", "S", "enum"}, nil, true}, + {"const", []string{"components", "schemas", "S", "const"}, nil, true}, + {"default", []string{"components", "schemas", "S", "default"}, nil, true}, + {"below_default", []string{"components", "schemas", "S", "default", "nested"}, nil, true}, + {"items_enum", []string{"components", "schemas", "S", "items", "enum"}, nil, true}, + {"examples_array", []string{"components", "schemas", "S", "examples"}, seq.Content[0], true}, + {"examples_array_element", []string{"components", "schemas", "S", "examples", "[]"}, nil, true}, + {"examples_map", []string{"content", "application/json", "examples"}, mapping.Content[0], false}, + {"examples_unknown_node", []string{"components", "schemas", "S", "examples"}, nil, false}, + {"example_object_named_default", []string{"content", "application/json", "examples", "default"}, nil, false}, + {"schema_named_default", []string{"components", "schemas", "default"}, nil, false}, + {"property_named_default", []string{"components", "schemas", "S", "properties", "default"}, nil, false}, + {"property_named_enum", []string{"components", "schemas", "S", "properties", "enum"}, nil, false}, + {"property_named_const", []string{"components", "schemas", "S", "properties", "const"}, nil, false}, + {"default_response", []string{"paths", "~1pets", "get", "responses", "default"}, nil, false}, + {"default_of_property_named_default", []string{"components", "schemas", "S", "properties", "default", "default"}, nil, true}, + {"swagger_parameter_named_default", []string{"parameters", "default"}, nil, false}, + {"operation_parameter_schema_default", []string{"paths", "~1pets", "get", "parameters", "schema", "default"}, nil, true}, + {"default_response_schema_default", []string{"paths", "~1pets", "get", "responses", "default", "content", "application/json", "schema", "default"}, nil, true}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + assert.Equal(t, tt.want, underSchemaInstanceValuePath(tt.path, tt.node)) + }) + } +} + +func TestExtractReferenceAt_IgnoresRefsInsideSchemaInstanceValues(t *testing.T) { + idx := NewTestSpecIndex().Load().(*SpecIndex) + idx.specAbsolutePath = "test.yaml" + + var refNode yaml.Node + _ = yaml.Unmarshal([]byte(`$ref: '#/components/schemas/Pet'`), &refNode) + + ref := idx.extractReferenceAt(refNode.Content[0], nil, 0, []string{"components", "schemas", "S", "default"}, nil, false, "") + assert.Nil(t, ref) + assert.Empty(t, idx.GetAllReferences()) + assert.Empty(t, idx.GetAllSequencedReferences()) +} + +func TestSpecIndex_ExtractRefs_SchemaInstanceValueRefsIgnored(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Instance values + version: 1.0.0 +paths: + /pets: + get: + responses: + default: + $ref: '#/components/responses/Default' + "200": + description: ok + content: + application/json: + schema: + type: object + default: {$ref: '#/data/response-default'} + examples: + default: + $ref: '#/components/examples/Default' +components: + responses: + Default: + description: default + examples: + Default: + value: {ok: true} + schemas: + Data: + type: object + enum: + - {$ref: '#/data/enum'} + const: {$ref: '#/data/const'} + default: + nested: {$ref: '#/data/default'} + examples: + - {$ref: '#/data/examples'} + items: + enum: [{$ref: '#/data/items-enum'}] + Named: + type: object + properties: + default: {$ref: '#/components/schemas/Target'} + enum: {$ref: '#/components/schemas/Target'} + const: {$ref: '#/components/schemas/Target'} + examples: {$ref: '#/components/schemas/Target'} + default: + $ref: '#/components/schemas/Target' + Target: + type: string +` + + var rootNode yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(spec), &rootNode)) + + idx := NewSpecIndexWithConfig(&rootNode, CreateOpenAPIIndexConfig()) + + rawRefs := make(map[string]bool) + for _, ref := range idx.GetRawReferencesSequenced() { + rawRefs[ref.RawRef] = true + } + + assert.True(t, rawRefs["#/components/responses/Default"], "a response keyed default is a reference") + assert.True(t, rawRefs["#/components/examples/Default"], "an Example Object named default is a reference") + assert.True(t, rawRefs["#/components/schemas/Target"], "properties named default, enum, const and examples are schemas") + for raw := range rawRefs { + assert.False(t, strings.HasPrefix(raw, "#/data/"), "instance data indexed as a reference: %s", raw) + } + assert.Empty(t, idx.GetReferenceIndexErrors()) +} + +func TestIsOpenAPIKeywordSegment_OutOfRange(t *testing.T) { + path := []string{"components", "schemas", "S", "default"} + assert.False(t, isOpenAPIKeywordSegment(path, -1)) + assert.False(t, isOpenAPIKeywordSegment(path, len(path))) + assert.True(t, isOpenAPIKeywordSegment(path, 3)) +} diff --git a/index/extract_refs_walk.go b/index/extract_refs_walk.go index 02fd53c9..60be6144 100644 --- a/index/extract_refs_walk.go +++ b/index/extract_refs_walk.go @@ -102,6 +102,9 @@ func (index *SpecIndex) walkChildExtractRefs(node, parent *yaml.Node, state *ext if isDirectOpenAPIExampleValuePath(state.seenPath) && !isDirectOpenAPIExampleRefNode(node) { return nil } + if underSchemaInstanceValuePath(state.seenPath, node) { + return nil + } state.level++ if isPoly, _ := index.checkPolymorphicNode(state.prev); isPoly { state.poly = true diff --git a/index/resolver_relatives.go b/index/resolver_relatives.go index 41f1ea72..7fcbb65e 100644 --- a/index/resolver_relatives.go +++ b/index/resolver_relatives.go @@ -67,6 +67,9 @@ func (resolver *Resolver) extractRelativesWithState( if isDirectOpenAPIExampleValuePath(walkPath) && !isDirectOpenAPIExampleRefNode(node) { return nil } + if underSchemaInstanceValuePath(walkPath, node) { + return nil + } // Guard against stack overflow from deeply nested or circular specs. // Journey tracks the reference chain (100 max); depth tracks recursive calls (500 max). if len(state.journey) > 100 { @@ -92,6 +95,13 @@ func (resolver *Resolver) extractRelativesWithState( childPath := walkPath if node.Kind == yaml.MappingNode && i%2 == 1 { childPath = append(walkPath, node.Content[i-1].Value) + // The index does not extract references under excluded extensions, so the + // resolver must not look for them there either. A property named x-... is + // still a schema. + if resolver.excludeExtensionRefs() && strings.HasPrefix(childPath[len(childPath)-1], "x-") && + isOpenAPIKeywordSegment(childPath, len(childPath)-1) { + continue + } } else if node.Kind == yaml.SequenceNode { childPath = append(walkPath, "[]") } @@ -119,6 +129,10 @@ func (resolver *Resolver) extractRelativesWithState( return found } +func (resolver *Resolver) excludeExtensionRefs() bool { + return resolver.specIndex != nil && resolver.specIndex.config != nil && resolver.specIndex.config.ExcludeExtensionRefs +} + func (resolver *Resolver) handleRelativeDepthLimit(ref *Reference, state relativeWalkState) []*Reference { def := "unknown" if ref != nil { diff --git a/index/resolver_test.go b/index/resolver_test.go index 04a41a93..6923049a 100644 --- a/index/resolver_test.go +++ b/index/resolver_test.go @@ -2089,3 +2089,68 @@ func TestResolverDeepExamplePaths(t *testing.T) { require.Len(t, found, 1) require.Equal(t, "#/components/schemas/Target", found[0].Definition) } + +func TestResolver_SchemaInstanceValueRefsNotResolved(t *testing.T) { + spec := `openapi: 3.1.0 +components: + schemas: + Data: + type: object + enum: + - {$ref: '#/missing/enum'} + const: {$ref: 'missing.yaml#/const'} + default: + nested: {$ref: '#/missing/default'} + examples: + - {$ref: '#/missing/examples'} + properties: + default: {$ref: '#/components/schemas/Target'} + Target: + type: string +` + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(spec), &root)) + idx := NewSpecIndexWithConfig(&root, CreateOpenAPIIndexConfig()) + ref, _ := idx.SearchIndexForReference("#/components/schemas/Data") + require.NotNil(t, ref) + found := NewResolver(idx).extractRelatives(ref, ref.Node, nil, map[string]bool{}, nil, false, 0, "") + require.Len(t, found, 1, "only the property named default is a reference") + require.Equal(t, "#/components/schemas/Target", found[0].Definition) + + require.Empty(t, NewResolver(idx).Resolve()) +} + +func TestResolver_ExcludeExtensionRefs(t *testing.T) { + spec := `openapi: 3.1.0 +components: + schemas: + Pasta: + type: object + x-hello: + thing: {$ref: 'gone.yaml#/x'} + properties: + x-name: {$ref: '#/components/schemas/Target'} + Target: + type: string +` + for _, exclude := range []bool{false, true} { + t.Run(fmt.Sprintf("exclude=%v", exclude), func(t *testing.T) { + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(spec), &root)) + c := CreateOpenAPIIndexConfig() + c.ExcludeExtensionRefs = exclude + idx := NewSpecIndexWithConfig(&root, c) + ref, _ := idx.SearchIndexForReference("#/components/schemas/Pasta") + require.NotNil(t, ref) + resolver := NewResolver(idx) + found := resolver.extractRelatives(ref, ref.Node, nil, map[string]bool{}, nil, false, 0, "") + require.Len(t, found, 1, "a property named x-name is a schema") + require.Equal(t, "#/components/schemas/Target", found[0].Definition) + if exclude { + require.Empty(t, resolver.resolvingErrors) + } else { + require.Len(t, resolver.resolvingErrors, 1) + } + }) + } +}