Issue 230: Add OpenAPI 3.1 Support #1102
Conversation
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](https://github.com/santhosh-tekuri/jsonschema): - 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
…d formatting and correcting the version logic
|
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 |
|
Thank you for contributing this @chanceattoast ! So excited for this to be merged so we can finally upgrade oasdiff. |
|
thank you for this!! |
|
@jamietanna here's the answers to your questions and sorry for the delay in responding:
Yes, I used Claude code to help
Yes it has and it worked well from the 3.1 files we have
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 |
6 participants
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 validationExamples- Array of examples (replaces singularexample)PrefixItems- Tuple validation for arraysContains,MinContains,MaxContains- Array containment validationPatternProperties- Pattern-based property matchingDependentSchemas- Conditional schema dependenciesPropertyNames- Property name validationUnevaluatedItems,UnevaluatedProperties- Unevaluated keyword support["string", "null"]notation2. Document-Level Features (openapi3/openapi3.go)
Webhooks- New field for defining webhook callbacks (OpenAPI 3.1)JSONSchemaDialect- Specifies default JSON Schema dialectIsOpenAPI3_0()- Returns true for 3.0.x documentsIsOpenAPI3_1()- Returns true for 3.1.x documentsVersion()- Returns major.minor version string3. 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 includedIsMultiple()- Detects type arrays (OpenAPI 3.1 feature)IsSingle()- Checks for single typeIsEmpty()- Checks for unspecified types6. JSON Schema 2020-12 Validator (openapi3/schema_jsonschema_validator.go)
A new opt-in validator using santhosh-tekuri/jsonschema/v6:
nullableto type arraysexclusiveMinimum/exclusiveMaximumconversion