differ

Overview ¶

Package differ provides OpenAPI specification comparison and breaking change detection.

Overview ¶

The differ package enables comparison of OpenAPI specifications to identify differences, categorize changes, and detect breaking API changes. It supports both OAS 2.0 and OAS 3.x documents.

Usage ¶

The package provides two API styles:

1. Package-level convenience functions for simple, one-off operations
2. Struct-based API for reusable instances with custom configuration

Diff Modes ¶

The differ supports two operational modes:

• ModeSimple: Reports all semantic differences without categorization
• ModeBreaking: Categorizes changes by severity and identifies breaking changes

Change Categories ¶

Changes are categorized by the part of the specification that changed:

• CategoryEndpoint: Path/endpoint changes
• CategoryOperation: HTTP operation changes
• CategoryParameter: Parameter changes
• CategoryRequestBody: Request body changes
• CategoryResponse: Response changes
• CategorySchema: Schema/definition changes
• CategorySecurity: Security scheme changes
• CategoryServer: Server/host changes
• CategoryInfo: Metadata changes

Severity Levels ¶

In ModeBreaking, changes are assigned severity levels:

• SeverityCritical: Critical breaking changes (removed endpoints, operations)
• SeverityError: Breaking changes (removed required parameters, type changes)
• SeverityWarning: Potentially problematic changes (deprecated operations, new required fields)
• SeverityInfo: Non-breaking changes (additions, relaxed constraints)

Example (Simple Diff) ¶

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	// Simple diff using functional options
	result, err := differ.DiffWithOptions(
		differ.WithSourceFilePath("api-v1.yaml"),
		differ.WithTargetFilePath("api-v2.yaml"),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d changes\n", len(result.Changes))
	for _, change := range result.Changes {
		fmt.Println(change.String())
	}
}

Example (Breaking Change Detection) ¶

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	// Diff with breaking mode using functional options
	result, err := differ.DiffWithOptions(
		differ.WithSourceFilePath("api-v1.yaml"),
		differ.WithTargetFilePath("api-v2.yaml"),
		differ.WithMode(differ.ModeBreaking),
		differ.WithIncludeInfo(true),
	)
	if err != nil {
		log.Fatal(err)
	}

	if result.HasBreakingChanges {
		fmt.Printf("⚠️  Found %d breaking change(s)!\n", result.BreakingCount)
	}

	fmt.Printf("Summary: %d breaking, %d warnings, %d info\n",
		result.BreakingCount, result.WarningCount, result.InfoCount)

	// Print changes grouped by severity
	for _, change := range result.Changes {
		fmt.Println(change.String())
	}
}

Example (Reusable Differ Instance) ¶

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	// Create a reusable differ instance
	d := differ.New()
	d.Mode = differ.ModeBreaking
	d.IncludeInfo = false // Skip informational changes

	// Compare multiple spec pairs with same configuration
	pairs := []struct{ old, new string }{
		{"api-v1.yaml", "api-v2.yaml"},
		{"api-v2.yaml", "api-v3.yaml"},
		{"api-v3.yaml", "api-v4.yaml"},
	}

	for _, pair := range pairs {
		result, err := d.Diff(pair.old, pair.new)
		if err != nil {
			log.Printf("Error comparing %s to %s: %v", pair.old, pair.new, err)
			continue
		}

		fmt.Printf("\n%s → %s:\n", pair.old, pair.new)
		if result.HasBreakingChanges {
			fmt.Printf("  ⚠️  %d breaking changes\n", result.BreakingCount)
		} else {
			fmt.Println("  ✓ No breaking changes")
		}
	}
}

Working with Parsed Documents ¶

For efficiency when documents are already parsed, use WithSourceParsed and WithTargetParsed:

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
	"github.com/erraggy/oastools/parser"
)

