Fix example indexing, clean up rendering, add coverage.

Author: daveshanley

bundler/bundler.go

@@ -28,6 +28,28 @@ import (
 // ErrInvalidModel is returned when the model is not usable.
 var ErrInvalidModel = errors.New("invalid model")
 
+type invalidModelBuildError struct {
+	cause error
+}
+
+func (e *invalidModelBuildError) Error() string {
+	if e == nil || e.cause == nil {
+		return ErrInvalidModel.Error()
+	}
+	return e.cause.Error()
+}
+
+func (e *invalidModelBuildError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.cause
+}
+
+func (e *invalidModelBuildError) Is(target error) bool {
+	return target == ErrInvalidModel
+}
+
 // buildV3ModelFromBytes is a helper that parses bytes and builds a v3 model.
 // Returns the model and any build errors. The model may be non-nil even when err is non-nil
 // (e.g., circular reference warnings), allowing bundling to proceed with warnings.
@@ -39,7 +61,7 @@ func buildV3ModelFromBytes(bytes []byte, configuration *datamodel.DocumentConfig
 
 	v3Doc, buildErr := doc.BuildV3Model()
 	if v3Doc == nil {
-		return nil, errors.Join(ErrInvalidModel, buildErr)
+		return nil, &invalidModelBuildError{cause: buildErr}
 	}
 	// Return both model and error - caller decides how to handle warnings/errors
 	return &v3Doc.Model, buildErr
@@ -76,7 +98,7 @@ func BundleBytesComposed(bytes []byte, configuration *datamodel.DocumentConfigur
 
 	v3Doc, err := doc.BuildV3Model()
 	if err != nil {
-		return nil, errors.Join(ErrInvalidModel, err)
+		return nil, &invalidModelBuildError{cause: err}
 	}
 
 	bundledBytes, e := compose(&v3Doc.Model, compositionConfig)
@@ -93,7 +115,7 @@ func BundleBytesComposedWithOrigins(bytes []byte, configuration *datamodel.Docum
 
 	v3Doc, err := doc.BuildV3Model()
 	if err != nil {
-		return nil, errors.Join(ErrInvalidModel, err)
+		return nil, &invalidModelBuildError{cause: err}
 	}
 
 	result, e := composeWithOrigins(&v3Doc.Model, compositionConfig)

bundler/bundler_test.go

@@ -416,12 +416,10 @@ components:
 	_, e := BundleBytes(digi, config)
 	require.Error(t, e)
 	unwrap := utils.UnwrapErrors(e)
-	require.Len(t, unwrap, 2)
+	require.Len(t, unwrap, 1)
 	assert.ErrorIs(t, unwrap[0], ErrInvalidModel)
-	unwrapNext := utils.UnwrapErrors(unwrap[1])
-	require.Len(t, unwrapNext, 2)
-	assert.Equal(t, "component `bork` does not exist in the specification", unwrapNext[0].Error())
-	assert.Equal(t, "cannot resolve reference `bork`, it's missing: $.bork [5:7]", unwrapNext[1].Error())
+	assert.Equal(t, "component `bork` does not exist in the specification\ncannot resolve reference `bork`, it's missing: $.bork [5:7]", unwrap[0].Error())
+	assert.NotContains(t, unwrap[0].Error(), "invalid model")
 
 	logEntries := strings.Split(byteBuf.String(), "\n")
 	if len(logEntries) == 1 && logEntries[0] == "" {
@@ -1799,6 +1797,20 @@ paths: {}`)
 	assert.Contains(t, err.Error(), "different version")
 }
 
+func TestBundleBytesComposedWithOrigins_InvalidModel(t *testing.T) {
+	swagger2Spec := []byte(`swagger: "2.0"
+info:
+  title: Test API
+  version: 1.0.0
+paths: {}`)
+
+	_, err := BundleBytesComposedWithOrigins(swagger2Spec, nil, nil)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, ErrInvalidModel)
+	assert.Contains(t, err.Error(), "different version")
+	assert.NotContains(t, err.Error(), "invalid model")
+}
+
 // TestBundleBytesWithConfig_BackwardCompatibility tests that existing behavior is preserved
 // when ResolveDiscriminatorExternalRefs is not enabled.
 func TestBundleBytesWithConfig_BackwardCompatibility(t *testing.T) {

index/extract_refs.go

@@ -38,10 +38,43 @@ func isArrayOfSchemaContainingNode(v string) bool {
 // 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 {
-	for i, p := range seenPath {
-		if p == "example" || p == "examples" {
-			if i == 0 || (seenPath[i-1] != "properties" && seenPath[i-1] != "patternProperties") {
-				return true
+	for i := range seenPath {
+		if isOpenAPIExampleKeywordSegment(seenPath, i) {
+			return true
+		}
+	}
+	return false
+}
+
+func isOpenAPIExampleKeywordSegment(seenPath []string, idx int) bool {
+	if idx < 0 || idx >= len(seenPath) {
+		return false
+	}
+	switch seenPath[idx] {
+	case "example", "examples":
+		return idx == 0 || (seenPath[idx-1] != "properties" && seenPath[idx-1] != "patternProperties")
+	default:
+		return false
+	}
+}
+
+// underOpenAPIExamplePayloadPath reports whether seenPath points to raw example payload content,
+// not the Example Object itself. This lets the walker keep traversing legitimate Example Objects
+// for $ref values while still skipping sample data under example/value/dataValue.
+func underOpenAPIExamplePayloadPath(seenPath []string) bool {
+	for i := range seenPath {
+		if !isOpenAPIExampleKeywordSegment(seenPath, i) {
+			continue
+		}
+		switch seenPath[i] {
+		case "example":
+			return true
+		case "examples":
+			if len(seenPath) > i+2 {
+				switch seenPath[i+2] {
+				case "value", "dataValue":
+					return true
+				}
 			}
 		}
 	}

index/extract_refs_ref.go

@@ -27,6 +27,9 @@ func (index *SpecIndex) extractReferenceAt(
 	if len(node.Content) <= keyIndex+1 {
 		return nil
 	}
+	if underOpenAPIExamplePayloadPath(seenPath) {
+		return nil
+	}
 
 	isExtensionPath := false
 	for _, spi := range seenPath {

index/extract_refs_test.go

@@ -737,6 +737,31 @@ func TestUnderOpenAPIExamplePath(t *testing.T) {
 	}
 }
 
+func TestUnderOpenAPIExamplePayloadPath(t *testing.T) {
+	tests := []struct {
+		name string
+		path []string
+		want bool
+	}{
+		{"empty", nil, false},
+		{"example_payload", []string{"paths", "get", "responses", "200", "content", "application/json", "schema", "example"}, true},
+		{"nested_under_example_payload", []string{"components", "schemas", "Foo", "example", "nested"}, true},
+		{"examples_collection", []string{"components", "examples"}, false},
+		{"example_object_entry", []string{"components", "examples", "ReusableExample"}, false},
+		{"examples_value_payload", []string{"content", "application/json", "examples", "sample", "value"}, true},
+		{"examples_value_nested_payload", []string{"content", "application/json", "examples", "sample", "value", "nested"}, true},
+		{"examples_data_value_payload", []string{"components", "examples", "sample", "dataValue"}, true},
+		{"property_named_example", []string{"components", "schemas", "Foo", "properties", "example"}, false},
+		{"property_named_examples_value", []string{"components", "schemas", "Foo", "properties", "examples", "value"}, 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) {
+			assert.Equal(t, tt.want, underOpenAPIExamplePayloadPath(tt.path))
+		})
+	}
+}
+
 func TestExtractRefs_InlineSchemaHelpers(t *testing.T) {
 	idx := NewTestSpecIndex().Load().(*SpecIndex)
 	idx.specAbsolutePath = "test.yaml"
@@ -961,4 +986,87 @@ func TestExtractRefs_WalkHelpers(t *testing.T) {
 	assert.False(t, shouldSkipMapSchemaCollection([]string{"properties", "example"}))
 	assert.False(t, shouldSkipMapSchemaCollection([]string{"patternProperties", "example"}))
 	assert.True(t, shouldSkipMapSchemaCollection([]string{"x-test"}))
+
+	var noAppendNode yaml.Node
+	_ = yaml.Unmarshal([]byte("summary: hello\nvalue: world"), &noAppendNode)
+	state.seenPath = []string{"components", "examples", "sample"}
+	state.lastAppended = false
+	idx.unwindExtractRefsPath(noAppendNode.Content[0], &state, 1)
+	assert.Equal(t, []string{"components", "examples", "sample"}, state.seenPath)
+
+	var appendNode yaml.Node
+	_ = yaml.Unmarshal([]byte("value: hello\nnext: world"), &appendNode)
+	state.lastAppended = true
+	idx.unwindExtractRefsPath(appendNode.Content[0], &state, 1)
+	assert.Equal(t, []string{"components", "examples"}, state.seenPath)
+	assert.False(t, state.lastAppended)
+}
+
+func TestExtractReferenceAt_IgnoresRefsInsideExamplePayloads(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", "examples", "sample", "value"}, nil, false, "")
+	assert.Nil(t, ref)
+	assert.Empty(t, idx.GetAllReferences())
+	assert.Empty(t, idx.GetAllSequencedReferences())
+}
+
+func TestSpecIndex_ExtractRefs_ExampleObjectRefsIndexedButPayloadRefsIgnored(t *testing.T) {
+	spec := `openapi: 3.2.0
+info:
+  title: Example refs
+  version: 1.0.0
+paths:
+  /widgets:
+    get:
+      responses:
+        "200":
+          description: ok
+          content:
+            application/json:
+              examples:
+                responseRef:
+                  $ref: '#/components/examples/ReusableExample'
+                inlinePayload:
+                  summary: payload example
+                  value:
+                    nested:
+                      $ref: '#/components/schemas/ShouldNotIndex'
+components:
+  examples:
+    ReusableExample:
+      $ref: '#/components/examples/LeafExample'
+    LeafExample:
+      summary: reusable
+      value:
+        ok: true
+    DataValueExample:
+      dataValue:
+        nested:
+          $ref: '#/components/schemas/ShouldNotIndexData'
+  schemas:
+    ShouldNotIndex:
+      type: object
+    ShouldNotIndexData:
+      type: object
+`
+
+	var rootNode yaml.Node
+	_ = yaml.Unmarshal([]byte(spec), &rootNode)
+
+	idx := NewSpecIndexWithConfig(&rootNode, CreateOpenAPIIndexConfig())
+
+	rawRefs := make(map[string]bool)
+	for _, ref := range idx.GetAllReferences() {
+		rawRefs[ref.RawRef] = true
+	}
+
+	assert.True(t, rawRefs["#/components/examples/ReusableExample"])
+	assert.True(t, rawRefs["#/components/examples/LeafExample"])
+	assert.False(t, rawRefs["#/components/schemas/ShouldNotIndex"])
+	assert.False(t, rawRefs["#/components/schemas/ShouldNotIndexData"])
 }

index/extract_refs_walk.go

@@ -16,6 +16,7 @@ type extractRefsState struct {
 	scope         *SchemaIdScope
 	parentBaseURI string
 	seenPath      []string
+	lastAppended  bool
 	level         int
 	poly          bool
 	polyName      string
@@ -67,10 +68,6 @@ func (index *SpecIndex) walkExtractRefs(node, parent *yaml.Node, state *extractR
 
 	var found []*Reference
 	for i, n := range node.Content {
-		if utils.IsNodeMap(n) || utils.IsNodeArray(n) {
-			found = append(found, index.walkChildExtractRefs(n, node, state)...)
-		}
-
 		// In YAML mapping nodes, Content alternates key-value: even indices (0, 2, 4...)
 		// are keys, odd indices (1, 3, 5...) are values.
 		if i%2 == 0 {
@@ -79,13 +76,20 @@ func (index *SpecIndex) walkExtractRefs(node, parent *yaml.Node, state *extractR
 			}
 		}
 
+		if utils.IsNodeMap(n) || utils.IsNodeArray(n) {
+			found = append(found, index.walkChildExtractRefs(n, node, state)...)
+		}
+
 		index.unwindExtractRefsPath(node, state, i)
 	}
 
 	return found
 }
 
 func (index *SpecIndex) walkChildExtractRefs(node, parent *yaml.Node, state *extractRefsState) []*Reference {
+	if underOpenAPIExamplePayloadPath(state.seenPath) {
+		return nil
+	}
 	state.level++
 	if isPoly, _ := index.checkPolymorphicNode(state.prev); isPoly {
 		state.poly = true
@@ -103,6 +107,7 @@ func (index *SpecIndex) handleExtractRefsKey(
 	found *[]*Reference,
 ) bool {
 	keyNode := node.Content[keyIndex]
+	state.lastAppended = false
 	if keyNode == nil {
 		return false
 	}
@@ -134,6 +139,7 @@ func (index *SpecIndex) handleExtractRefsKey(
 
 	if keyNode.Value != "$ref" && keyNode.Value != "$id" && keyNode.Value != "" {
 		action := index.extractNodeMetadata(node, parent, state.seenPath, keyIndex)
+		state.lastAppended = action.appendSegment
 		if action.appendSegment {
 			state.seenPath = append(state.seenPath, strings.ReplaceAll(keyNode.Value, "/", "~1"))
 			state.prev = keyNode.Value
@@ -161,7 +167,9 @@ func (index *SpecIndex) unwindExtractRefsPath(node *yaml.Node, state *extractRef
 		return
 	}
 	next := node.Content[currentIndex+1]
-	if currentIndex%2 != 0 && next != nil && !utils.IsNodeArray(next) && !utils.IsNodeMap(next) && len(state.seenPath) > 0 {
+	if currentIndex%2 != 0 && state.lastAppended &&
+		next != nil && !utils.IsNodeArray(next) && !utils.IsNodeMap(next) && len(state.seenPath) > 0 {
 		state.seenPath = state.seenPath[:len(state.seenPath)-1]
+		state.lastAppended = false
 	}
 }

index/schema_id_test.go

@@ -1532,6 +1532,56 @@ components:
 	assert.True(t, found, "Should find invalid $id error")
 }
 
+// Test that $id values embedded inside OpenAPI example payloads are ignored.
+func TestSchemaId_IgnoresIdsInsideExamplePayloads(t *testing.T) {
+	spec := `openapi: "3.1.0"
+info:
+  title: Test API
+  version: 1.0.0
+components:
+  schemas:
+    Widget:
+      type: object
+      properties:
+        outputSchema:
+          type: object
+          example:
+            definitions: {}
+            properties:
+              id:
+                $id: '#widget/example/id'
+                type: string
+              nested:
+                $id: '#widget/example/nested'
+                type: string
+          examples:
+            sample:
+              value:
+                child:
+                  $id: '#widget/examples/child'
+                  type: integer
+`
+
+	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, 0)
+
+	errors := index.GetReferenceIndexErrors()
+	for _, e := range errors {
+		if e != nil {
+			assert.NotContains(t, e.Error(), "invalid $id")
+		}
+	}
+}
+
 // Test fragment navigation with DocumentNode wrapper
 func TestNavigateToFragment_DocumentNode(t *testing.T) {
 	yamlContent := `type: object