openapi 3.1.0 Schema is missing $defs information

[spacether]

openapi 3.1.0 Schema is missing $defs information
In this file: https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-models/src/main/java/io/swagger/v3/oas/models/media/Schema.java

#defs information is not included from the openapi document schema
This prevents downstream users of this library from being able to implement the 3.1.0 and 2020-12 json schema $defs feature

[aqeelat]

Confirming this is still the case on 2.2.50 and on current master. Schema already models the other 2020-12 keywords that were added incrementally — $dynamicAnchor (2.2.14), $dynamicRef (2.2.32), $anchor, $id, $schema, $vocabulary, patternProperties, contains, contentSchema, propertyNames, unevaluatedProperties, dependentSchemas, prefixItems — but $defs is the notable omission.

Producer use case. Downstream OpenAPI 3.1 producers need $defs to emit the spec-correct generic/template pattern with $dynamicRef/$dynamicAnchor. A generic Response<T> used as Response<Pet> / Response<Group> should produce one reusable template plus an inline binding at each usage site:

components:
  schemas:
    Response:                  # template
      $dynamicAnchor: dataType
      properties:
        data: { $dynamicRef: '#dataType' }
      $defs:
        dataType: { $dynamicAnchor: dataType, not: {} }   # unbound slot
paths:
  /pet:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:                                         # inline binding
                $ref: '#/components/schemas/Response'
                $defs:
                  dataType: { $dynamicAnchor: dataType, $ref: '#/components/schemas/Pet' }

The $defs entry rebinds the outermost dynamic anchor at the point of use without applying the concrete schema to the enclosing instance — the only correct shape. The natural alternative (allOf: [$ref template, {$dynamicAnchor, $ref concrete}]) is invalid: allOf validates all subschemas against the same instance, so the concrete schema applies to the whole wrapper and valid parameterized instances fail validation. Without $defs, producers can't emit this pattern correctly.

Workarounds (verified on 2.2.50) and why they're inadequate:

• schema.addExtension("$defs", defs) is silently dropped — addExtension only accepts x--prefixed keys, no exception/warning.
• Reflection-injecting $defs into the private extensions map works (the serializer emits extensions verbatim via @JsonAnyGetter), but it depends on a private field and is fragile.
• setJsonSchema(Map) exists as a raw escape hatch, but it's all-or-nothing rather than a targeted $defs field.

This isn't just a producer problem — the consumer side is forced into the same workaround. Because Schema has no $defs field, $defs lands in extensions on parse, so swagger-parser's OAS 3.1 dereferencer has to traverse $defs out of the extensions map (see swagger-api/swagger-parser#2332). A first-class $defs field would let both producers and consumers handle it directly.

Proposed API — a first-class field mirroring the existing 2020-12 additions:

@OpenAPI31
private Map<String, Schema> $defs;
// get$defs() / set$defs(Map) / $defs(Map) / add$defs(String, Schema)

…wired into the V31 serializer mixin alongside $dynamicAnchor/$dynamicRef and into the V31 deserializer. $defs is a core JSON Schema 2020-12 keyword and the missing piece for round-tripping/emitting 3.1 documents that use dynamic references generically.

I would like to open a PR