v1.21.1

v1.21.1 - Documentation Fix

Fixes pkg.go.dev documentation for the parser package.

🐛 Bug Fix

• parser: Moved //go:generate directive from doc.go to parser.go to restore package documentation on pkg.go.dev

The //go:generate directive was breaking godoc by separating the package documentation comment from the package parser declaration, causing no package description to appear in the pkg.go.dev directories table.

📥 Installation

# Homebrew
brew upgrade oastools

# Go install
go install github.com/erraggy/oastools/cmd/oastools@v1.21.1

# Go library
go get github.com/erraggy/oastools@v1.21.1

Full Changelog: v1.21.0...v1.21.1

v1.21.0

v1.21.0 - Enterprise Features Release

This release adds enterprise-grade error handling, a pluggable logging interface, and configurable resource limits for production deployments.

✨ New Features

Structured Error Types (oaserrors package)

New public package providing typed errors with errors.Is() and errors.As() support:

Error Type	Use Case
ParseError	YAML/JSON parsing failures with location info
ReferenceError	$ref resolution, circular refs, path traversal
ValidationError	Spec violations with field/path details
ResourceLimitError	Resource exhaustion (ref depth, cache size, file size)
ConversionError	Version conversion failures
ConfigError	Invalid configuration options

Sentinel errors for easy checking:

• ErrParse, ErrReference, ErrCircularReference, ErrPathTraversal
• ErrValidation, ErrResourceLimit, ErrConversion, ErrConfig

import "github.com/erraggy/oastools/oaserrors"

if errors.Is(err, oaserrors.ErrCircularReference) {
    // Handle circular reference
}

var refErr *oaserrors.ReferenceError
if errors.As(err, &refErr) {
    log.Printf("Ref: %s, Type: %s", refErr.Ref, refErr.RefType)
}

Logger Interface

Pluggable logging with slog-compatible interface:

result, _ := parser.ParseWithOptions(
    parser.WithFilePath("api.yaml"),
    parser.WithLogger(parser.NewSlogAdapter(slog.Default())),
)

Built-in adapters:

• NopLogger - No-op (default, zero overhead)
• SlogAdapter - Wraps *slog.Logger
• ContextLogger - Adds context association

Configurable Resource Limits

Runtime-configurable protection against resource exhaustion:

result, _ := parser.ParseWithOptions(
    parser.WithFilePath("api.yaml"),
    parser.WithMaxRefDepth(50),           // Default: 100
    parser.WithMaxCachedDocuments(200),   // Default: 100
    parser.WithMaxFileSize(20*1024*1024), // Default: 10MB
)

🔧 Improvements

• Nullable Deprecation Warnings: Converter now warns when converting OAS 3.0.x specs with nullable: true to OAS 3.1.x
• Severity Exports: All packages now export all 4 severity levels (Info, Warning, Error, Critical)
• Version Comparison: Simplified OAS version comparison using range checks (contributed by Copilot)
• Documentation: Added circular reference handling and resource limits documentation to parser package

📦 Package Updates

Package	Changes
oaserrors	NEW - Structured error types
parser	Logger interface, resource limit options, integrated error types
validator	Added SeverityInfo, SeverityCritical exports
converter	Added SeverityError export, nullable deprecation warnings
generator	Added SeverityError export

🔄 Backward Compatibility

All changes are additive with sensible defaults:

• Logger defaults to NopLogger (zero overhead)
• Resource limits use existing constants as defaults
• No breaking API changes

📥 Installation

# Homebrew
brew upgrade oastools

# Go install
go install github.com/erraggy/oastools/cmd/oastools@v1.21.0

# Go library
go get github.com/erraggy/oastools@v1.21.0

Full Changelog: v1.20.3...v1.21.0

v1.20.3

Documentation

