Issue 230: Add OpenAPI 3.1 Support

[chanceattoast]

The implementation provides complete OpenAPI 3.1 specification compliance while maintaining 100% backward compatibility with OpenAPI 3.0.

What Was Implemented

1. Schema Object Extensions (openapi3/schema.go)

Added full JSON Schema 2020-12 support with new fields:

• Const - Constant value validation
• Examples - Array of examples (replaces singular example)
• PrefixItems - Tuple validation for arrays
• Contains, MinContains, MaxContains - Array containment validation
• PatternProperties - Pattern-based property matching
• DependentSchemas - Conditional schema dependencies
• PropertyNames - Property name validation
• UnevaluatedItems, UnevaluatedProperties - Unevaluated keyword support
• Type arrays - Support for ["string", "null"] notation

2. Document-Level Features (openapi3/openapi3.go)

• Webhooks - New field for defining webhook callbacks (OpenAPI 3.1)
• JSONSchemaDialect - Specifies default JSON Schema dialect
• Version detection methods:
  • IsOpenAPI3_0() - Returns true for 3.0.x documents
  • IsOpenAPI3_1() - Returns true for 3.1.x documents
  • Version() - Returns major.minor version string

3. License Object (openapi3/license.go)

• Identifier - SPDX license expression (alternative to URL)

4. Info Object (openapi3/info.go)

• Summary - Short summary of the API (OpenAPI 3.1)

5. Types Helper Methods (openapi3/schema.go)

New methods for working with type arrays:

• IncludesNull() - Checks if null type is included
• IsMultiple() - Detects type arrays (OpenAPI 3.1 feature)
• IsSingle() - Checks for single type
• IsEmpty() - Checks for unspecified types

6. JSON Schema 2020-12 Validator (openapi3/schema_jsonschema_validator.go)

A new opt-in validator using santhosh-tekuri/jsonschema/v6:

• Full JSON Schema Draft 2020-12 compliance
• Automatic OpenAPI → JSON Schema transformation
• Converts OpenAPI 3.0 nullable to type arrays
• Handles exclusiveMinimum/exclusiveMaximum conversion
• Comprehensive error formatting
• Fallback to built-in validator on compilation errors

[jamietanna]

Out of interest, was there any AI usage here to develop these changes?

Has this been used to test with "real" repositories and specifications?

Might also be worth making sure your Git authorship is correctly set up, to associate the commits with your user

[ialexryan]

Thank you for contributing this @chanceattoast ! So excited for this to be merged so we can finally upgrade oasdiff.

[doxie-king]

thank you for this!!

[gramidt]

Thank you so much! LGTM!

[chanceattoast]

@jamietanna here's the answers to your questions and sorry for the delay in responding:

Out of interest, was there any AI usage here to develop these changes?

Yes, I used Claude code to help

Has this been used to test with "real" repositories and specifications?

Yes it has and it worked well from the 3.1 files we have

Might also be worth making sure your Git authorship is correctly set up, to associate the commits with your user

I realized that as I committed; my company uses a private Github enterprise and so my machine was set up for that; if I push any more commits if you have changes, I'll correct this

[ialexryan]

@fenollp would you be able to merge this? 🙏🏻

[RulerOfTheQueendom]

@fenollp Checking in here - this seems like a great thing to get over the line. Any timeline on when this can get merged in?

[jamietanna]

For folks looking at using this, can you share some results of using it with OpenAPI 3.1 specs? Ie confirming that the 3.1 support in this PR does cover the functionality that's needed

[ajroetker]

Maybe I'm missing it but @jamietanna I don't think this covers if/then/else and $ref keyword independence (SchemaRef still uses either Ref OR Value, not both. $ref alongside description/default not supported)

[RobbertDM]

I am trying to run this against my OpenAPI 3.1 spec as you suggest @jamietanna .
For that, I am trying to make the 3.1 option available to the CLI. (in cmd/validate/main.go)
This PR refers a couple different variables that can be set, namely UseJSONSchema2020Validator, UseJsonSchema2020 and EnableJsonSchema2020().

I think the first one is only referenced in the docs openapi3/ISSUE_230.md

if doc.IsOpenAPI3_1() {
    openapi3.UseJSONSchema2020Validator = true
    fmt.Println("openAPI 3.1 document detected")
}

Did you mean UseJSONSchema2020 here, @chanceattoast ? Or is this a global option that was not implemented yet?

The two others openapi3.UseJsonSchema2020 and openapi3.EnableJsonSchema2020() seem to be options that you can set on the VisitJSON method, which is not exposed in the CLI, since it's a SchemaValidationOption, not a ValidationOption.

[RobbertDM]

Another problem is that in openapi3/schema.go, in the validate method, the NullType is not in the switch/case so will always be rejected. I think an easy fix is to add a case statement like

case TypeNull:                                                                                                                                                                      │
  if !validationOpts.jsonSchema2020ValidationEnabled {                                                                                                                            
    return stack, fmt.Errorf("unsupported 'type' value %q", schemaType)                                                                                                             } 

[RobbertDM]

Then in refs.go, extra sibling fields are not allowed

	if len(extras) != 0 {
		return fmt.Errorf("extra sibling fields: %+v", extras)
        }

Should also become

	if len(extras) != 0 {
		if !getValidationOptions(ctx).jsonSchema2020ValidationEnabled {
			return fmt.Errorf("extra sibling fields: %+v", extras)
		}
	}

[RobbertDM]

Sorry for the spam, I made a PR with fixes here https://github.com/chanceattoast/kin-openapi-fork/pull/1/files
Just to set expectations, I just have a few spare days now, I don't have time in 2026 to work on this.