Summary

Hello maintainers 👋

New contributor to this project, so feedback very much welcome & appreciated!

We just upgraded our internal OAS Spec to version 3.1, before running in to #373 3.1 compatibility issues. Instead of downgrading, I have some cycles to spend on hopefully progressing some of the tasks under OpenAPI 3.1 support.

This is the first in a small series of PRs to hopefully make progress towards the changed nullable behaviour in OAS 3.1, while ensuring backwards compatibility.

Open Questions up-front:

• Is this the right approach?
• If not, should this live elsewhere?
  • https://github.com/oapi-codegen/nullable ?
  • or upstream in https://github.com/getkin/kin-openapi?
• Is the assumption of "Empty schemas being treated as non-nullable to avoid over-detection in codegen" a valid one?

This PR

nullable.go handles null in line with JSON schema core 2020-12 spec for OAS 3.1, with one explicit generator policy:
Empty schemas {} are treated as non-nullable to avoid over-detection in codegen.

What's included:

• Centralised 3.1 null detector in pkg/codegen/nullable.go (this PR) but not wired up yet.
  • Exports IsSchemaNullable(specVersion string, schema *openapi3.SchemaRef) bool
  • Keeps default behaviour unchanged (i.e. output-options.nullable-type exists in configuration-schema.json, default false)
  • 3.1: Considers type (including union with 'null'), oneOf/anyOf/allOf, enum (null present), and not (blocks null if it accepts null)
  • 3.0: Falls back to schema.Value.Nullable for nullable: true compatibility
  • a single file keeps logic consistent and avoids scattered special cases throughout the codebase.
• Tests in pkg/codegen/nullability_test.go
  • Validates consistency against patterns from the JSON Schema Test Suite.

Note: The detector intentionally diverges from raw JSON Schema for {} as explained above.

The logic & test coverage of oneOf/anyOf/allOf got a little hairy, so I found I understood it better once I sketched it out.

• General rule (where k is “how many subschemas explicitly allow null”):
  • anyOf: k ≥ 1
  • oneOf: k = 1
  • allOf: k = total number of subschemas

e.g.

• [ {'type':'string'} ] is zero subschemas, k=0
• [ {'type':'null'} ] is one subschema, k=1
• [ {'type':'null'}, {'type':'null'} ] k=2, etc...

appendix below with full test coverage matrix.

Future Work

• If above PR is accepted, integrate IsSchemaNullable() into the broader codebase,
• Feature-flag: Wire up existing output-options.nullable-type config
  • When output-options.nullable-type is enabled, use nullable.Value[T] from github.com/oapi-codegen/nullable (previously nullable.Nullable[T]), non-blocking PR: feat(codegen): emit nullable.Value[T] when nullable-type is enabled #2067
  • Otherwise retain existing behaviour for 3.0 users
• Version gating and safety
  • Detect spec version; enable 3.1 paths only when openapi: 3.1.*
  • Provide unit-test coverage for detector behavior on both 3.0 and 3.1 inputs

Delivery plan

rough PR split

• PR1: detector (unused) + tests <- this PR
• PR2: Explicit feature-flag & initial schema integration,
• PR3: Version gating & safety,
• PR4?: Cleanup, docs touch-ups, internal refactors if needed

Checklist

• Tests added/updated (for new features or bug fixes)
• Documentation updated (README/CONTRIBUTING/examples as needed) N/A
• make tidy is run locally
• make test is run locally
• make generate run is run locally and outputs committed (if generated code is affected) N/A
• make lint is run locally

Additional context

• oapi-codegen Project Board for 3.1 support
• json-schema-org anyOf JSON Schema Test Suite
• Clarification on nullable properties, OpenAPI 3.1 OAI/OpenAPI-Specification#3148

Test Coverage of all cases: