A few edits on your v3.1 PR

.github/docs/openapi3.txt

@@ -23,7 +23,7 @@ For OpenAPI 3.1 validation, use the JSON Schema 2020-12 validator option:
 
 Version detection is available via helper methods:
 
-    if doc.IsOpenAPI3_1() {
+    if doc.IsOpenAPI31OrLater() {
         // Handle OpenAPI 3.1 specific features
     }
 
@@ -745,7 +745,7 @@ type Info struct {
 	Origin     *Origin        `json:"-" yaml:"-"`
 
 	Title          string   `json:"title" yaml:"title"`                         // Required
-	Summary        string   `json:"summary,omitempty" yaml:"summary,omitempty"` // OpenAPI 3.1
+	Summary        string   `json:"summary,omitempty" yaml:"summary,omitempty"` // OpenAPI >=3.1
 	Description    string   `json:"description,omitempty" yaml:"description,omitempty"`
 	TermsOfService string   `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"`
 	Contact        *Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
@@ -781,7 +781,7 @@ type License struct {
 
 	// Identifier is an SPDX license expression for the API (OpenAPI 3.1)
 	// Either url or identifier can be specified, not both
-	Identifier string `json:"identifier,omitempty" yaml:"identifier,omitempty"`
+	Identifier string `json:"identifier,omitempty" yaml:"identifier,omitempty"` // OpenAPI >=3.1
 }
     License is specified by OpenAPI/Swagger standard version 3. See
     https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#license-object
@@ -1686,10 +1686,8 @@ type Schema struct {
 	// Array-related, here for struct compactness
 	UniqueItems bool `json:"uniqueItems,omitempty" yaml:"uniqueItems,omitempty"`
 	// Number-related, here for struct compactness
-	// In OpenAPI 3.0: boolean modifier for minimum/maximum
-	// In OpenAPI 3.1: number representing the actual exclusive bound
-	ExclusiveMin ExclusiveBound `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`
-	ExclusiveMax ExclusiveBound `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
+	ExclusiveMin ExclusiveBound `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"` // Number for v3.1+ otherwise boolean
+	ExclusiveMax ExclusiveBound `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"` // Number for v3.1+ otherwise boolean
 	// Properties
 	Nullable        bool `json:"nullable,omitempty" yaml:"nullable,omitempty"`
 	ReadOnly        bool `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`
@@ -1721,45 +1719,41 @@ type Schema struct {
 	AdditionalProperties AdditionalProperties `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
 	Discriminator        *Discriminator       `json:"discriminator,omitempty" yaml:"discriminator,omitempty"`
 
-	// OpenAPI 3.1 / JSON Schema 2020-12 fields
-	Const                 any        `json:"const,omitempty" yaml:"const,omitempty"`
-	Examples              []any      `json:"examples,omitempty" yaml:"examples,omitempty"`
-	PrefixItems           SchemaRefs `json:"prefixItems,omitempty" yaml:"prefixItems,omitempty"`
-	Contains              *SchemaRef `json:"contains,omitempty" yaml:"contains,omitempty"`
-	MinContains           *uint64    `json:"minContains,omitempty" yaml:"minContains,omitempty"`
-	MaxContains           *uint64    `json:"maxContains,omitempty" yaml:"maxContains,omitempty"`
-	PatternProperties     Schemas    `json:"patternProperties,omitempty" yaml:"patternProperties,omitempty"`
-	DependentSchemas      Schemas    `json:"dependentSchemas,omitempty" yaml:"dependentSchemas,omitempty"`
-	PropertyNames         *SchemaRef `json:"propertyNames,omitempty" yaml:"propertyNames,omitempty"`
-	UnevaluatedItems      BoolSchema `json:"unevaluatedItems,omitempty" yaml:"unevaluatedItems,omitempty"`
-	UnevaluatedProperties BoolSchema `json:"unevaluatedProperties,omitempty" yaml:"unevaluatedProperties,omitempty"`
-
-	// JSON Schema 2020-12 conditional keywords
-	If   *SchemaRef `json:"if,omitempty" yaml:"if,omitempty"`
-	Then *SchemaRef `json:"then,omitempty" yaml:"then,omitempty"`
-	Else *SchemaRef `json:"else,omitempty" yaml:"else,omitempty"`
-
-	// JSON Schema 2020-12 dependent requirements
-	DependentRequired map[string][]string `json:"dependentRequired,omitempty" yaml:"dependentRequired,omitempty"`
-
-	// JSON Schema 2020-12 core keywords
-	Defs          Schemas `json:"$defs,omitempty" yaml:"$defs,omitempty"`
-	SchemaDialect string  `json:"$schema,omitempty" yaml:"$schema,omitempty"`
-	Comment       string  `json:"$comment,omitempty" yaml:"$comment,omitempty"`
-
-	// JSON Schema 2020-12 identity/referencing keywords
-	SchemaID      string `json:"$id,omitempty" yaml:"$id,omitempty"`
-	Anchor        string `json:"$anchor,omitempty" yaml:"$anchor,omitempty"`
-	DynamicRef    string `json:"$dynamicRef,omitempty" yaml:"$dynamicRef,omitempty"`
-	DynamicAnchor string `json:"$dynamicAnchor,omitempty" yaml:"$dynamicAnchor,omitempty"`
-
-	// JSON Schema 2020-12 content vocabulary
-	ContentMediaType string     `json:"contentMediaType,omitempty" yaml:"contentMediaType,omitempty"`
-	ContentEncoding  string     `json:"contentEncoding,omitempty" yaml:"contentEncoding,omitempty"`
-	ContentSchema    *SchemaRef `json:"contentSchema,omitempty" yaml:"contentSchema,omitempty"`
+	Const                 any        `json:"const,omitempty" yaml:"const,omitempty"`                                 // OpenAPI >=3.1
+	Examples              []any      `json:"examples,omitempty" yaml:"examples,omitempty"`                           // OpenAPI >=3.1
+	PrefixItems           SchemaRefs `json:"prefixItems,omitempty" yaml:"prefixItems,omitempty"`                     // OpenAPI >=3.1
+	Contains              *SchemaRef `json:"contains,omitempty" yaml:"contains,omitempty"`                           // OpenAPI >=3.1
+	MinContains           *uint64    `json:"minContains,omitempty" yaml:"minContains,omitempty"`                     // OpenAPI >=3.1
+	MaxContains           *uint64    `json:"maxContains,omitempty" yaml:"maxContains,omitempty"`                     // OpenAPI >=3.1
+	PatternProperties     Schemas    `json:"patternProperties,omitempty" yaml:"patternProperties,omitempty"`         // OpenAPI >=3.1
+	DependentSchemas      Schemas    `json:"dependentSchemas,omitempty" yaml:"dependentSchemas,omitempty"`           // OpenAPI >=3.1
+	PropertyNames         *SchemaRef `json:"propertyNames,omitempty" yaml:"propertyNames,omitempty"`                 // OpenAPI >=3.1
+	UnevaluatedItems      BoolSchema `json:"unevaluatedItems,omitempty" yaml:"unevaluatedItems,omitempty"`           // OpenAPI >=3.1
+	UnevaluatedProperties BoolSchema `json:"unevaluatedProperties,omitempty" yaml:"unevaluatedProperties,omitempty"` // OpenAPI >=3.1
+
+	If   *SchemaRef `json:"if,omitempty" yaml:"if,omitempty"`     // OpenAPI >=3.1
+	Then *SchemaRef `json:"then,omitempty" yaml:"then,omitempty"` // OpenAPI >=3.1
+	Else *SchemaRef `json:"else,omitempty" yaml:"else,omitempty"` // OpenAPI >=3.1
+
+	DependentRequired map[string][]string `json:"dependentRequired,omitempty" yaml:"dependentRequired,omitempty"` // OpenAPI >=3.1
+
+	Defs          Schemas `json:"$defs,omitempty" yaml:"$defs,omitempty"`       // OpenAPI >=3.1
+	SchemaDialect string  `json:"$schema,omitempty" yaml:"$schema,omitempty"`   // OpenAPI >=3.1
+	Comment       string  `json:"$comment,omitempty" yaml:"$comment,omitempty"` // OpenAPI >=3.1
+
+	SchemaID      string `json:"$id,omitempty" yaml:"$id,omitempty"`                       // OpenAPI >=3.1
+	Anchor        string `json:"$anchor,omitempty" yaml:"$anchor,omitempty"`               // OpenAPI >=3.1
+	DynamicRef    string `json:"$dynamicRef,omitempty" yaml:"$dynamicRef,omitempty"`       // OpenAPI >=3.1
+	DynamicAnchor string `json:"$dynamicAnchor,omitempty" yaml:"$dynamicAnchor,omitempty"` // OpenAPI >=3.1
+
+	ContentMediaType string     `json:"contentMediaType,omitempty" yaml:"contentMediaType,omitempty"` // OpenAPI >=3.1
+	ContentEncoding  string     `json:"contentEncoding,omitempty" yaml:"contentEncoding,omitempty"`   // OpenAPI >=3.1
+	ContentSchema    *SchemaRef `json:"contentSchema,omitempty" yaml:"contentSchema,omitempty"`       // OpenAPI >=3.1
 }
     Schema is specified by OpenAPI/Swagger 3.0 standard. See
     https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object
+    and
+    https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object
 
 func NewAllOfSchema(schemas ...*Schema) *Schema
 
@@ -1827,6 +1821,9 @@ func (schema *Schema) Validate(ctx context.Context, opts ...ValidationOption) er
     Validate returns an error if Schema does not comply with the OpenAPI spec.
 
 func (schema *Schema) VisitJSON(value any, opts ...SchemaValidationOption) error
+    VisitJSON applies a Schema to the given data, considering opts.
+    To validate data against an OpenAPIv3.1+ schema, be sure to pass the
+    EnableJSONSchema2020() option.
 
 func (schema *Schema) VisitJSONArray(value []any) error
 
@@ -2107,6 +2104,8 @@ type SecurityScheme struct {
 }
     SecurityScheme is specified by OpenAPI/Swagger standard version 3. See
     https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-scheme-object
+    and
+    https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object
 
 func NewCSRFSecurityScheme() *SecurityScheme
 
@@ -2292,22 +2291,16 @@ func (stringMap *StringMap[V]) UnmarshalJSON(data []byte) (err error)
 type T struct {
 	Extensions map[string]any `json:"-" yaml:"-"`
 
-	OpenAPI      string               `json:"openapi" yaml:"openapi"` // Required
-	Components   *Components          `json:"components,omitempty" yaml:"components,omitempty"`
-	Info         *Info                `json:"info" yaml:"info"`                       // Required
-	Paths        *Paths               `json:"paths,omitempty" yaml:"paths,omitempty"` // Required in 3.0, optional in 3.1
-	Security     SecurityRequirements `json:"security,omitempty" yaml:"security,omitempty"`
-	Servers      Servers              `json:"servers,omitempty" yaml:"servers,omitempty"`
-	Tags         Tags                 `json:"tags,omitempty" yaml:"tags,omitempty"`
-	ExternalDocs *ExternalDocs        `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
-
-	// OpenAPI 3.1.x specific fields
-	// Webhooks are a new feature in OpenAPI 3.1 that allow APIs to define callback operations
-	Webhooks map[string]*PathItem `json:"webhooks,omitempty" yaml:"webhooks,omitempty"`
-
-	// JSONSchemaDialect allows specifying the default JSON Schema dialect for Schema Objects
-	// See https://spec.openapis.org/oas/v3.1.0#schema-object
-	JSONSchemaDialect string `json:"jsonSchemaDialect,omitempty" yaml:"jsonSchemaDialect,omitempty"`
+	OpenAPI           string               `json:"openapi" yaml:"openapi"` // Required
+	Components        *Components          `json:"components,omitempty" yaml:"components,omitempty"`
+	Info              *Info                `json:"info" yaml:"info"`   // Required
+	Paths             *Paths               `json:"paths" yaml:"paths"` // Required in 3.0, optional in 3.1
+	Security          SecurityRequirements `json:"security,omitempty" yaml:"security,omitempty"`
+	Servers           Servers              `json:"servers,omitempty" yaml:"servers,omitempty"`
+	Tags              Tags                 `json:"tags,omitempty" yaml:"tags,omitempty"`
+	ExternalDocs      *ExternalDocs        `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
+	Webhooks          map[string]*PathItem `json:"webhooks,omitempty" yaml:"webhooks,omitempty"`                   // OpenAPI >=3.1
+	JSONSchemaDialect string               `json:"jsonSchemaDialect,omitempty" yaml:"jsonSchemaDialect,omitempty"` // OpenAPI >=3.1
 
 	// Has unexported fields.
 }
@@ -2340,11 +2333,15 @@ func (doc *T) InternalizeRefs(ctx context.Context, refNameResolver func(*T, Comp
 
         doc.InternalizeRefs(context.Background(), nil)
 
-func (doc *T) IsOpenAPI3_0() bool
-    IsOpenAPI3_0 returns true if the document is OpenAPI 3.0.x
+func (doc *T) IsOpenAPI30() bool
+    IsOpenAPI30 returns whether doc is an OpenAPI document version 3.0.x.
+    Returns true for 3, 3.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, ... And false
+    for 3.1.0, 3.2, ... and for invalid strings.
 
-func (doc *T) IsOpenAPI3_1() bool
-    IsOpenAPI3_1 returns true if the document is OpenAPI 3.1.x
+func (doc *T) IsOpenAPI31OrLater() bool
+    IsOpenAPI31OrLater returns whether doc is an OpenAPI document version >=3.1.
+    Returns true for 3.1, 3.1.0, 3.1.1, 3.1.2, 3.2.0, ... And false for cases
+    where IsOpenAPI30 returns true and for invalid strings.
 
 func (doc *T) JSONLookup(token string) (any, error)
     JSONLookup implements
@@ -2356,6 +2353,10 @@ func (doc *T) MarshalJSON() ([]byte, error)
 func (doc *T) MarshalYAML() (any, error)
     MarshalYAML returns the YAML encoding of T.
 
+func (doc *T) OpenAPIMajorMinor() string
+    OpenAPIMajorMinor returns 3.y of the OpenAPI "3.y" or "3.y.z" version of the
+    document. Returns the empty string for invalid OpenAPI version strings.
+
 func (doc *T) SetIntegerFormatValidator(name string, validator IntegerFormatValidator)
     SetIntegerFormatValidator sets a single document-scoped integer format
     validator.
@@ -2387,14 +2388,14 @@ func (doc *T) Validate(ctx context.Context, opts ...ValidationOption) error
     Validate returns an error if T does not comply with the OpenAPI spec.
     Validations Options can be provided to modify the validation behavior.
 
+    By default, doc.OpenAPI's field dictates whether "JSON Schema Draft 2020-12"
+    validation is enabled.
+
 func (doc *T) ValidateSchemaJSON(schema *Schema, value any, opts ...SchemaValidationOption) error
     ValidateSchemaJSON validates data against a schema using this document's
     format validators. This is a convenience method that automatically applies
     the document's format validators.
 
-func (doc *T) Version() string
-    Version returns the major.minor version of the OpenAPI document
-
 type Tag struct {
 	Extensions map[string]any `json:"-" yaml:"-"`
 	Origin     *Origin        `json:"-" yaml:"-"`
@@ -2583,11 +2584,6 @@ func EnableExamplesValidation() ValidationOption
     EnableExamplesValidation does the opposite of DisableExamplesValidation.
     By default, all schema examples are validated.
 
-func EnableJSONSchema2020Validation() ValidationOption
-    EnableJSONSchema2020Validation enables JSON Schema 2020-12 compliant
-    validation for OpenAPI 3.1 documents. This option should be used with
-    doc.Validate().
-
 func EnableSchemaDefaultsValidation() ValidationOption
     EnableSchemaDefaultsValidation does the opposite of
     DisableSchemaDefaultsValidation. By default, schema default values are
@@ -2603,6 +2599,10 @@ func EnableSchemaPatternValidation() ValidationOption
     DisableSchemaPatternValidation. By default, schema pattern validation is
     enabled.
 
+func IsOpenAPI31OrLater() ValidationOption
+    IsOpenAPI31OrLater enables "JSON Schema Draft 2020-12"-compliant validation
+    (for OpenAPI 3.1 documents).
+
 func ProhibitExtensionsWithRef() ValidationOption
     ProhibitExtensionsWithRef causes the validation to return an error if
     extensions (fields starting with 'x-') are found as siblings for $ref

.github/workflows/go.yml

@@ -138,7 +138,7 @@ jobs:
     - if: runner.os == 'Linux'
       name: Missing specification object link to definition
       run: |
-        [[ 31 -eq $(git grep -InE '^// See https:.+OpenAPI-Specification.+3[.]0[.]3[.]md#.+bject$' openapi3/*.go | grep -v _test.go | grep -v doc.go | wc -l) ]]
+        [[ 31 -eq $(git grep -InE '^// See https:.+OpenAPI-Specification.+3[0-9.]+md#.+bject$' openapi3/*.go | grep -v _test.go | grep -v doc.go | wc -l) ]]
 
     - if: runner.os == 'Linux'
       name: Missing validation of unknown fields in extensions

cmd/validate/main.go

@@ -68,10 +68,6 @@ 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())
 		}

openapi3/doc.go

@@ -19,7 +19,7 @@
 //
 // Version detection is available via helper methods:
 //
-//	if doc.IsOpenAPI3_1() {
+//	if doc.IsOpenAPI31OrLater() {
 //	    // Handle OpenAPI 3.1 specific features
 //	}
 package openapi3

openapi3/example_jsonschema2020_test.go

@@ -239,14 +239,12 @@ func Example_comparingValidators() {
 	testValue := "test"
 
 	// Test with built-in validator (no option)
-	err1 := schema.VisitJSON(testValue)
-	if err1 != nil {
+	if err := schema.VisitJSON(testValue); err != nil {
 		fmt.Println("built-in validator: rejected")
 	}
 
 	// Test with JSON Schema 2020-12 validator
-	err2 := schema.VisitJSON(testValue, openapi3.EnableJSONSchema2020())
-	if err2 != nil {
+	if err := schema.VisitJSON(testValue, openapi3.EnableJSONSchema2020()); err != nil {
 		fmt.Println("visit JSON Schema 2020-12 validator: rejected")
 	}
 

openapi3/example_validation.go

@@ -3,7 +3,7 @@ package openapi3
 import "context"
 
 func validateExampleValue(ctx context.Context, input any, schema *Schema) error {
-	opts := make([]SchemaValidationOption, 0, 2)
+	opts := []SchemaValidationOption{MultiErrors()}
 
 	vo := getValidationOptions(ctx)
 	if vo.examplesValidationAsReq {
@@ -16,7 +16,5 @@ func validateExampleValue(ctx context.Context, input any, schema *Schema) error
 		opts = append(opts, EnableJSONSchema2020())
 	}
 
-	opts = append(opts, MultiErrors())
-
 	return schema.VisitJSON(input, opts...)
 }

openapi3/info.go

@@ -15,7 +15,7 @@ type Info struct {
 	Origin     *Origin        `json:"-" yaml:"-"`
 
 	Title          string   `json:"title" yaml:"title"`                         // Required
-	Summary        string   `json:"summary,omitempty" yaml:"summary,omitempty"` // OpenAPI 3.1
+	Summary        string   `json:"summary,omitempty" yaml:"summary,omitempty"` // OpenAPI >=3.1
 	Description    string   `json:"description,omitempty" yaml:"description,omitempty"`
 	TermsOfService string   `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"`
 	Contact        *Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
@@ -40,7 +40,6 @@ func (info *Info) MarshalYAML() (any, error) {
 	m := make(map[string]any, 7+len(info.Extensions))
 	maps.Copy(m, info.Extensions)
 	m["title"] = info.Title
-	// OpenAPI 3.1 field
 	if x := info.Summary; x != "" {
 		m["summary"] = x
 	}
@@ -69,7 +68,7 @@ func (info *Info) UnmarshalJSON(data []byte) error {
 	}
 	_ = json.Unmarshal(data, &x.Extensions)
 	delete(x.Extensions, "title")
-	delete(x.Extensions, "summary") // OpenAPI 3.1
+	delete(x.Extensions, "summary")
 	delete(x.Extensions, "description")
 	delete(x.Extensions, "termsOfService")
 	delete(x.Extensions, "contact")
@@ -86,6 +85,10 @@ func (info *Info) UnmarshalJSON(data []byte) error {
 func (info *Info) Validate(ctx context.Context, opts ...ValidationOption) error {
 	ctx = WithValidationOptions(ctx, opts...)
 
+	if info.Summary != "" && !getValidationOptions(ctx).isOpenAPI31OrLater {
+		return errFieldFor31Plus("summary")
+	}
+
 	if contact := info.Contact; contact != nil {
 		if err := contact.Validate(ctx); err != nil {
 			return err

openapi3/info_test.go

@@ -0,0 +1,45 @@
+package openapi3_test
+
+import (
+	"testing"
+
+	"github.com/getkin/kin-openapi/openapi3"
+	"github.com/stretchr/testify/require"
+)
+
+func TestValidateInfo_SummaryIn30(t *testing.T) {
+	spec := []byte(`
+openapi: '3'
+paths: {}
+info:
+  title: An API
+  version: 1.2.3.4
+  summary: bla
+`)
+
+	loader := openapi3.NewLoader()
+	doc, err := loader.LoadFromData(spec)
+	require.NoError(t, err)
+
+	err = doc.Validate(loader.Context)
+	require.ErrorContains(t, err, "invalid info")
+	require.ErrorContains(t, err, "field summary")
+}
+
+func TestValidateInfo_SummaryIn31(t *testing.T) {
+	spec := []byte(`
+openapi: '3.1'
+paths: {}
+info:
+  title: An API
+  version: 1.2.3.4
+  summary: bla
+`)
+
+	loader := openapi3.NewLoader()
+	doc, err := loader.LoadFromData(spec)
+	require.NoError(t, err)
+
+	err = doc.Validate(loader.Context)
+	require.NoError(t, err)
+}