fix(joiner): include documentation fields in semantic-dedup equivalence by default

Two schemas that differ only in title/description/example/examples are no
longer treated as equivalent by the joiner's schema comparison. Semantic
deduplication previously replaced the surviving canonical schema's docs at
every $ref site, producing misleading API docs (a 403 response landing on a
schema whose description said "The request is invalid").

- Add EquivalenceDocs type with "include" (default, strict) and "ignore"
  (legacy loose) values
- Add CompareSchemasWithOptions accepting CompareOptions; CompareSchemas
  delegates with the strict default
- Thread compareDocs bool through compareShallow/compareDeep and all
  recursive helpers
- Add JoinerConfig.EquivalenceDocs, WithEquivalenceDocs option, and
  --equivalence-docs CLI flag
- Update metadata-only tests to reflect the new strict default; add
  regression test mirroring issue #363 (BadRequest/Forbidden/NotFound
  error-response schemas)
- Update joiner/deep_dive.md with the new flag and default change

Callers needing the old loose behavior can opt in via
WithEquivalenceDocs("ignore") or --equivalence-docs ignore.

Fixes #363

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: erraggy

builder/builder_dedupe_test.go

@@ -164,10 +164,13 @@ func TestBuilder_WithSemanticDeduplication_Disabled(t *testing.T) {
 	assert.Len(t, doc.Components.Schemas, 2)
 }
 
