Support additional OpenAPI 3.1 / JSON Schema 2020-12 features

Follow-up to the $ref+description fix, addressing further 3.1 gaps found in an
audit of the schema generator. Structural correctness fixes (narrow blast
radius; only affect specs using these constructs):

- $defs: collect top-level `$defs` as a schema source and resolve
  `$ref: '#/$defs/...'` (ApiTool.getComponentSchemas). Models under $defs now
  generate and are referenceable.
- prefixItems / items:false: tuple arrays and `items:false` degrade to
  List<Object> instead of an empty/invalid element type.
- type:"null": a scalar null type degrades to Object instead of emitting an
  invalid `null` Java type.
- nullability: a field that is nullable (3.0 `nullable:true` or the 3.1
  ["T","null"] idiom) is no longer marked required, so no spurious @NotNull is
  generated (ApiTool.isNullable).
- patternProperties: an object with patternProperties maps to Map<String,V>
  instead of an empty POJO.
- 3.1 binary strings: `contentEncoding` / `contentMediaType` are recognised as
  binary (MultipartFile), complementing `format: binary`.

Adds regression test `testOpenApi31Completeness` covering all of the above.

Documented limitations (left non-breaking, deferred as larger work):
- multi-type unions still pick the first concrete type (tested behaviour;
  needs a real union type model);
- description/summary/examples propagation (wide blast radius: 51 specs use
  field-level description);
- contains/propertyNames/unevaluated*/dependent*/if-then-else validation
  (needs new validators; parsed-through today);
- info.summary / license.identifier metadata;
- $id/$anchor resolution and $schema/$dynamicRef (ignored non-fatally).

Bumps version 6.4.2 -> 6.5.0 (new features).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: joseegarcia

multiapi-engine/pom.xml

@@ -4,7 +4,7 @@
 
   <groupId>com.sngular</groupId>
   <artifactId>multiapi-engine</artifactId>
-  <version>6.4.2</version>
+  <version>6.5.0</version>
   <packaging>jar</packaging>
 
   <properties>

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/tools/ApiTool.java