• README Overhaul: Comprehensive update to README.md for better pkg.go.dev landing page experience (#111)
  • Reorganized structure with clearer sections
  • Enhanced Quick Start examples for CLI and library usage
  • Improved feature descriptions and links

Installation

# Homebrew
brew install erraggy/tap/oastools

# Go install
go install github.com/erraggy/oastools/cmd/oastools@v1.20.3

Full Changelog: v1.20.2...v1.20.3

v1.20.2

What's Changed

Bug Fixes

• fix(parser): Prevent infinite loop when marshaling documents with circular references (#109)

  • Added HasCircularRefs() method to detect circular references during resolution
  • Documents with circular refs now use original data instead of re-marshaling (which caused hangs)
  • Added warning message when circular references are detected

• fix(generator): Fix time import, duplicate fields, and additionalProperties handling (#108)

  • Fixed missing time import when generating time.Time fields
  • Fixed duplicate field generation for embedded structs
  • Fixed additionalProperties handling in schema generation

Other Changes

• chore: Add benchmarks for v1.20.1 and v1.20.2 (#110)
  • Backfilled v1.20.1 benchmarks
  • Added v1.20.2 benchmarks
  • Added fuzz test seed discovered during verification

Full Changelog: v1.20.1...v1.20.2

v1.20.1

Critical Bug Fix: $ref Parameter and RequestBody Validation

This release fixes a critical validation bug that caused massive false positive error counts when validating OpenAPI specifications that use $ref references for parameters and request bodies.

The Problem

The parser was incorrectly validating $ref parameters/requestBodies for required fields (name, in, content) that only exist in the referenced definition, not the reference itself. This caused specs like the weather.gov API to report errors like:

missing required field 'paths./.../parameters[1].name': Parameter must have a name

...when the parameter correctly used $ref to reference a component definition.

Impact

This fix eliminates ~40,000 false positives across real-world API specifications:

Specification	Before	After	Improvement
Microsoft Graph	30,000 errors	✅ Valid	-100%
GitHub API	8,000 errors	2,224	-72%
DigitalOcean	1,918 errors	496	-74%
Google Maps	228 errors	✅ Valid	-100%
US NWS	156 errors	44	-72%

Changes

• Skip validation for $ref parameters in OAS 2.0 and OAS 3.x
• Skip validation for $ref requestBodies in OAS 3.x
• Added comprehensive test coverage for ref validation

Upgrade Recommendation

All users should upgrade immediately. If you were seeing unexpected "Parameter must have a name" or "RequestBody must have at least one media type" errors on valid specs using $ref, this release fixes those issues.

# Upgrade via Go
go install github.com/erraggy/oastools@latest

# Or download from releases

---

Full Changelog: v1.20.0...v1.20.1

v1.20.0

v1.20.0 - Code-Generated DeepCopy: Correctness & Performance

This release introduces code-generated DeepCopy methods for all OAS document types, delivering both correctness fixes and dramatic performance improvements.

Highlights

Correctness: Proper $ref Parameter Handling

The previous JSON marshal/unmarshal deep copy approach corrupted documents containing $ref parameters by adding empty string fields (name: "", in: ""). This caused the fixer to produce invalid documents when processing specs with referenced parameters.

v1.20.0 fixes this with type-aware DeepCopy methods that:

• Preserve nil vs empty distinction (critical for OAS semantics)
• Handle polymorphic fields correctly (Schema.Type, AdditionalProperties, etc.)
• Maintain full type fidelity for all OAS structures

Performance: 20-40x Faster Deep Copying

Operation	v1.19.x	v1.20.0	Improvement
FixParsed (small)	86 μs	2.3 μs	37x faster
FixParsed (medium)	908 μs	28.5 μs	32x faster
FixParsed (large)	11.3 ms	347 μs	33x faster
ConvertParsed (small)	16.2 μs	3.2 μs	5x faster
ConvertParsed (medium)	256 μs	37.3 μs	7x faster

Memory usage also improved significantly:

• 10x fewer allocations for deep copy operations
• 5-8x less memory allocated per operation

New Features

DeepCopy Methods for All OAS Types

Every parser type now has code-generated DeepCopy() and DeepCopyInto() methods:

// Create independent copy of OAS3 document
original, _ := result.Document.(*parser.OAS3Document)
docCopy := original.DeepCopy()

// Modify copy without affecting original
docCopy.Info.Title = "Modified API"

Type-Aware Polymorphic Field Handling

OAS 3.1+ polymorphic fields are handled correctly:

Field	Supported Types
Schema.Type	string or []string
Schema.AdditionalProperties	*Schema or bool
Schema.ExclusiveMinimum	bool or float64
*.Default, *.Example	Any JSON value

Developer Experience

• Corpus benchmarks now opt-in: Use make bench-corpus or -tags=corpus to run memory-intensive benchmarks
• Benchmark results: See benchmarks/benchmark-v1.20.0.txt for complete performance data
• Documentation: New Example_deepCopy() in godoc

Breaking Changes

None. This is a backwards-compatible enhancement.

Changelog

• feat(parser): add deep copy code generation for OAS types (#105)
• docs: v1.20.0 release prep - DeepCopy documentation and corpus benchmark build tags (#106)

---

Full benchmark comparison: See benchmarks.md for detailed performance metrics.

v1.19.1

Summary

This patch release improves the benchmark infrastructure and release workflow. No functional changes to the core packages.

Improvements

Benchmark Infrastructure

• Added comprehensive benchmarks for fixer package (fixer/fixer_bench_test.go)
• Added generator package to benchmark infrastructure
• Backfilled benchmark baselines for v1.17.1, v1.17.2, v1.18.0, v1.19.0
• Added bench-fixer and bench-generator Makefile targets
• Added -timeout=15m to all benchmark commands to prevent hangs

Release Workflow

• Added make bench-release VERSION=vX.Y.Z target for capturing release benchmarks with automatic comparison using benchstat
• Created scripts/compare-with-previous.sh for version-to-version benchmark comparison
• Refactored Makefile with per-target .PHONY declarations and section headers

Documentation

• Added "Adding a New Package/Feature Checklist" to CLAUDE.md
• Updated benchmarks.md with Fixer and Generator sections
• Updated README.md performance table (corrected package count to 8)
• Updated WORKFLOW.md, BENCHMARK_UPDATE_PROCESS.md, and benchmarks/README.md

Related PRs

• #101 - docs: add fixer/generator benchmarks, feature checklist, and backfill v1.17-v1.19
• #102 - chore: add bench-release target and improve release workflow

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools

Go Module

go get github.com/erraggy/oastools@v1.19.1

Binary Download

Download the appropriate binary for your platform from the assets below.

v1.19.0

What's New in v1.19.0

New fixer Package

This release introduces the fixer package for automatically fixing common OAS validation errors.

First Fix Type: Missing Path Parameters

The fixer automatically adds Parameter objects for path template variables that are missing from the operation's parameters list - a common validation error affecting thousands of real-world APIs:

• GitHub API: 8,074 errors → fixed
• DigitalOcean API: 1,918 errors → fixed
• Asana API: 302 errors → fixed

Features

• Dual API: Functional options (FixWithOptions) and struct-based (New().Fix())
• Type Inference: --infer flag for smart type detection:
  • Names ending in id/Id/ID → integer
  • Names containing uuid/guid → string with format: uuid
  • All others → string
• OAS 2.0 & 3.x Support: Works with all supported OpenAPI versions
• Deterministic Output: Sorted iteration ensures consistent results
• Pipeline-Friendly: stdin/stdout support for chaining commands

CLI Usage

# Fix and output to stdout
oastools fix openapi.yaml

# Fix and write to file
oastools fix -o fixed.yaml openapi.yaml

# Enable type inference
oastools fix --infer openapi.yaml

# Pipeline: fix then validate
oastools fix -q api.yaml | oastools validate -q -

CLI Refactoring

The CLI has been refactored from a monolithic ~1400-line main.go into a modular structure:

cmd/oastools/
├── main.go              (~100 lines - command dispatch)
└── commands/
    ├── common.go        (shared utilities)
    ├── parse.go
    ├── validate.go
    ├── join.go
    ├── convert.go
    ├── diff.go
    ├── generate.go
    └── fix.go

Each command now has its own file with dedicated unit tests following Go conventions.

Full Changelog

v1.18.0...v1.19.0

v1.18.0

HTTP/HTTPS $ref Resolution Support

This release adds support for resolving $ref references that point to HTTP/HTTPS URLs, enabling parsing of modular OpenAPI specifications with external references.

New Features

HTTP $ref Resolution (#96)

• Parse specifications with external HTTP/HTTPS $ref references
• Opt-in via --resolve-http-refs flag (SSRF protection by default)
• --insecure flag for self-signed TLS certificates
• Caching, size limits, and circular reference protection

CLI Usage:

# Parse spec with HTTP references
oastools parse --resolve-refs --resolve-http-refs spec.yaml

# With self-signed certificates (development only)
oastools parse --resolve-refs --resolve-http-refs --insecure spec.yaml

Library Usage:

result, err := parser.ParseWithOptions(
    parser.WithFilePath("spec.yaml"),
    parser.WithResolveRefs(true),
    parser.WithResolveHTTPRefs(true),
    // parser.WithInsecureSkipVerify(true), // For self-signed certs
)

Additional CLI Improvements:

• join -q/--quiet flag for pipeline support
• join -o now optional (defaults to stdout like convert)

---

Integration Testing with Real-World OAS Corpus

Corpus Integration Tests (#97)

Added comprehensive integration tests using 10 real-world public OpenAPI specifications spanning OAS 2.0, 3.0.x, and 3.1.0 versions. Tests validate the full pipeline: parser, validator, converter, joiner, and differ.

API	OAS Version	Size
Petstore	2.0	20KB
Discord	3.1.0	3MB
Stripe	3.0.0	14MB
GitHub	3.0.3	5MB
Microsoft Graph	3.0.4	15MB
DigitalOcean	3.0.0	200KB
+ 4 more...

New Makefile Targets:

make corpus-download    # Download all specs (one-time)
make test-corpus-short  # Run tests (excludes large specs)
make test-corpus        # Run all corpus tests

For methodology and validation results, see OAS Corpus Research.

---

Documentation Updates

• Updated README with HTTP $ref support and integration testing sections (#98)
• Added parser examples for WithResolveHTTPRefs and WithInsecureSkipVerify
• Updated parser/doc.go with HTTP resolution documentation

Full Changelog

v1.17.2...v1.18.0

v1.17.2

What's Changed

Build Improvements

• Add -trimpath flag for smaller, reproducible binaries
• Add build metadata to version output (commit, build time, go version)

Documentation

• Comprehensive documentation update for pipeline and CLI features
• Add stdin support (-) docs for validate, parse, convert commands
• Add --format json/yaml and -q/--quiet mode documentation
• Update version numbers and examples throughout

Full Changelog

v1.17.1...v1.17.2