func main() {
	// Parse documents once
	source, err := parser.ParseWithOptions(
		parser.WithFilePath("api-v1.yaml"),
		parser.WithValidateStructure(true),
	)
	if err != nil {
		log.Fatal(err)
	}

	target, err := parser.ParseWithOptions(
		parser.WithFilePath("api-v2.yaml"),
		parser.WithValidateStructure(true),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Compare parsed documents
	result, err := differ.DiffWithOptions(
		differ.WithSourceParsed(*source),
		differ.WithTargetParsed(*target),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d changes\n", len(result.Changes))
}

Change Analysis ¶

The Change struct provides detailed information about each difference:

for _, change := range result.Changes {
	fmt.Printf("Path: %s\n", change.Path)
	fmt.Printf("Type: %s\n", change.Type)
	fmt.Printf("Category: %s\n", change.Category)
	fmt.Printf("Severity: %s\n", change.Severity)
	fmt.Printf("Message: %s\n", change.Message)

	if change.OldValue != nil {
		fmt.Printf("Old value: %v\n", change.OldValue)
	}
	if change.NewValue != nil {
		fmt.Printf("New value: %v\n", change.NewValue)
	}
}

Breaking Change Examples ¶

Common breaking changes detected in ModeBreaking:

• Removed endpoints or operations (SeverityCritical)
• Removed required parameters (SeverityCritical)
• Changed parameter types (SeverityError)
• Made optional parameters required (SeverityError)
• Removed enum values (SeverityError)
• Removed success response codes (SeverityError)
• Removed schemas (SeverityError)
• Changed authentication requirements (SeverityError)

Non-Breaking Change Examples ¶

Common non-breaking changes in ModeBreaking:

• Added endpoints or operations (SeverityInfo)
• Added optional parameters (SeverityInfo)
• Made required parameters optional (SeverityInfo)
• Added enum values (SeverityInfo)
• Added response codes (SeverityInfo)
• Documentation updates (SeverityInfo)

Version Compatibility ¶

The differ works with:

• OAS 2.0 (Swagger) documents
• OAS 3.0.x documents
• OAS 3.1.x documents
• OAS 3.2.x documents
• Cross-version comparisons (with limitations)

When comparing documents of different OAS versions (e.g., 2.0 vs 3.0), the diff is limited to common elements present in both versions.

Coverage Details ¶

The differ provides comprehensive comparison of OpenAPI specification elements:

Response Comparison ¶

Response objects are fully compared including:

• Headers: All header properties (description, required, deprecated, type, style, schema)
• Content/MediaTypes: Media type objects and their schemas
• Links: Link objects (operationRef, operationId, description)
• Examples: Example map keys (not deep value comparison)
• Extensions: All x-* fields on Response objects

Header comparison includes:

• Description and deprecation status
• Required flag changes
• Type and style modifications
• Schema changes (delegates to schema comparison)
• Extensions on Header objects

MediaType comparison includes:

• Schema changes (delegates to comprehensive schema comparison)
• Extensions on MediaType objects

Link comparison includes:

• Operation references (operationRef, operationId)
• Description changes
• Extensions on Link objects

Schema Comparison ¶

Schema objects are comprehensively compared including all fields:

Metadata:

• title, description

Type information:

• type, format

Numeric constraints:

• multipleOf, maximum, exclusiveMaximum, minimum, exclusiveMinimum

String constraints:

• maxLength, minLength, pattern

Array constraints:

• maxItems, minItems, uniqueItems

Object constraints:

• maxProperties, minProperties
• required fields (with smart severity: adding required=ERROR, removing=INFO)

OAS-specific fields:

• nullable, readOnly, writeOnly, deprecated

Schema comparison uses smart severity assignment in breaking mode:

• ERROR: Stricter constraints (adding required fields, lowering max values, raising min values)
• WARNING: Changes that might affect consumers (type changes, constraint modifications)
• INFO: Relaxations and non-breaking changes (removing required, raising max, lowering min)

Note: Recursive schema properties (properties, items, allOf, oneOf, anyOf, not) are compared separately to avoid cyclic comparison issues.

Extension (x-*) Field Coverage ¶

The OpenAPI Specification allows custom extension fields (starting with "x-") at many levels of the document. The differ detects and reports changes to extensions at commonly-used locations:

Extensions ARE diffed for these types:

• Document level (OAS2Document, OAS3Document)
• Info object
• Server objects
• PathItem objects
• Operation objects
• Parameter objects
• RequestBody objects
• Response objects
• Header objects (response headers)
• Link objects (response links)
• MediaType objects (content types)
• Schema objects
• SecurityScheme objects
• Tag objects
• Components object

Extensions are NOT currently diffed for these less commonly-used types:

• Contact, License, ExternalDocs (nested within Info)
• ServerVariable (nested within Server)
• Reference objects
• Items (OAS 2.0 array item definitions)
• Example, Encoding (response-related nested objects)
• Discriminator, XML (schema-related nested objects)
• OAuthFlows, OAuthFlow (security-related nested objects)

The rationale for this selective coverage is that extensions are most commonly placed at document, path, operation, parameter, response, and schema levels where they provide cross-cutting metadata. Extensions in deeply nested objects like ServerVariable, Discriminator, or Example are rare in practice.

If your use case requires extension diffing for the uncovered types, please open an issue at https://github.com/erraggy/oastools/issues

All extension changes are reported with CategoryExtension and are assigned SeverityInfo in breaking mode, as specification extensions are non-normative and optional according to the OpenAPI Specification.

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	// Compare two OpenAPI specifications
	result, err := differ.DiffWithOptions(
		differ.WithSourceFilePath("../testdata/petstore-v1.yaml"),
		differ.WithTargetFilePath("../testdata/petstore-v2.yaml"),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d changes\n", len(result.Changes))
	fmt.Printf("Source version: %s\n", result.SourceVersion)
	fmt.Printf("Target version: %s\n", result.TargetVersion)
}

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	result, err := differ.DiffWithOptions(
		differ.WithSourceFilePath("../testdata/petstore-v1.yaml"),
		differ.WithTargetFilePath("../testdata/petstore-v2.yaml"),
		differ.WithMode(differ.ModeBreaking),
		differ.WithIncludeInfo(true),
	)
	if err != nil {
		log.Fatal(err)
	}

	if result.HasBreakingChanges {
		fmt.Printf("⚠️  Found %d breaking change(s)\n", result.BreakingCount)
	} else {
		fmt.Println("✓ No breaking changes detected")
	}

	fmt.Printf("Summary: %d breaking, %d warnings, %d info\n",
		result.BreakingCount, result.WarningCount, result.InfoCount)
}

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	// Compare two API versions with breaking mode enabled
	result, err := differ.DiffWithOptions(
		differ.WithSourceFilePath("../testdata/petstore-v1.yaml"),
		differ.WithTargetFilePath("../testdata/petstore-v2.yaml"),
		differ.WithMode(differ.ModeBreaking),
		differ.WithIncludeInfo(true), // Include all change levels
	)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Comparing %s to %s\n", result.SourceVersion, result.TargetVersion)
	fmt.Printf("Total changes: %d\n\n", len(result.Changes))

	// Critical changes: API consumers WILL break
	// Examples: removed endpoints, required parameters, response schema changes
	criticalCount := 0
	errorCount := 0
	warningCount := 0
	infoCount := 0

	for _, change := range result.Changes {
		// Severity constants from internal/severity package:
		// SeverityCritical = 3, SeverityError = 2, SeverityWarning = 1, SeverityInfo = 0
		switch change.Severity {
		case 3: // Critical
			criticalCount++
			fmt.Printf("CRITICAL [%s]: %s\n", change.Path, change.Message)
		case 2: // Error
			errorCount++
		case 1: // Warning
			warningCount++
		case 0: // Info
			infoCount++
		}
	}

	// Summary by severity
	fmt.Printf("\nSummary:\n")
	fmt.Printf("- Critical (API will break): %d\n", criticalCount)
	fmt.Printf("- Errors (likely to break): %d\n", errorCount)
	fmt.Printf("- Warnings (may affect clients): %d\n", warningCount)
	fmt.Printf("- Info (non-breaking changes): %d\n", infoCount)

	// Check if changes are backward compatible
	if result.HasBreakingChanges {
		fmt.Println("\n⚠️  This update contains BREAKING CHANGES")
		fmt.Println("Consider versioning the API (e.g., /v2/...)")
	} else {
		fmt.Println("\n✓ Changes are backward compatible")
	}
}

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	d := differ.New()
	d.Mode = differ.ModeBreaking

	result, err := d.Diff("../testdata/petstore-v1.yaml", "../testdata/petstore-v2.yaml")
	if err != nil {
		log.Fatal(err)
	}

	// Group changes by category
	categories := make(map[differ.ChangeCategory]int)
	for _, change := range result.Changes {
		categories[change.Category]++
	}

	fmt.Println("Changes by category:")
	for category, count := range categories {
		fmt.Printf("  %s: %d\n", category, count)
	}
}

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	d := differ.New()
	d.Mode = differ.ModeBreaking
	d.IncludeInfo = false // Exclude info-level changes

	result, err := d.Diff("../testdata/petstore-v1.yaml", "../testdata/petstore-v2.yaml")
	if err != nil {
		log.Fatal(err)
	}

	// Only breaking changes and warnings remain
	fmt.Printf("Breaking and warnings only: %d changes\n", len(result.Changes))
	fmt.Printf("Breaking: %d, Warnings: %d\n", result.BreakingCount, result.WarningCount)
}

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
	"github.com/erraggy/oastools/parser"
)

