Add underOpenAPIExamplePath function to filter schema IDs in examples

- Introduced underOpenAPIExamplePath function to determine if a path is under OpenAPI example or examples payload.
- Updated ExtractRefs method to skip processing nodes under example paths.
- Added tests to ensure schema IDs in examples are not registered, confirming correct behavior for both example and examples payloads.

Author: luke-hagar-sp

index/extract_refs.go

@@ -57,6 +57,12 @@ 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.
+func underOpenAPIExamplePath(seenPath []string) bool {
+	return slices.Contains(seenPath, "example") || slices.Contains(seenPath, "examples")
+}
+
 // ExtractRefs will return a deduplicated slice of references for every unique ref found in the document.
 // The total number of refs, will generally be much higher, you can extract those from GetRawReferenceCount()
 func (index *SpecIndex) ExtractRefs(ctx context.Context, node, parent *yaml.Node, seenPath []string, level int, poly bool, pName string) []*Reference {
@@ -77,7 +83,7 @@ func (index *SpecIndex) ExtractRefs(ctx context.Context, node, parent *yaml.Node
 
 	// Check if THIS node has a $id and update scope for processing children
 	// This must happen before iterating children so they see the updated scope
-	if node.Kind == yaml.MappingNode {
+	if node.Kind == yaml.MappingNode && !underOpenAPIExamplePath(seenPath) {
 		if nodeId := FindSchemaIdInNode(node); nodeId != "" {
 			resolvedNodeId, _ := ResolveSchemaId(nodeId, parentBaseUri)
 			if resolvedNodeId == "" {
@@ -557,6 +563,9 @@ func (index *SpecIndex) ExtractRefs(ctx context.Context, node, parent *yaml.Node
 
 			// Detect and register JSON Schema 2020-12 $id declarations
 			if i%2 == 0 && n.Value == "$id" {
+				if underOpenAPIExamplePath(seenPath) {
+					continue
+				}
 				if len(node.Content) > i+1 && utils.IsNodeStringValue(node.Content[i+1]) {
 					idValue := node.Content[i+1].Value
 					idNode := node.Content[i+1]

index/schema_id_test.go

@@ -750,6 +750,118 @@ components:
 	assert.Contains(t, petEntry.DefinitionPath, "Pet")
 }
 
+func TestSchemaId_IgnoredUnderExampleAndExamples(t *testing.T) {
+	t.Run("example_payload", 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:
+                  id:
+                    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, 1)
+		assert.NotNil(t, allIds["https://example.com/schemas/pet.json"])
+		assert.Nil(t, allIds["https://example.com/should-not-register"])
+	})
+
+	t.Run("examples_named_value", func(t *testing.T) {
+		spec := `openapi: "3.1.0"
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /widgets:
+    get:
+      responses:
+        "200":
+          description: ok
+          content:
+            application/json:
+              schema:
+                $id: "https://example.com/schemas/widget.json"
+                type: object
+                examples:
+                  sample:
+                    value:
+                      $id: "https://example.com/fake-from-examples"
+                      foo: bar
+`
+		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/widget.json"])
+		assert.Nil(t, allIds["https://example.com/fake-from-examples"])
+	})
+
+	t.Run("invalid_id_in_example_no_index_error", func(t *testing.T) {
+		spec := `openapi: "3.1.0"
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /x:
+    get:
+      responses:
+        "200":
+          description: ok
+          content:
+            application/json:
+              schema:
+                type: object
+                example:
+                  $id: "https://bad.com/schema#fragment"
+                  k: v
+`
+		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)
+
+		assert.Len(t, index.GetAllSchemaIds(), 0)
+		for _, e := range index.GetReferenceIndexErrors() {
+			assert.False(t, strings.Contains(e.Error(), "invalid $id"),
+				"$id inside example must not be validated as schema $id: %v", e)
+		}
+	})
+}
+
 func TestSchemaId_ExtractionWithInvalidId(t *testing.T) {
 	// OpenAPI 3.1 spec with invalid $id (contains fragment)
 	spec := `openapi: "3.1.0"