feat: OpenAPI 3.1 support with scoped validation enhancements

README.md

@@ -302,6 +302,9 @@ for _, path := range doc.Paths.InMatchingOrder() {
 * `openapi3.Location` gained `File` and `Name` fields (`string` type, replacing previous `int`-only struct layout)
 * `openapi3.Origin` gained `Sequences` field (`map[string][]Location`, extending previous `map[string]Location`-only struct)
 
+### v0.132.0
+* `openapi3.Schema.ExclusiveMin` and `openapi3.Schema.ExclusiveMax` fields changed from `bool` to `ExclusiveBound` (a union type holding `*bool` for OpenAPI 3.0 or `*float64` for OpenAPI 3.1).
+* `openapi3.Schema.PrefixItems` field changed from `[]*SchemaRef` to `SchemaRefs`.
 ### v0.131.0
 * No longer `openapi3filter.RegisterBodyDecoder` the `openapi3filter.ZipFileBodyDecoder` by default.
 

cmd/validate/main.go

@@ -68,6 +68,10 @@ func main() {
 		}
 
 		var opts []openapi3.ValidationOption
+		if doc.IsOpenAPI3_1() {
+			log.Println("Detected OpenAPI 3.1 document, enabling JSON Schema 2020-12 validation")
+			opts = append(opts, openapi3.EnableJSONSchema2020Validation())
+		}
 		if !*defaults {
 			opts = append(opts, openapi3.DisableSchemaDefaultsValidation())
 		}

go.mod

@@ -9,6 +9,7 @@ require (
 	github.com/oasdiff/yaml v0.0.1
 	github.com/oasdiff/yaml3 v0.0.1
 	github.com/perimeterx/marshmallow v1.1.5
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
 	github.com/stretchr/testify v1.9.0
 	github.com/woodsbury/decimal128 v1.3.0
 )
@@ -20,5 +21,6 @@ require (
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rogpeppe/go-internal v1.12.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,5 +1,7 @@
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
+github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/go-openapi/jsonpointer v0.21.0 h1:YgdVicSA9vH5RiHs9TZW5oyafXZFc6+2Vc1rr/O9oNQ=
 github.com/go-openapi/jsonpointer v0.21.0/go.mod h1:IUyH9l/+uyhIYQ/PXVA41Rexl+kOkAPDdXEYns6fzUY=
 github.com/go-openapi/swag v0.23.0 h1:vsEVJDUo2hPJ2tu0/Xc+4noaxyEffXNIs3cOULZ+GrE=
@@ -28,12 +30,16 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU5NdKM8=
 github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/ugorji/go/codec v1.2.7 h1:YPXUKf7fYbp/y8xloBqZOw2qaVggbfwMlI8WM3wZUJ0=
 github.com/ugorji/go/codec v1.2.7/go.mod h1:WGN1fab3R1fzQlVQTkfxVtIBhWDRqOviHU95kRgeqEY=
 github.com/woodsbury/decimal128 v1.3.0 h1:8pffMNWIlC0O5vbyHWFZAt5yWvWcrHA+3ovIIjVWss0=
 github.com/woodsbury/decimal128 v1.3.0/go.mod h1:C5UTmyTjW3JftjUFzOVhC20BEQa2a4ZKOB5I6Zjb+ds=
+golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
+golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

openapi2conv/openapi2_conv.go

@@ -268,8 +268,8 @@ func ToV3Parameter(components *openapi3.Components, parameter *openapi2.Paramete
 			Enum:            parameter.Enum,
 			Min:             parameter.Minimum,
 			Max:             parameter.Maximum,
-			ExclusiveMin:    parameter.ExclusiveMin,
-			ExclusiveMax:    parameter.ExclusiveMax,
+			ExclusiveMin:    openapi3.ExclusiveBound{Bool: boolPtr(parameter.ExclusiveMin)},
+			ExclusiveMax:    openapi3.ExclusiveBound{Bool: boolPtr(parameter.ExclusiveMax)},
 			MinLength:       parameter.MinLength,
 			MaxLength:       parameter.MaxLength,
 			Default:         parameter.Default,
@@ -494,8 +494,8 @@ func ToV3SchemaRef(schema *openapi2.SchemaRef) *openapi3.SchemaRef {
 		Example:              schema.Value.Example,
 		ExternalDocs:         schema.Value.ExternalDocs,
 		UniqueItems:          schema.Value.UniqueItems,
-		ExclusiveMin:         schema.Value.ExclusiveMin,
-		ExclusiveMax:         schema.Value.ExclusiveMax,
+		ExclusiveMin:         openapi3.ExclusiveBound{Bool: boolPtr(schema.Value.ExclusiveMin)},
+		ExclusiveMax:         openapi3.ExclusiveBound{Bool: boolPtr(schema.Value.ExclusiveMax)},
 		ReadOnly:             schema.Value.ReadOnly,
 		WriteOnly:            schema.Value.WriteOnly,
 		AllowEmptyValue:      schema.Value.AllowEmptyValue,
@@ -881,10 +881,10 @@ func FromV3SchemaRef(schema *openapi3.SchemaRef, components *openapi3.Components
 				Description:  schema.Value.Description,
 				Type:         paramType,
 				Enum:         schema.Value.Enum,
-				Minimum:      schema.Value.Min,
-				Maximum:      schema.Value.Max,
-				ExclusiveMin: schema.Value.ExclusiveMin,
-				ExclusiveMax: schema.Value.ExclusiveMax,
+				Minimum:      effectiveMin(schema.Value.Min, schema.Value.ExclusiveMin),
+				Maximum:      effectiveMax(schema.Value.Max, schema.Value.ExclusiveMax),
+				ExclusiveMin: exclusiveMinToBool(schema.Value.ExclusiveMin, schema.Value.Min),
+				ExclusiveMax: exclusiveMaxToBool(schema.Value.ExclusiveMax, schema.Value.Max),
 				MinLength:    schema.Value.MinLength,
 				MaxLength:    schema.Value.MaxLength,
 				Default:      schema.Value.Default,
@@ -911,15 +911,15 @@ func FromV3SchemaRef(schema *openapi3.SchemaRef, components *openapi3.Components
 		Example:              schema.Value.Example,
 		ExternalDocs:         schema.Value.ExternalDocs,
 		UniqueItems:          schema.Value.UniqueItems,
-		ExclusiveMin:         schema.Value.ExclusiveMin,
-		ExclusiveMax:         schema.Value.ExclusiveMax,
+		ExclusiveMin:         exclusiveMinToBool(schema.Value.ExclusiveMin, schema.Value.Min),
+		ExclusiveMax:         exclusiveMaxToBool(schema.Value.ExclusiveMax, schema.Value.Max),
 		ReadOnly:             schema.Value.ReadOnly,
 		WriteOnly:            schema.Value.WriteOnly,
 		AllowEmptyValue:      schema.Value.AllowEmptyValue,
 		Deprecated:           schema.Value.Deprecated,
 		XML:                  schema.Value.XML,
-		Min:                  schema.Value.Min,
-		Max:                  schema.Value.Max,
+		Min:                  effectiveMin(schema.Value.Min, schema.Value.ExclusiveMin),
+		Max:                  effectiveMax(schema.Value.Max, schema.Value.ExclusiveMax),
 		MultipleOf:           schema.Value.MultipleOf,
 		MinLength:            schema.Value.MinLength,
 		MaxLength:            schema.Value.MaxLength,
@@ -1045,16 +1045,16 @@ func FromV3RequestBodyFormData(mediaType *openapi3.MediaType) openapi2.Parameter
 			In:           "formData",
 			Extensions:   stripNonExtensions(val.Extensions),
 			Enum:         val.Enum,
-			ExclusiveMin: val.ExclusiveMin,
-			ExclusiveMax: val.ExclusiveMax,
+			ExclusiveMin: exclusiveMinToBool(val.ExclusiveMin, val.Min),
+			ExclusiveMax: exclusiveMaxToBool(val.ExclusiveMax, val.Max),
 			MinLength:    val.MinLength,
 			MaxLength:    val.MaxLength,
 			Default:      val.Default,
 			Items:        v2Items,
 			MinItems:     val.MinItems,
 			MaxItems:     val.MaxItems,
-			Maximum:      val.Max,
-			Minimum:      val.Min,
+			Maximum:      effectiveMax(val.Max, val.ExclusiveMax),
+			Minimum:      effectiveMin(val.Min, val.ExclusiveMin),
 			Pattern:      val.Pattern,
 			// CollectionFormat: val.CollectionFormat,
 			// Format:          val.Format,
@@ -1341,3 +1341,80 @@ func addPathExtensions(doc2 *openapi2.T, path string, extensions map[string]any)
 	}
 	pathItem.Extensions = extensions
 }
+
+// boolPtr returns a pointer to a bool, or nil if the value is false (to avoid storing empty values)
+func boolPtr(b bool) *bool {
+	if !b {
+		return nil
+	}
+	return &b
+}
+
+// exclusiveMinToBool returns true when the OAS 3.1 numeric exclusiveMinimum is
+// the strictly tighter lower-bound constraint compared to minimum.
+func exclusiveMinToBool(eb openapi3.ExclusiveBound, min *float64) bool {
+	if eb.Bool != nil {
+		return *eb.Bool
+	}
+	if eb.Value == nil {
+		return false
+	}
+	// No inclusive minimum: use exclusive bound, set flag = true.
+	if min == nil {
+		return true
+	}
+	// Both present. OAS 3.1 means value >= min AND value > eb.Value.
+	// The binding constraint depends on which is tighter:
+	//   if eb.Value >= min, then value > eb.Value is tighter → exclusive=true, bound=eb.Value
+	//   if eb.Value < min,  then value >= min is tighter     → exclusive=false, bound=min
+	return *eb.Value >= *min
+}
+
+// exclusiveMaxToBool returns true when the OAS 3.1 numeric exclusiveMaximum is
+// the strictly tighter upper-bound constraint compared to maximum.
+func exclusiveMaxToBool(eb openapi3.ExclusiveBound, max *float64) bool {
+	if eb.Bool != nil {
+		return *eb.Bool
+	}
+	if eb.Value == nil {
+		return false
+	}
+	if max == nil {
+		return true
+	}
+	// eb.Value <= max means exclusive upper bound is tighter.
+	return *eb.Value <= *max
+}
+
+// effectiveMin returns the minimum value for OAS 2.0 conversion, considering ExclusiveBound.
+// In OAS 3.1, exclusiveMinimum is a number. In OAS 2.0, it must be in the minimum field.
+// When both minimum and a numeric exclusiveMinimum are present, the tighter bound is returned.
+func effectiveMin(min *float64, eb openapi3.ExclusiveBound) *float64 {
+	if eb.Value == nil {
+		return min
+	}
+	if min == nil {
+		return eb.Value
+	}
+	// Both present: the tighter (larger) lower bound wins.
+	if *eb.Value >= *min {
+		return eb.Value
+	}
+	return min
+}
+
+// effectiveMax returns the maximum value for OAS 2.0 conversion, considering ExclusiveBound.
+// When both maximum and a numeric exclusiveMaximum are present, the tighter bound is returned.
+func effectiveMax(max *float64, eb openapi3.ExclusiveBound) *float64 {
+	if eb.Value == nil {
+		return max
+	}
+	if max == nil {
+		return eb.Value
+	}
+	// Both present: the tighter (smaller) upper bound wins.
+	if *eb.Value <= *max {
+		return eb.Value
+	}
+	return max
+}

openapi3/components.go

@@ -15,6 +15,7 @@ type (
 	Headers         map[string]*HeaderRef
 	Links           map[string]*LinkRef
 	ParametersMap   map[string]*ParameterRef
+	PathItems       map[string]*PathItem
 	RequestBodies   map[string]*RequestBodyRef
 	ResponseBodies  map[string]*ResponseRef
 	Schemas         map[string]*SchemaRef
@@ -36,6 +37,7 @@ type Components struct {
 	Examples        Examples        `json:"examples,omitempty" yaml:"examples,omitempty"`
 	Links           Links           `json:"links,omitempty" yaml:"links,omitempty"`
 	Callbacks       Callbacks       `json:"callbacks,omitempty" yaml:"callbacks,omitempty"`
+	PathItems       PathItems       `json:"pathItems,omitempty" yaml:"pathItems,omitempty"`
 }
 
 func NewComponents() Components {
@@ -53,7 +55,7 @@ func (components Components) MarshalJSON() ([]byte, error) {
 
 // MarshalYAML returns the YAML encoding of Components.
 func (components Components) MarshalYAML() (any, error) {
-	m := make(map[string]any, 9+len(components.Extensions))
+	m := make(map[string]any, 10+len(components.Extensions))
 	for k, v := range components.Extensions {
 		m[k] = v
 	}
@@ -84,6 +86,9 @@ func (components Components) MarshalYAML() (any, error) {
 	if x := components.Callbacks; len(x) != 0 {
 		m["callbacks"] = x
 	}
+	if x := components.PathItems; len(x) != 0 {
+		m["pathItems"] = x
+	}
 	return m, nil
 }
 
@@ -105,6 +110,7 @@ func (components *Components) UnmarshalJSON(data []byte) error {
 	delete(x.Extensions, "examples")
 	delete(x.Extensions, "links")
 	delete(x.Extensions, "callbacks")
+	delete(x.Extensions, "pathItems")
 	if len(x.Extensions) == 0 {
 		x.Extensions = nil
 	}
@@ -251,6 +257,21 @@ func (components *Components) Validate(ctx context.Context, opts ...ValidationOp
 		}
 	}
 
+	pathItems := make([]string, 0, len(components.PathItems))
+	for name := range components.PathItems {
+		pathItems = append(pathItems, name)
+	}
+	sort.Strings(pathItems)
+	for _, k := range pathItems {
+		v := components.PathItems[k]
+		if err = ValidateIdentifier(k); err != nil {
+			return fmt.Errorf("pathItem %q: %w", k, err)
+		}
+		if err = v.Validate(ctx); err != nil {
+			return fmt.Errorf("pathItem %q: %w", k, err)
+		}
+	}
+
 	return validateExtensions(ctx, components.Extensions)
 }
 
@@ -370,3 +391,16 @@ func (m Callbacks) JSONLookup(token string) (any, error) {
 		return v.Value, nil
 	}
 }
+
+var _ jsonpointer.JSONPointable = (*PathItems)(nil)
+
+// JSONLookup implements https://pkg.go.dev/github.com/go-openapi/jsonpointer#JSONPointable
+func (m PathItems) JSONLookup(token string) (any, error) {
+	if v, ok := m[token]; !ok || v == nil {
+		return nil, fmt.Errorf("no path item %q", token)
+	} else if ref := v.Ref; ref != "" {
+		return &Ref{Ref: ref}, nil
+	} else {
+		return v, nil
+	}
+}

openapi3/doc.go

@@ -1,4 +1,25 @@
 // Package openapi3 parses and writes OpenAPI 3 specification documents.
 //
-// See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md
+// Supports both OpenAPI 3.0 and OpenAPI 3.1:
+//   - OpenAPI 3.0.x: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md
+//   - OpenAPI 3.1.x: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md
+//
+// OpenAPI 3.1 Features:
+//   - Type arrays with null support (e.g., ["string", "null"])
+//   - JSON Schema 2020-12 keywords (const, examples, prefixItems, etc.)
+//   - Webhooks for defining callback operations
+//   - JSON Schema dialect specification
+//   - SPDX license identifiers
+//
+// The implementation is designed to preserve backward compatibility with OpenAPI 3.0.
+//
+// For OpenAPI 3.1 validation, use the JSON Schema 2020-12 validator option:
+//
+//	schema.VisitJSON(value, openapi3.EnableJSONSchema2020())
+//
+// Version detection is available via helper methods:
+//
+//	if doc.IsOpenAPI3_1() {
+//	    // Handle OpenAPI 3.1 specific features
+//	}
 package openapi3