func main() {
	// Parse documents once
	source, err := parser.ParseWithOptions(
		parser.WithFilePath("../testdata/petstore-v1.yaml"),
		parser.WithValidateStructure(true),
	)
	if err != nil {
		log.Fatal(err)
	}

	target, err := parser.ParseWithOptions(
		parser.WithFilePath("../testdata/petstore-v2.yaml"),
		parser.WithValidateStructure(true),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Compare parsed documents
	result, err := differ.DiffWithOptions(
		differ.WithSourceParsed(*source),
		differ.WithTargetParsed(*target),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Found %d changes between %s and %s\n",
		len(result.Changes), result.SourceVersion, result.TargetVersion)
}

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	// Create a reusable differ with specific configuration
	d := differ.New()
	d.Mode = differ.ModeBreaking
	d.IncludeInfo = false
	d.UserAgent = "my-api-tool/1.0"

	// Use the same differ for multiple comparisons
	specs := []struct{ old, new string }{
		{"../testdata/petstore-v1.yaml", "../testdata/petstore-v2.yaml"},
	}

	for _, spec := range specs {
		result, err := d.Diff(spec.old, spec.new)
		if err != nil {
			log.Printf("Error: %v", err)
			continue
		}

		fmt.Printf("%s → %s: ", spec.old, spec.new)
		if result.HasBreakingChanges {
			fmt.Printf("%d breaking\n", result.BreakingCount)
		} else {
			fmt.Println("compatible")
		}
	}
}

package main

import (
	"fmt"
	"log"

	"github.com/erraggy/oastools/differ"
)

func main() {
	result, err := differ.DiffWithOptions(
		differ.WithSourceFilePath("../testdata/petstore-v1.yaml"),
		differ.WithTargetFilePath("../testdata/petstore-v2.yaml"),
		differ.WithMode(differ.ModeSimple),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Simple diff found %d changes\n", len(result.Changes))

	// Print first few changes
	for i, change := range result.Changes {
		if i >= 3 {
			break
		}
		fmt.Println(change.String())
	}
}