@@ -42,6 +42,8 @@ public final class ApiTool {
 
   public static final String SCHEMAS = "schemas";
 
+  public static final String DEFS = "$defs";
+
   public static final String REQUIRED = "required";
 
   public static final String PARAMETERS = "parameters";
@@ -153,7 +155,21 @@ public static JsonNode getItems(final JsonNode schema) {
   }
 
   public static Map<String, JsonNode> getComponentSchemas(final JsonNode openApi) {
-    return getComponentSchemasByType(openApi, SCHEMAS);
+    final var schemasMap = getComponentSchemasByType(openApi, SCHEMAS);
+    // JSON Schema 2020-12 / OpenAPI 3.1: reusable schemas may live under a
+    // top-level `$defs` object instead of `components/schemas`.
+    schemasMap.putAll(getDefsSchemas(openApi));
+    return schemasMap;
+  }
+
+  private static Map<String, JsonNode> getDefsSchemas(final JsonNode openApi) {
+    final var schemasMap = new HashMap<String, JsonNode>();
+    if (hasNode(openApi, DEFS)) {
+      final var defs = getNode(openApi, DEFS);
+      defs.fieldNames().forEachRemaining(name -> schemasMap.put(
+          DEFS.toUpperCase() + "/" + StringCaseUtils.titleToSnakeCase(name), getNode(defs, name)));
+    }
+    return schemasMap;
   }
 
   private static Map<String, JsonNode> getComponentSchemasByType(final JsonNode openApi, final String schemaType) {
@@ -226,7 +242,15 @@ public static String getType(final JsonNode schema) {
       return "";
     }
     final JsonNode typeNode = getNode(schema, "type");
-    return typeNode.isArray() ? getArrayType(typeNode) : StringUtils.defaultIfEmpty(typeNode.textValue(), "");
+    if (typeNode.isArray()) {
+      return getArrayType(typeNode);
+    }
+    // OpenAPI 3.1 / JSON Schema 2020-12: a scalar `type: "null"` carries no concrete
+    // Java type; degrade to object so we never emit an invalid `null` type.
+    if (TypeConstants.NULL.equalsIgnoreCase(typeNode.textValue())) {
+      return TypeConstants.OBJECT;
+    }
+    return StringUtils.defaultIfEmpty(typeNode.textValue(), "");
   }
 
   private static String getArrayType(final JsonNode typeNode) {
@@ -347,17 +371,59 @@ public static boolean isDateTime(final JsonNode schema) {
   public static boolean isBinary(final JsonNode schema) {
     final boolean isMultipartFile;
     if (hasType(schema) && TypeConstants.STRING.equalsIgnoreCase(getType(schema))) {
-      if (hasNode(schema, FORMAT)) {
-        isMultipartFile = "binary".equalsIgnoreCase(getNode(schema, FORMAT).textValue());
+      if (hasNode(schema, FORMAT) && "binary".equalsIgnoreCase(getNode(schema, FORMAT).textValue())) {
+        isMultipartFile = true;
       } else {
-        isMultipartFile = false;
+        // OpenAPI 3.1 / JSON Schema 2020-12 replace `format: binary` with the
+        // `contentEncoding` / `contentMediaType` keywords for binary payloads.
+        isMultipartFile = hasNode(schema, "contentEncoding") || hasNode(schema, "contentMediaType");
       }
     } else {
       isMultipartFile = false;
     }
     return isMultipartFile;
   }
 
+  public static boolean isNullable(final JsonNode schema) {
+    if (Objects.isNull(schema)) {
+      return false;
+    }
+    // OpenAPI 3.0 `nullable: true`.
+    if (getNodeAsBoolean(schema, "nullable")) {
+      return true;
+    }
+    // OpenAPI 3.1 idiom: `type: ["<type>", "null"]`.
+    if (hasType(schema)) {
+      final JsonNode typeNode = getNode(schema, "type");
+      if (typeNode.isArray()) {
+        for (final JsonNode element : typeNode) {
+          if (TypeConstants.NULL.equalsIgnoreCase(element.asText())) {
+            return true;
+          }
+        }
+      } else {
+        return TypeConstants.NULL.equalsIgnoreCase(typeNode.textValue());
+      }
+    }
+    return false;
+  }
+
+  public static boolean hasPatternProperties(final JsonNode schema) {
+    return hasNode(schema, "patternProperties");
+  }
+
+  public static JsonNode getPatternProperties(final JsonNode schema) {
+    return getNode(schema, "patternProperties");
+  }
+
+  public static boolean hasPrefixItems(final JsonNode schema) {
+    return hasNode(schema, "prefixItems");
+  }
+
+  public static JsonNode getPrefixItems(final JsonNode schema) {
+    return getNode(schema, "prefixItems");
+  }
+
   public static List<JsonNode> findContentSchemas(final JsonNode schema) {
     return hasNode(schema, "content") ? schema.findValues("schema") : Collections.emptyList();
   }

multiapi-engine/src/main/java/com/sngular/api/generator/plugin/common/tools/ModelBuilder.java

@@ -169,12 +169,12 @@ private static Set<SchemaFieldObject> getFields(
                                                                          baseDir));
       }
     } else if (TypeConstants.ARRAY.equalsIgnoreCase(ApiTool.getType(schema))) {
-      final String itemType = ApiTool.hasRef(ApiTool.getItems(schema)) ? MapperUtil.getPojoNameFromRef(ApiTool.getItems(schema), specFile, null)
-                                  : ApiTool.getType(ApiTool.getItems(schema));
       fieldObjectArrayList.add(SchemaFieldObject.builder()
                                                 .baseName("items")
-                                                .dataType(SchemaFieldObjectType.fromTypeList(TypeConstants.ARRAY, itemType))
+                                                .dataType(SchemaFieldObjectType.fromTypeList(TypeConstants.ARRAY, resolveArrayItemType(schema, specFile)))
                                                 .build());
+    } else if (ApiTool.hasPatternProperties(schema)) {
+      fieldObjectArrayList.add(buildPatternPropertiesField(ApiTool.getName(schema), schema, specFile));
     } else if (ApiTool.isAllOf(schema)) {
       fieldObjectArrayList.addAll(processAllOf(totalSchemas, ApiTool.getAllOf(schema), specFile, compositedSchemas, antiLoopList, baseDir));
     } else if (ApiTool.isAnyOf(schema)) {
@@ -209,6 +209,8 @@ private static List<SchemaFieldObject> processFieldObjectList(
       fieldObjectArrayList.addAll(processArray(fieldName, className, schema, specFile, totalSchemas, compositedSchemas, antiLoopList, baseDir));
     } else if (ApiTool.hasAdditionalProperties(schema)) {
       fieldObjectArrayList.addAll(processMap(fieldName, schema, specFile, totalSchemas, compositedSchemas, antiLoopList, baseDir));
+    } else if (ApiTool.hasPatternProperties(schema)) {
+      fieldObjectArrayList.add(buildPatternPropertiesField(fieldName, schema, specFile));
     } else if (ApiTool.hasRef(schema)) {
       fieldObjectArrayList.add(
           processRef(fieldName, schema, new SchemaFieldObjectType(MapperUtil.getSimpleType(schema, specFile)), totalSchemas, compositedSchemas, antiLoopList, specFile, baseDir));
@@ -426,11 +428,17 @@ private static List<SchemaFieldObject> processArray(
       final Map<String, SchemaObject> compositedSchemas, final Set<String> antiLoopList, final Path baseDir) {
     final List<SchemaFieldObject> fieldObjectArrayList = new LinkedList<>();
 
-    if (!ApiTool.hasItems(schema)) {
+    if (!ApiTool.hasItems(schema) || ApiTool.getItems(schema).isBoolean()) {
+      // No `items` schema, or `items: false` (JSON Schema 2020-12). If the array
+      // declares positional `prefixItems` (tuple), or nothing typable at all, the
+      // element type degrades to Object -> List<Object>.
+      final boolean isTuple = ApiTool.hasPrefixItems(schema);
       fieldObjectArrayList.add(SchemaFieldObject
                                    .builder()
                                    .baseName(fieldName)
-                                   .dataType(new SchemaFieldObjectType(TypeConstants.OBJECT))
+                                   .dataType(isTuple
+                                                 ? SchemaFieldObjectType.fromTypeList(TypeConstants.ARRAY, TypeConstants.OBJECT)
+                                                 : new SchemaFieldObjectType(TypeConstants.OBJECT))
                                    .build());
     } else {
       final var items = ApiTool.getItems(schema);
@@ -626,7 +634,9 @@ private static SchemaObject createComposedSchema(
   private static void setFieldType(
       final SchemaFieldObject field, final JsonNode schemaProperty, final JsonNode schema,
       final CommonSpecFile specFile, final String key) {
-    field.setRequired(ApiTool.hasRequired(schema) && ApiTool.checkIfRequired(schema, key));
+    // A nullable field (3.0 `nullable: true` or the 3.1 ["T","null"] idiom) must not be
+    // marked required, otherwise the generated @NotNull would reject a legitimate null value.
+    field.setRequired(ApiTool.hasRequired(schema) && ApiTool.checkIfRequired(schema, key) && !ApiTool.isNullable(schemaProperty));
     if (ApiTool.isArray(schemaProperty)) {
       final String typeArray;
       if (ApiTool.hasItems(schemaProperty)) {
@@ -888,5 +898,38 @@ private static String getImportClass(final String type) {
     return StringUtils.isNotBlank(type) && !TypeConstants.NO_IMPORT_TYPE.contains(type) ? StringUtils.capitalize(type) : "";
   }
 
+  private static String resolveArrayItemType(final JsonNode schema, final CommonSpecFile specFile) {
+    final var items = ApiTool.getItems(schema);
+    if (Objects.nonNull(items) && !items.isBoolean()) {
+      return ApiTool.hasRef(items) ? MapperUtil.getPojoNameFromRef(items, specFile, null) : ApiTool.getType(items);
+    }
+    // `prefixItems` (tuple) or `items: false` -> degrade the element type to Object.
+    return TypeConstants.OBJECT;
+  }
+
+  private static SchemaFieldObject buildPatternPropertiesField(
+      final String fieldName, final JsonNode schema, final CommonSpecFile specFile) {
+    // JSON Schema 2020-12 `patternProperties` maps regex keys to a value schema.
+    // We model it as Map<String, ValueType> using the first declared pattern's value schema.
+    final var patternProps = ApiTool.getPatternProperties(schema);
+    final var valueSchemas = patternProps.elements();
+    final JsonNode valueSchema = valueSchemas.hasNext() ? valueSchemas.next() : null;
+    final String valueType;
+    if (Objects.isNull(valueSchema)) {
+      valueType = TypeConstants.OBJECT;
+    } else if (ApiTool.hasRef(valueSchema)) {
+      valueType = MapperUtil.getPojoNameFromRef(valueSchema, specFile, null);
+    } else if (isBasicType(valueSchema) && ApiTool.hasType(valueSchema)) {
+      valueType = MapperUtil.getSimpleType(valueSchema, specFile);
+    } else {
+      valueType = TypeConstants.OBJECT;
+    }
+    return SchemaFieldObject
+               .builder()
+               .baseName(StringUtils.defaultIfBlank(fieldName, ADDITIONAL_PROPERTIES))
+               .dataType(SchemaFieldObjectType.fromTypeList(TypeConstants.MAP, valueType))
+               .build();
+  }
+
 
 }

multiapi-engine/src/test/java/com/sngular/api/generator/plugin/openapi/OpenApiGeneratorFixtures.java

@@ -182,6 +182,13 @@ public final class OpenApiGeneratorFixtures {
 					.clientPackage("com.sngular.multifileplugin.refwithdescription.client")
 					.modelNameSuffix("DTO").build());
 
+	static final List<SpecFile> TEST_OPEN_API_31_COMPLETENESS = List
+			.of(SpecFile.builder().filePath("openapigenerator/testOpenApi31Completeness/api-test.yml")
+					.apiPackage("com.sngular.multifileplugin.openapi31completeness")
+					.modelPackage("com.sngular.multifileplugin.openapi31completeness.model")
+					.clientPackage("com.sngular.multifileplugin.openapi31completeness.client")
+					.modelNameSuffix("DTO").build());
+
 	static final List<SpecFile> TEST_EXTERNAL_PATH_ITEM_REF_GENERATION = List
 			.of(SpecFile.builder().filePath("openapigenerator/testExternalPathItemRefsGeneration/api-test.yml")
 					.apiPackage("com.sngular.multifileplugin.externalpathitemref")
@@ -891,6 +898,25 @@ static Function<Path, Boolean> validateOpenApi31Types() {
     DEFAULT_MODEL_API, Collections.emptyList(), null);
   }
 
+	static Function<Path, Boolean> validateOpenApi31Completeness() {
+
+		final String DEFAULT_TARGET_API = "generated/com/sngular/multifileplugin/openapi31completeness";
+
+		final String DEFAULT_MODEL_API = "generated/com/sngular/multifileplugin/openapi31completeness/model";
+
+		final String COMMON_PATH = "openapigenerator/testOpenApi31Completeness/";
+
+		final String ASSETS_PATH = COMMON_PATH + "assets/";
+
+		final List<String> expectedTestApiFile = List.of(ASSETS_PATH + "GadgetApi.java");
+
+		final List<String> expectedTestApiModelFiles = List.of(ASSETS_PATH + "GadgetDTO.java",
+				ASSETS_PATH + "PersonDTO.java");
+
+		return path -> commonTest(path, expectedTestApiFile, expectedTestApiModelFiles, DEFAULT_TARGET_API,
+				DEFAULT_MODEL_API, Collections.emptyList(), null);
+	}
+
 	static Function<Path, Boolean> validateRefWithDescription() {
 
 		final String DEFAULT_TARGET_API = "generated/com/sngular/multifileplugin/refwithdescription";

multiapi-engine/src/test/java/com/sngular/api/generator/plugin/openapi/OpenApiGeneratorTest.java

@@ -87,6 +87,8 @@ static Stream<Arguments> fileSpecToProcess() {
             OpenApiGeneratorFixtures.validateOpenApi31Types()),
         Arguments.of("testRefWithDescription", OpenApiGeneratorFixtures.TEST_REF_WITH_DESCRIPTION,
             OpenApiGeneratorFixtures.validateRefWithDescription()),
+        Arguments.of("testOpenApi31Completeness", OpenApiGeneratorFixtures.TEST_OPEN_API_31_COMPLETENESS,
+            OpenApiGeneratorFixtures.validateOpenApi31Completeness()),
         Arguments.of("testWebhooks", OpenApiGeneratorFixtures.TEST_WEBHOOKS,
             OpenApiGeneratorFixtures.validateWebhooks()),
         Arguments.of("testOpenApi31Union", OpenApiGeneratorFixtures.TEST_OPEN_API_31_UNION,

multiapi-engine/src/test/resources/openapigenerator/testOpenApi31Completeness/api-test.yml

@@ -0,0 +1,66 @@
+---
+# Regression for additional OpenAPI 3.1 / JSON Schema 2020-12 features:
+#  - $defs as a schema source (#/$defs/Person)                     -> generates PersonDTO
+#  - prefixItems tuple arrays                                       -> List<Object>
+#  - scalar type: "null"                                            -> Object (no invalid `null` type)
+#  - nullable via ["T","null"] idiom even when listed as required   -> no @NotNull
+#  - patternProperties object                                       -> Map<String, T>
+#  - 3.1 binary string via contentEncoding                          -> MultipartFile
+openapi: "3.1.0"
+info:
+  version: 1.0.0
+  title: Gadget API (OpenAPI 3.1)
+  license:
+    name: MIT
+servers:
+  - url: http://localhost:8080/v1
+tags:
+  - name: gadget
+paths:
+  /gadget:
+    get:
+      summary: Get a gadget
+      operationId: getGadget
+      tags:
+        - gadget
+      responses:
+        '200':
+          description: The requested gadget
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Gadget"
+components:
+  schemas:
+    Gadget:
+      type: object
+      required:
+        - serial
+      properties:
+        id:
+          type: string
+        serial:
+          type: ["string", "null"]
+        payload:
+          type: string
+          contentEncoding: base64
+        coords:
+          type: array
+          prefixItems:
+            - type: number
+            - type: number
+        metadata:
+          type: object
+          patternProperties:
+            "^x-":
+              type: string
+        nothing:
+          type: "null"
+        owner:
+          $ref: "#/$defs/Person"
+$defs:
+  Person:
+    type: object
+    properties:
+      name:
+        type: string

multiapi-engine/src/test/resources/openapigenerator/testOpenApi31Completeness/assets/GadgetApi.java

@@ -0,0 +1,46 @@
+package com.sngular.multifileplugin.openapi31completeness;
+
+import java.util.Optional;
+import java.util.List;
+import java.util.Map;
+import javax.validation.Valid;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import org.springframework.http.MediaType;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.context.request.NativeWebRequest;
+
+import com.sngular.multifileplugin.openapi31completeness.model.GadgetDTO;
+
+public interface GadgetApi {
+
+  /**
+   * GET /gadget: Get a gadget
+   * @return  The requested gadget; (status code 200)
+   */
+
+  @Operation(
+    operationId = "getGadget",
+    summary = "Get a gadget",
+    tags = {"gadget"},
+    responses = {
+      @ApiResponse(responseCode = "200", description = "The requested gadget", content = @Content(mediaType = "application/json", schema = @Schema(implementation = GadgetDTO.class)))
+    }
+  )
+  @RequestMapping(
+    method = RequestMethod.GET,
+    value = "/gadget",
+    produces = {"application/json"}
+  )
+
+  default ResponseEntity<GadgetDTO> getGadget() {
+    return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
+  }
+
+}