feat: Add support for 3.2.0 openapi spec (#54)

Co-authored-by: Tristan Cartledge <tristan@speakeasyapi.dev>
Co-authored-by: Tristan Cartledge <108070248+TristanSpeakEasy@users.noreply.github.com>

Author: BlakeTheAwesome

.github/workflows/ci.yaml

@@ -17,6 +17,8 @@ jobs:
 
       - name: Install mise
         uses: jdx/mise-action@v3
+        with:
+          experimental: true
 
       - name: Setup Go with caching
         uses: actions/setup-go@v6

.mise.toml

@@ -1,19 +1,19 @@
 [tools]
 go = "1.24.3"
-golangci-lint = "2.1.1"
 gotestsum = "latest"
 
 [tasks.setup-vscode-symlinks]
 description = "Create VSCode symlinks for tools not automatically handled by mise-vscode"
 run = [
   "mkdir -p .vscode/mise-tools",
-  "ln -sf $(mise exec -- which golangci-lint-v2) $(dirname $(mise exec -- which golangci-lint-v2))/golangci-lint || true",
-  "ln -sf $(mise exec -- which golangci-lint) .vscode/mise-tools/golangci-lint",
+  "ln -sf $(mise exec golangci-lint@2.7.2 -- which golangci-lint) .vscode/mise-tools/golangci-lint",
 ]
 
 [hooks]
 postinstall = [
   "ln -sf ./AGENTS.md ./CLAUDE.md",
+  "git submodule update --init --recursive",
+  "mise exec go@1.24.3 -- go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.7.2",
   "mise run setup-vscode-symlinks",
   "go install go.uber.org/nilaway/cmd/nilaway@8ad05f0",
 ]

AGENTS.md

@@ -58,6 +58,54 @@ mise test -count=1 ./...
 - **Race Detection**: Automatically enables race detection to catch concurrency issues
 - **Submodule Awareness**: Checks for and warns about uninitialized test submodules
 
+## Git Commit Conventions
+
+**Always use single-line conventional commits.** Do not create multi-line commit messages.
+
+### Commit Message Format
+
+```
+<type>: <description>
+```
+
+### Common Types
+
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation changes
+- `refactor:` - Code refactoring
+- `test:` - Adding or updating tests
+- `chore:` - Maintenance tasks
+- `perf:` - Performance improvements
+
+### Examples
+
+#### ✅ Good: Single-line conventional commits
+
+```bash
+git commit -m "feat: add prefixEncoding and itemEncoding support for OpenAPI 3.2 multipart media types"
+git commit -m "fix: correct validation logic for encoding field mutual exclusivity"
+git commit -m "test: add comprehensive tests for multipart encoding validation"
+git commit -m "refactor: simplify media type context passing in validation"
+```
+
+#### ❌ Bad: Multi-line commits
+
+```bash
+git commit -m "feat: implement prefixEncoding and itemEncoding for OpenAPI 3.2
+
+- Add PrefixEncoding and ItemEncoding fields to MediaType
+- Implement validation for mutual exclusivity
+- Add comprehensive tests"
+```
+
+### Why Single-Line Commits?
+
+1. **Simplicity**: Easy to read in git log and GitHub UI
+2. **Consistency**: All commits follow the same pattern
+3. **Searchability**: Easier to search and filter commits
+4. **Tool Compatibility**: Works better with automated tools and scripts
+
 ## Testing
 
 Follow these testing conventions when writing Go tests in this project. Run newly added or modified test immediately after changes to make sure they work as expected before continuing with more work.

README.md

@@ -27,7 +27,7 @@
     <!-- OpenAPI Hub Badge -->
     <a href="https://www.speakeasy.com/openapi"><img alt="OpenAPI Hub" src="https://www.speakeasy.com/assets/badges/openapi-hub.svg" /></a>
     <!-- OpenAPI Support Badge -->
-    <a href="https://www.speakeasy.com/openapi"><img alt="OpenAPI Support" src="https://img.shields.io/badge/OpenAPI-3.0%20%7C%203.1-85EA2D.svg?style=for-the-badge&logo=openapiinitiative"></a>
+    <a href="https://www.speakeasy.com/openapi"><img alt="OpenAPI Support" src="https://img.shields.io/badge/OpenAPI-3.0%20%7C%203.1%20%7C%203.2-85EA2D.svg?style=for-the-badge&logo=openapiinitiative"></a>
     <!-- Arazzo Support Badge -->
     <img alt="Arazzo Support" src="https://img.shields.io/badge/Arazzo-1.0-purple.svg?style=for-the-badge">
     <a href="https://pkg.go.dev/github.com/speakeasy-api/openapi?tab=doc"><img alt="Go Doc" src="https://img.shields.io/badge/godoc-reference-blue.svg?style=for-the-badge"></a>
@@ -68,7 +68,7 @@ The `arazzo` package provides an API for working with Arazzo documents including
 
 ### [openapi](./openapi)
 
-The `openapi` package provides an API for working with OpenAPI documents including reading, creating, mutating, walking, validating and upgrading them. Supports both OpenAPI 3.0.x and 3.1.x specifications.
+The `openapi` package provides an API for working with OpenAPI documents including reading, creating, mutating, walking, validating and upgrading them. Supports OpenAPI 3.0.x, 3.1.x, and 3.2.x specifications.
 
 ### [swagger](./swagger)
 

arazzo/arazzo.go

@@ -11,7 +11,7 @@ import (
 	"github.com/speakeasy-api/openapi/arazzo/core"
 	"github.com/speakeasy-api/openapi/extensions"
 	"github.com/speakeasy-api/openapi/internal/interfaces"
-	"github.com/speakeasy-api/openapi/internal/utils"
+	"github.com/speakeasy-api/openapi/internal/version"
 	"github.com/speakeasy-api/openapi/jsonschema/oas3"
 	"github.com/speakeasy-api/openapi/marshaller"
 	"github.com/speakeasy-api/openapi/pointer"
@@ -20,10 +20,12 @@ import (
 
 // Version is the version of the Arazzo Specification that this package conforms to.
 const (
-	Version      = "1.0.1"
-	VersionMajor = 1
-	VersionMinor = 0
-	VersionPatch = 1
+	Version = "1.0.1"
+)
+
+var (
+	MinimumSupportedVersion = version.MustParse("1.0.0")
+	MaximumSupportedVersion = version.MustParse(Version)
 )
 
 // Arazzo is the root object for an Arazzo document.
@@ -105,13 +107,14 @@ func (a *Arazzo) Validate(ctx context.Context, opts ...validation.Option) []erro
 	core := a.GetCore()
 	errs := []error{}
 
-	arazzoMajor, arazzoMinor, arazzoPatch, err := utils.ParseVersion(a.Arazzo)
+	arazzoVersion, err := version.Parse(a.Arazzo)
 	if err != nil {
 		errs = append(errs, validation.NewValueError(validation.NewValueValidationError("arazzo.version is invalid %s: %s", a.Arazzo, err.Error()), core, core.Arazzo))
 	}
-
-	if arazzoMajor != VersionMajor || arazzoMinor != VersionMinor || arazzoPatch > VersionPatch {
-		errs = append(errs, validation.NewValueError(validation.NewValueValidationError("arazzo.version only %s and below is supported", Version), core, core.Arazzo))
+	if arazzoVersion != nil {
+		if arazzoVersion.GreaterThan(*MaximumSupportedVersion) {
+			errs = append(errs, validation.NewValueError(validation.NewValueValidationError("arazzo.version only Arazzo versions between %s and %s are supported", MinimumSupportedVersion, MaximumSupportedVersion), core, core.Arazzo))
+		}
 	}
 
 	errs = append(errs, a.Info.Validate(ctx, opts...)...)

arazzo/arazzo_test.go

@@ -301,7 +301,7 @@ sourceDescriptions:
 		underlyingError error
 	}{
 		{line: 1, column: 1, underlyingError: validation.NewMissingFieldError("arazzo.workflows is missing")},
-		{line: 1, column: 9, underlyingError: validation.NewValueValidationError("arazzo.version only 1.0.1 and below is supported")},
+		{line: 1, column: 9, underlyingError: validation.NewValueValidationError("arazzo.version only Arazzo versions between 1.0.0 and 1.0.1 are supported")},
 		{line: 4, column: 3, underlyingError: validation.NewMissingFieldError("info.version is missing")},
 		{line: 6, column: 5, underlyingError: validation.NewMissingFieldError("sourceDescription.url is missing")},
 		{line: 7, column: 11, underlyingError: validation.NewValueValidationError("sourceDescription.type must be one of [openapi, arazzo]")},

cmd/openapi/commands/openapi/README.md

@@ -50,7 +50,7 @@ This command checks for:
 
 ### `upgrade`
 
-Upgrade an OpenAPI specification to the latest supported version (3.1.1).
+Upgrade an OpenAPI specification to the latest supported version (3.2.0).
 
 ```bash
 # Upgrade to stdout
@@ -64,11 +64,12 @@ openapi spec upgrade -w ./spec.yaml
 
 # Upgrade with specific target version
 openapi spec upgrade --version 3.1.0 ./spec.yaml
+openapi spec upgrade --version 3.2.0 ./spec.yaml
 ```
 
 Features:
 
-- Converts OpenAPI 3.0.x specifications to 3.1.x
+- Converts OpenAPI 3.0.x and 3.1.x specifications to 3.2.0
 - Maintains backward compatibility where possible
 - Updates schema formats and structures
 - Preserves all custom extensions and vendor-specific content
@@ -937,7 +938,7 @@ All commands work with both YAML and JSON input files and preserve the original
 openapi spec validate ./spec.yaml
 
 # Upgrade if needed
-openapi spec upgrade ./spec.yaml ./spec-v3.1.yaml
+openapi spec upgrade ./spec.yaml ./spec-v3.2.yaml
 
 # Bundle external references
 openapi spec bundle ./spec-v3.1.yaml ./spec-bundled.yaml

cmd/openapi/commands/openapi/upgrade.go

@@ -13,12 +13,17 @@ import (
 var upgradeCmd = &cobra.Command{
 	Use:   "upgrade <input-file> [output-file]",
 	Short: "Upgrade an OpenAPI specification to the latest supported version",
-	Long: `Upgrade an OpenAPI specification document to the latest supported version (3.1.1).
+	Long: `Upgrade an OpenAPI specification document to the latest supported version (3.2.0).
 
-This command will upgrade OpenAPI documents from:
-- OpenAPI 3.0.x versions to 3.1.1 (always)
-- OpenAPI 3.1.x versions to 3.1.1 (by default)
-- Use --minor-only to only upgrade minor versions (3.0.x to 3.1.1, but skip 3.1.x versions)
+By default, upgrades all versions including patch-level upgrades:
+- 3.0.x → 3.2.0
+- 3.1.x → 3.2.0
+- 3.2.x (e.g., 3.2.0) → 3.2.0 (patch upgrade if newer patch exists)
+
+With --minor-only, only performs cross-minor version upgrades:
+- 3.0.x → 3.2.0 (cross-minor upgrade)
+- 3.1.x → 3.2.0 (cross-minor upgrade)
+- 3.2.x → no change (same minor version, skip patch upgrades)
 
 The upgrade process includes:
 - Updating the OpenAPI version field
@@ -40,7 +45,7 @@ var (
 )
 
 func init() {
-	upgradeCmd.Flags().BoolVar(&minorOnly, "minor-only", false, "only upgrade minor versions (3.0.x to 3.1.1, skip 3.1.x versions)")
+	upgradeCmd.Flags().BoolVar(&minorOnly, "minor-only", false, "only upgrade across minor versions, skip patch-level upgrades within same minor")
 	upgradeCmd.Flags().BoolVarP(&writeInPlace, "write", "w", false, "write result in-place to input file")
 }
 
@@ -59,13 +64,13 @@ func runUpgrade(cmd *cobra.Command, args []string) {
 		os.Exit(1)
 	}
 
-	if err := upgradeOpenAPI(ctx, processor, minorOnly); err != nil {
+	if err := upgradeOpenAPI(ctx, processor, !minorOnly); err != nil {
 		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
 		os.Exit(1)
 	}
 }
 
-func upgradeOpenAPI(ctx context.Context, processor *OpenAPIProcessor, minorOnly bool) error {
+func upgradeOpenAPI(ctx context.Context, processor *OpenAPIProcessor, upgradeSameMinorVersion bool) error {
 	// Load the OpenAPI document
 	doc, validationErrors, err := processor.LoadDocument(ctx)
 	if err != nil {
@@ -80,12 +85,12 @@ func upgradeOpenAPI(ctx context.Context, processor *OpenAPIProcessor, minorOnly
 
 	// Prepare upgrade options
 	var opts []openapi.Option[openapi.UpgradeOptions]
-	if !minorOnly {
-		// By default, upgrade all versions including patch versions (3.1.x to 3.1.1)
-		opts = append(opts, openapi.WithUpgradeSamePatchVersion())
+	if upgradeSameMinorVersion {
+		// By default, upgrade all versions including patch upgrades (e.g., 3.2.0 → 3.2.1)
+		opts = append(opts, openapi.WithUpgradeSameMinorVersion())
 	}
-	// When minorOnly is true, only 3.0.x versions will be upgraded to 3.1.1
-	// 3.1.x versions will be skipped unless they need minor version upgrade
+	// When minorOnly is true, only cross-minor upgrades are performed
+	// Patch upgrades within the same minor version (e.g., 3.2.0 → 3.2.1) are skipped
 
 	// Perform the upgrade
 	originalVersion := doc.OpenAPI

cmd/openapi/main.go

@@ -67,7 +67,7 @@ This CLI provides tools for:
 
 OpenAPI Specifications:
 - Validate OpenAPI specification documents for compliance
-- Upgrade OpenAPI specs to the latest supported version (3.1.1)
+- Upgrade OpenAPI specs to the latest supported version (3.2.0)
 - Inline all references to create self-contained documents
 - Bundle external references into components section while preserving structure