-func TestBuilder_DeduplicateSchemas_MetadataIgnored(t *testing.T) {
+func TestBuilder_DeduplicateSchemas_MetadataPreserved(t *testing.T) {
+	// Regression for issue #363: under the strict equivalence default, the
+	// builder must not consolidate schemas that differ in documentation.
+	// Doing so would replace the surviving canonical schema's docs at every
+	// reference site, producing misleading API documentation.
 	b := New(parser.OASVersion320, WithSemanticDeduplication(true))
 
-	// Schemas differ only in metadata - should still be deduplicated
 	b.addSchema("Address", &parser.Schema{
 		Type:        "object",
 		Title:       "An Address",
@@ -188,8 +191,11 @@ func TestBuilder_DeduplicateSchemas_MetadataIgnored(t *testing.T) {
 	doc, err := b.BuildOAS3()
 	require.NoError(t, err)
 
-	// Should deduplicate since structural properties are the same
-	assert.Len(t, doc.Components.Schemas, 1)
+	// Both schemas must survive because their documentation differs.
+	assert.Len(t, doc.Components.Schemas, 2,
+		"strict equivalence should preserve schemas with divergent metadata")
+	assert.Equal(t, "An Address", doc.Components.Schemas["Address"].Title)
+	assert.Equal(t, "A Location", doc.Components.Schemas["Location"].Title)
 }
 
 func TestBuilder_DeduplicateSchemas_MultipleGroups(t *testing.T) {

cmd/oastools/commands/common.go

@@ -73,6 +73,15 @@ func ValidateEquivalenceMode(value string) error {
 	return nil
 }
 
+// ValidateEquivalenceDocs validates the equivalence-docs flag and returns an
+// error if invalid. Empty values are accepted and resolved to the default.
+func ValidateEquivalenceDocs(value string) error {
+	if value != "" && !joiner.IsValidEquivalenceDocs(value) {
+		return fmt.Errorf("invalid equivalence-docs '%s'. Valid values: %v", value, joiner.ValidEquivalenceDocs())
+	}
+	return nil
+}
+
 // ValidatePrimaryOperationPolicy validates the primary operation policy flag value.
 func ValidatePrimaryOperationPolicy(policy string) error {
 	if policy == "" {

cmd/oastools/commands/common_test.go

@@ -89,6 +89,31 @@ func TestValidateEquivalenceMode(t *testing.T) {
 	}
 }
 
+func TestValidateEquivalenceDocs(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   string
+		wantErr bool
+	}{
+		{"empty value", "", false},
+		{"valid include", "include", false},
+		{"valid ignore", "ignore", false},
+		{"invalid value", "strict", true},
+		{"case sensitive INCLUDE", "INCLUDE", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ValidateEquivalenceDocs(tt.value)
+			if tt.wantErr {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
 func TestMarshalDocument(t *testing.T) {
 	doc := map[string]string{"key": "value"}
 

cmd/oastools/commands/join.go

@@ -78,6 +78,7 @@ type JoinFlags struct {
 	// Advanced collision strategies
 	RenameTemplate  string
 	EquivalenceMode string
+	EquivalenceDocs string
 	CollisionReport bool
 	SemanticDedup   bool
 	// Namespace prefix configuration
@@ -114,6 +115,8 @@ func SetupJoinFlags() (*flag.FlagSet, *JoinFlags) {
 	// Advanced collision strategies
 	fs.StringVar(&flags.RenameTemplate, "rename-template", "{{.Name}}_{{.Source}}", "template for renamed schema names")
 	fs.StringVar(&flags.EquivalenceMode, "equivalence-mode", "none", "schema comparison mode for deduplication (none, shallow, deep)")
+	fs.StringVar(&flags.EquivalenceDocs, "equivalence-docs", "include",
+		"whether title/description/example/examples participate in schema equivalence (include, ignore)")
 	fs.BoolVar(&flags.CollisionReport, "collision-report", false, "generate detailed collision analysis report")
 	fs.BoolVar(&flags.SemanticDedup, "semantic-dedup", false, "enable semantic deduplication to consolidate identical schemas")
 
@@ -243,6 +246,9 @@ func HandleJoin(args []string) error {
 	// Apply advanced collision strategy settings
 	config.RenameTemplate = flags.RenameTemplate
 	config.EquivalenceMode = flags.EquivalenceMode
+	if flags.EquivalenceDocs != "" {
+		config.EquivalenceDocs = flags.EquivalenceDocs
+	}
 	config.CollisionReport = flags.CollisionReport
 	config.SemanticDeduplication = flags.SemanticDedup
 
@@ -266,6 +272,9 @@ func HandleJoin(args []string) error {
 	if err := ValidateEquivalenceMode(flags.EquivalenceMode); err != nil {
 		return err
 	}
+	if err := ValidateEquivalenceDocs(flags.EquivalenceDocs); err != nil {
+		return err
+	}
 	if err := ValidatePrimaryOperationPolicy(flags.PrimaryOperationPolicy); err != nil {
 		return err
 	}

docs/cli-reference.md

@@ -599,6 +599,7 @@ oastools join [flags] <file1> <file2> [file3...]
 | `--primary-operation-policy` | | Policy for selecting primary operation: `first`, `most-specific`, `alphabetical` (default: `first`) |
 | `--semantic-dedup` | | Enable semantic deduplication to consolidate identical schemas |
 | `--equivalence-mode` | | Schema comparison mode for deduplication: `none`, `shallow`, `deep` (default: `none`) |
+| `--equivalence-docs` | | Whether `title`, `description`, `example`, and `examples` participate in schema equivalence: `include` (default, strict), `ignore` (legacy loose) |
 | `--collision-report` | | Generate detailed collision analysis report |
 | `--namespace-prefix` | | Namespace prefix for source file (format: source=prefix, can be repeated) |
 | `--always-prefix` | | Apply namespace prefix to all schemas, not just on collision |

joiner/deep_dive.md

@@ -1374,6 +1374,45 @@ func main() {
 }
 ```
 
+### Preserving Documentation During Deduplication
+
+Since v1.54.0, semantic equivalence is **strict by default**: two schemas that
+differ only in `title`, `description`, `example`, or `examples` are treated
+as **not equivalent** and are preserved as separate schemas. This prevents a
+subtle documentation-clobbering bug where every `$ref` site to a
+consolidated schema ended up pointing at a canonical schema whose prose
+applied to a different context (for example, a 403 response landing on a
+schema whose description said "The request is invalid").
+
+Callers that explicitly want the legacy loose behavior — where schemas with
+identical structure are merged regardless of docs — can opt in with
+`WithEquivalenceDocs`:
+
+```go
+result, err := joiner.JoinWithOptions(
+    joiner.WithFilePaths("users-api.yaml", "admin-api.yaml"),
+    joiner.WithSemanticDeduplication(true),
+    // Accept that consolidated schemas' docs will be replaced
+    // at every $ref site.
+    joiner.WithEquivalenceDocs(string(joiner.EquivalenceDocsIgnore)),
+)
+```
+
+The CLI exposes the same control via `--equivalence-docs`:
+
+```bash
+# Default: strict. Schemas with differing docs are preserved.
+oastools join --semantic-dedup -o merged.yaml api1.yaml api2.yaml
+
+# Loose: legacy behavior. Differing docs are discarded during dedup.
+oastools join --semantic-dedup --equivalence-docs ignore \
+    -o merged.yaml api1.yaml api2.yaml
+```
+
+The same `WithEquivalenceDocs` option applies to the `deduplicate` collision
+strategy (`SchemaStrategy = StrategyDeduplicateEquivalent`) and to the
+`SemanticDeduplication` post-merge pass.
+
 ### High-Performance Joining with Pre-Parsed Documents
 
 For integration with other oastools packages, use pre-parsed documents for 154x faster performance: