Fix underOpenAPIExamplePath to distinguish property names from OpenAPI keywords

The previous implementation matched any path segment named "example" or
"examples", which incorrectly suppressed $id extraction for schemas under
properties with those names. Now checks the preceding segment — if it is
"properties" or "patternProperties", the segment is a property name and
not an OpenAPI example keyword.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

index/extract_refs.go

@@ -11,7 +11,6 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
-	"slices"
 	"sort"
 	"strconv"
 	"strings"
@@ -57,10 +56,18 @@ func isArrayOfSchemaContainingNode(v string) bool {
 	return false
 }
 
-// underOpenAPIExamplePath reports whether seenPath is under OpenAPI example or examples payload
-// (sample data, not schema). Matches description/summary and properties skipping in this file.
+// underOpenAPIExamplePath reports whether seenPath is under an OpenAPI example or examples
+// keyword (sample data, not schema). A segment named "example" or "examples" that is preceded
+// by "properties" or "patternProperties" is a schema property name, not an OpenAPI keyword.
 func underOpenAPIExamplePath(seenPath []string) bool {
-	return slices.Contains(seenPath, "example") || slices.Contains(seenPath, "examples")
+	for i, p := range seenPath {
+		if p == "example" || p == "examples" {
+			if i == 0 || (seenPath[i-1] != "properties" && seenPath[i-1] != "patternProperties") {
+				return true
+			}
+		}
+	}
+	return false
 }
 
 // ExtractRefs will return a deduplicated slice of references for every unique ref found in the document.
@@ -176,11 +183,13 @@ func (index *SpecIndex) ExtractRefs(ctx context.Context, node, parent *yaml.Node
 				if len(seenPath) > 0 {
 					skip := false
 
-					// iterate through the path and look for an item named 'examples' or 'example'
-					for _, p := range seenPath {
+					// iterate through the path and look for an OpenAPI example/examples keyword or extension
+					for j, p := range seenPath {
 						if p == "examples" || p == "example" {
-							skip = true
-							break
+							if j == 0 || (seenPath[j-1] != "properties" && seenPath[j-1] != "patternProperties") {
+								skip = true
+								break
+							}
 						}
 						// look for any extension in the path and ignore it
 						if strings.HasPrefix(p, "x-") {
@@ -670,7 +679,7 @@ func (index *SpecIndex) ExtractRefs(ctx context.Context, node, parent *yaml.Node
 						prev = n.Value
 						continue
 					}
-					if !slices.Contains(seenPath, "example") && !slices.Contains(seenPath, "examples") {
+					if !underOpenAPIExamplePath(seenPath) {
 						ref := &DescriptionReference{
 							ParentNode: parent,
 							Content:    node.Content[i+1].Value,
@@ -699,7 +708,7 @@ func (index *SpecIndex) ExtractRefs(ctx context.Context, node, parent *yaml.Node
 						continue
 					}
 
-					if slices.Contains(seenPath, "example") || slices.Contains(seenPath, "examples") {
+					if underOpenAPIExamplePath(seenPath) {
 						continue
 					}
 

index/extract_refs_test.go

@@ -723,6 +723,11 @@ func TestUnderOpenAPIExamplePath(t *testing.T) {
 		{"under_example", []string{"paths", "get", "responses", "200", "content", "application/json", "schema", "example"}, true},
 		{"under_examples", []string{"content", "application/json", "schema", "examples", "sample", "value"}, true},
 		{"example_not_whole_segment", []string{"paths", "exampled"}, false},
+		{"example_as_property_name", []string{"components", "schemas", "Foo", "properties", "example"}, false},
+		{"examples_as_property_name", []string{"components", "schemas", "Foo", "properties", "examples"}, false},
+		{"nested_under_property_example", []string{"components", "schemas", "Foo", "properties", "example", "properties", "id"}, false},
+		{"patternProperties_example", []string{"components", "schemas", "Foo", "patternProperties", "example"}, false},
+		{"real_example_after_property_example", []string{"components", "schemas", "Foo", "properties", "example", "example"}, true},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

index/schema_id_test.go

@@ -862,6 +862,112 @@ paths:
 	})
 }
 
+func TestSchemaId_NotIgnoredUnderPropertiesExample(t *testing.T) {
+	t.Run("property_named_example", func(t *testing.T) {
+		spec := `openapi: "3.1.0"
+info:
+  title: Test API
+  version: 1.0.0
+components:
+  schemas:
+    MySchema:
+      $id: "https://example.com/schemas/myschema.json"
+      type: object
+      properties:
+        example:
+          $id: "https://example.com/schemas/example-prop.json"
+          type: object
+          properties:
+            id:
+              type: string
+`
+		var rootNode yaml.Node
+		err := yaml.Unmarshal([]byte(spec), &rootNode)
+		assert.NoError(t, err)
+
+		config := CreateClosedAPIIndexConfig()
+		config.SpecAbsolutePath = "https://example.com/openapi.yaml"
+		index := NewSpecIndexWithConfig(&rootNode, config)
+		assert.NotNil(t, index)
+
+		allIds := index.GetAllSchemaIds()
+		assert.Len(t, allIds, 2)
+		assert.NotNil(t, allIds["https://example.com/schemas/myschema.json"])
+		assert.NotNil(t, allIds["https://example.com/schemas/example-prop.json"])
+	})
+
+	t.Run("property_named_examples", func(t *testing.T) {
+		spec := `openapi: "3.1.0"
+info:
+  title: Test API
+  version: 1.0.0
+components:
+  schemas:
+    MySchema:
+      type: object
+      properties:
+        examples:
+          $id: "https://example.com/schemas/examples-prop.json"
+          type: object
+          properties:
+            list:
+              type: array
+`
+		var rootNode yaml.Node
+		err := yaml.Unmarshal([]byte(spec), &rootNode)
+		assert.NoError(t, err)
+
+		config := CreateClosedAPIIndexConfig()
+		config.SpecAbsolutePath = "https://example.com/openapi.yaml"
+		index := NewSpecIndexWithConfig(&rootNode, config)
+		assert.NotNil(t, index)
+
+		allIds := index.GetAllSchemaIds()
+		assert.Len(t, allIds, 1)
+		assert.NotNil(t, allIds["https://example.com/schemas/examples-prop.json"])
+	})
+
+	t.Run("real_example_still_ignored", func(t *testing.T) {
+		spec := `openapi: "3.1.0"
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /pets:
+    get:
+      responses:
+        "200":
+          description: ok
+          content:
+            application/json:
+              schema:
+                $id: "https://example.com/schemas/pet.json"
+                type: object
+                properties:
+                  example:
+                    $id: "https://example.com/schemas/example-prop.json"
+                    type: string
+                example:
+                  $id: "https://example.com/should-not-register"
+                  id: "1"
+`
+		var rootNode yaml.Node
+		err := yaml.Unmarshal([]byte(spec), &rootNode)
+		assert.NoError(t, err)
+
+		config := CreateClosedAPIIndexConfig()
+		config.SpecAbsolutePath = "https://example.com/openapi.yaml"
+		index := NewSpecIndexWithConfig(&rootNode, config)
+		assert.NotNil(t, index)
+
+		allIds := index.GetAllSchemaIds()
+		assert.Len(t, allIds, 2)
+		assert.NotNil(t, allIds["https://example.com/schemas/pet.json"])
+		assert.NotNil(t, allIds["https://example.com/schemas/example-prop.json"])
+		assert.Nil(t, allIds["https://example.com/should-not-register"])
+	})
+}
+
 func TestSchemaId_ExtractionWithInvalidId(t *testing.T) {
 	// OpenAPI 3.1 spec with invalid $id (contains fragment)
 	spec := `openapi: "3.1.0"