feat: support for deepObject explode=true

* Initial support for deepObject, per spec only for explode=true

* Spotless apply

* Added requested unit tests, some cleanup

* override transformPrimitive for deepObject and throw an exception, early validation for deepObject + non-object schema type

* Fix transformObject -> transformPrimitive call breakage, fix unit test exception expectation

* More informative exception message for primitive transformation in deep object transformer

Author: rikvb

src/main/java/io/vertx/openapi/contract/impl/ParameterImpl.java

@@ -13,6 +13,7 @@
 package io.vertx.openapi.contract.impl;
 
 import static io.vertx.json.schema.common.dsl.SchemaType.ARRAY;
+import static io.vertx.json.schema.common.dsl.SchemaType.OBJECT;
 import static io.vertx.openapi.contract.Location.COOKIE;
 import static io.vertx.openapi.contract.Location.HEADER;
 import static io.vertx.openapi.contract.Location.PATH;
@@ -111,9 +112,15 @@ public ParameterImpl(String path, JsonObject parameterModel) {
       if (!(style == FORM || style == SPACE_DELIMITED || style == PIPE_DELIMITED || style == DEEP_OBJECT)) {
         throw createInvalidStyle(in, "form, spaceDelimited, pipeDelimited or deepObject");
       } else {
-        if (style == SPACE_DELIMITED || style == PIPE_DELIMITED || style == DEEP_OBJECT) {
+        if (style == SPACE_DELIMITED || style == PIPE_DELIMITED) {
           throw createUnsupportedFeature("Parameters of style: " + style);
         }
+        if (style == DEEP_OBJECT && !explode) {
+          throw createUnsupportedFeature("Query parameter in non-exploded deepObject style");
+        }
+        if (style == DEEP_OBJECT && schemaType != OBJECT) {
+          throw createUnsupportedFeature("Query parameter in deepObject style can only be an object");
+        }
       }
     }
   }

src/main/java/io/vertx/openapi/validation/ValidatorErrorType.java

@@ -49,5 +49,10 @@ public enum ValidatorErrorType {
   /**
    * The response can't get validated due to missing response definition for the related status code information.
    */
-  MISSING_RESPONSE
+  MISSING_RESPONSE,
+
+  /**
+   * Transformation to the chosen output format is not supported.
+   */
+  UNSUPPORTED_TRANSFORMATION
 }

src/main/java/io/vertx/openapi/validation/ValidatorException.java

@@ -17,10 +17,13 @@
 import static io.vertx.openapi.validation.ValidatorErrorType.MISSING_OPERATION;
 import static io.vertx.openapi.validation.ValidatorErrorType.MISSING_REQUIRED_PARAMETER;
 import static io.vertx.openapi.validation.ValidatorErrorType.MISSING_RESPONSE;
+import static io.vertx.openapi.validation.ValidatorErrorType.UNSUPPORTED_TRANSFORMATION;
 import static io.vertx.openapi.validation.ValidatorErrorType.UNSUPPORTED_VALUE_FORMAT;
 
 import io.vertx.core.http.HttpMethod;
+import io.vertx.json.schema.common.dsl.SchemaType;
 import io.vertx.openapi.contract.Parameter;
+import io.vertx.openapi.contract.Style;
 
 /**
  * A ValidatorException is thrown, if the validation of a request or response fails. The validation can fail for
@@ -61,6 +64,11 @@ public static ValidatorException createUnsupportedValueFormat(Parameter paramete
     return new ValidatorException(msg, UNSUPPORTED_VALUE_FORMAT);
   }
 
+  public static ValidatorException createUnsupportedTransformation(Style style, SchemaType schemaType) {
+    String msg = String.format("Transformation in style %s to schema type %s is not supported.", style, schemaType);
+    return new ValidatorException(msg, UNSUPPORTED_TRANSFORMATION);
+  }
+
   public static ValidatorException createCantDecodeValue(Parameter parameter) {
     String msg = String.format("The value of %s parameter %s can't be decoded.", parameter.getIn().name().toLowerCase(),
         parameter.getName());

src/main/java/io/vertx/openapi/validation/impl/RequestValidatorImpl.java

@@ -13,6 +13,7 @@
 package io.vertx.openapi.validation.impl;
 
 import static io.vertx.core.Future.failedFuture;
+import static io.vertx.openapi.contract.Style.DEEP_OBJECT;
 import static io.vertx.openapi.contract.Style.FORM;
 import static io.vertx.openapi.contract.Style.LABEL;
 import static io.vertx.openapi.contract.Style.MATRIX;
@@ -41,6 +42,7 @@
 import io.vertx.openapi.validation.ValidatableRequest;
 import io.vertx.openapi.validation.ValidatedRequest;
 import io.vertx.openapi.validation.ValidatorException;
+import io.vertx.openapi.validation.transformer.DeepObjectTransformer;
 import io.vertx.openapi.validation.transformer.FormTransformer;
 import io.vertx.openapi.validation.transformer.LabelTransformer;
 import io.vertx.openapi.validation.transformer.MatrixTransformer;
@@ -60,6 +62,7 @@ public RequestValidatorImpl(Vertx vertx, OpenAPIContract contract) {
     parameterTransformers.put(LABEL, new LabelTransformer());
     parameterTransformers.put(MATRIX, new MatrixTransformer());
     parameterTransformers.put(FORM, new FormTransformer());
+    parameterTransformers.put(DEEP_OBJECT, new DeepObjectTransformer());
   }
 
   @Override

src/main/java/io/vertx/openapi/validation/transformer/DeepObjectTransformer.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2011-2025 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+package io.vertx.openapi.validation.transformer;
+
+import static io.vertx.json.schema.common.dsl.SchemaType.OBJECT;
+import static io.vertx.openapi.contract.Style.DEEP_OBJECT;
+import static io.vertx.openapi.validation.ValidatorException.createUnsupportedTransformation;
+
+import io.vertx.json.schema.common.dsl.SchemaType;
+import io.vertx.openapi.contract.Parameter;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * <p>
+ * +------------+---------+--------+----------+-----------+-------------------------------------------+
+ * | style      | explode | empty  | string   | array     | object                                    |
+ * +------------+---------+--------+----------+-----------+-------------------------------------------+
+ * | deepObject | true    | n/a    | n/a      | n/a       | dummy[role]=admin&dummy[firstName]=Alex   |
+ * +------------+---------+--------+----------+-----------+-------------------------------------------+
+ */
+public class DeepObjectTransformer extends ParameterTransformer {
+
+  /**
+   * Matches name=[key]=value
+   */
+  private final Pattern PATTERN = Pattern.compile("(\\w+)\\[(\\w+)]\\s*=\\s*([^&]+)");
+
+  @Override
+  public Object transformPrimitive(SchemaType type, String rawValue) {
+    // as transformObject calls transformPrimitive internally, we delegate to the base method for type OBJECT
+    // to avoid breaking transformObject.
+    if (type == OBJECT)
+      return super.transformPrimitive(type, rawValue);
+    throw createUnsupportedTransformation(DEEP_OBJECT, type);
+  }
+
+  @Override
+  protected String[] getObjectKeysAndValues(Parameter parameter, String rawValue) {
+    Matcher matcher = PATTERN.matcher(rawValue);
+
+    List<String> keysAndValues = new ArrayList<>();
+    while (matcher.find()) {
+      String name = matcher.group(1);
+      String key = matcher.group(2);
+      String value = matcher.group(3);
+
+      if (parameter.getName().equals(name)) {
+        keysAndValues.add(key);
+        keysAndValues.add(value);
+      }
+    }
+
+    return keysAndValues.toArray(new String[keysAndValues.size()]);
+  }
+
+  @Override
+  public Object transformArray(Parameter parameter, String rawValue) {
+    throw createUnsupportedTransformation(parameter.getStyle(), parameter.getSchemaType());
+  }
+
+  @Override
+  protected String[] getArrayValues(Parameter parameter, String rawValue) {
+    // this is never called due to transformArray overridden and throwing an exception.
+    return null;
+  }
+
+}

src/test/java/io/vertx/tests/contract/impl/ParameterImplTest.java

@@ -90,15 +90,18 @@ private static Stream<Arguments> provideErrorScenarios() {
         Arguments.of("0008_Query_With_Wrong_Style", INVALID_SPEC,
             "The passed OpenAPI contract is invalid: The style of a query parameter MUST be form, spaceDelimited, pipeDelimited or deepObject"),
         Arguments.of("0009_Query_With_Unsupported_Style_DeepObject", UNSUPPORTED_FEATURE,
-            "The passed OpenAPI contract contains a feature that is not supported: Parameters of style: deepObject"),
+            "The passed OpenAPI contract contains a feature that is not supported: Query parameter in non-exploded deepObject style"),
         Arguments.of("0010_Query_With_Unsupported_Style_SpaceDelimited", UNSUPPORTED_FEATURE,
             "The passed OpenAPI contract contains a feature that is not supported: Parameters of style: spaceDelimited"),
         Arguments.of("0011_Query_With_Unsupported_Style_pipeDelimited", UNSUPPORTED_FEATURE,
             "The passed OpenAPI contract contains a feature that is not supported: Parameters of style: pipeDelimited"),
         Arguments.of("0012_With_Schema_No_Type", INVALID_SPEC,
             "The passed OpenAPI contract is invalid: Missing \"type\" for \"schema\" property in parameter: petId"),
         Arguments.of("0013_Cookie_With_Unsupported_Combination_Array_And_Exploded", UNSUPPORTED_FEATURE,
-            "The passed OpenAPI contract contains a feature that is not supported: Cookie parameter values formatted as exploded array"));
+            "The passed OpenAPI contract contains a feature that is not supported: Cookie parameter values formatted as exploded array"),
+        Arguments.of("0014_Query_With_Unsupported_Schema_DeepObject", UNSUPPORTED_FEATURE,
+            "The passed OpenAPI contract contains a feature that is not supported: Query parameter in deepObject style can only be an object"));
+
   }
 
   private static Stream<Arguments> provideDefaultValuesScenarios() {

src/test/java/io/vertx/tests/validation/ValidatorExceptionTest.java

@@ -85,4 +85,13 @@ void testCreateResponseNotFound() {
     assertThat(exception).hasMessageThat().isEqualTo(expectedMsg);
     assertThat(exception.type()).isEqualTo(ValidatorErrorType.MISSING_RESPONSE);
   }
+
+  @Test
+  void testCreateUnsupportedTransformationFormat() {
+    ValidatorException exception = ValidatorException.createUnsupportedTransformation(DUMMY_PARAMETER.getStyle(),
+        DUMMY_PARAMETER.getSchemaType());
+    String expectedMsg = "Transformation in style label to schema type INTEGER is not supported.";
+    assertThat(exception).hasMessageThat().isEqualTo(expectedMsg);
+    assertThat(exception.type()).isEqualTo(ValidatorErrorType.UNSUPPORTED_TRANSFORMATION);
+  }
 }

src/test/java/io/vertx/tests/validation/impl/RequestValidatorImplTest.java

@@ -372,7 +372,7 @@ void testValidateParameterMissingParamIsNotRequired(String scenario, RequestPara
   }
 
   @ParameterizedTest(name = "{index} Throw UNSUPPORTED_VALUE_FORMAT error when param style is {0}")
-  @EnumSource(value = Style.class, names = { "SPACE_DELIMITED", "PIPE_DELIMITED", "DEEP_OBJECT" })
+  @EnumSource(value = Style.class, names = { "SPACE_DELIMITED", "PIPE_DELIMITED" })
   void testValidateParameterThrowUnsupportedValueFormat(Style style) {
     Parameter param = mockParameter("dummy", HEADER, style, false, JsonSchema.of(stringSchema().toJson()));
     ValidatorException exception = assertThrows(ValidatorException.class,

src/test/java/io/vertx/tests/validation/transformer/DeepObjectTransformerTest.java

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2011-2025 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+package io.vertx.tests.validation.transformer;
+
+import static com.google.common.truth.Truth.assertThat;
+import static io.vertx.openapi.contract.Location.QUERY;
+import static io.vertx.openapi.contract.Style.DEEP_OBJECT;
+import static io.vertx.openapi.impl.Utils.EMPTY_JSON_OBJECT;
+import static io.vertx.tests.MockHelper.mockParameter;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import io.vertx.core.json.JsonObject;
+import io.vertx.openapi.contract.Parameter;
+import io.vertx.openapi.validation.ValidatorException;
+import io.vertx.openapi.validation.transformer.DeepObjectTransformer;
+import java.util.stream.Stream;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+public class DeepObjectTransformerTest implements SchemaSupport {
+
+  private static final Parameter DEEP_OBJECT_PARAM = mockParameter(NAME, QUERY, DEEP_OBJECT, true, OBJECT_SCHEMA);
+  private static final Parameter DEEP_OBJECT_ARRAY_PARAM = mockParameter(NAME, QUERY, DEEP_OBJECT, true, ARRAY_SCHEMA);
+  private static final Parameter STRING_PARAM = mockParameter(NAME, QUERY, DEEP_OBJECT, false, STRING_SCHEMA);
+  private static final Parameter NUMBER_PARAM = mockParameter(NAME, QUERY, DEEP_OBJECT, false, NUMBER_SCHEMA);
+  private static final Parameter INTEGER_PARAM = mockParameter(NAME, QUERY, DEEP_OBJECT, false, INTEGER_SCHEMA);
+  private static final Parameter BOOLEAN_PARAM = mockParameter(NAME, QUERY, DEEP_OBJECT, false, BOOLEAN_SCHEMA);
+
+  private static final DeepObjectTransformer TRANSFORMER = new DeepObjectTransformer();
+
+  private static Stream<Arguments> provideValidPrimitiveValues() {
+    return Stream.of(
+        Arguments.of("(String) empty", STRING_PARAM, "", ""),
+        Arguments.of("(String) 44", STRING_PARAM, "44", "44"),
+        Arguments.of("(Integer) -100", INTEGER_PARAM, "-101", -101),
+        Arguments.of("(Number) 14.6767", NUMBER_PARAM, "14.6767", 14.6767),
+        Arguments.of("(Boolean) true", BOOLEAN_PARAM, "true", true));
+  }
+
+  private static Stream<Arguments> provideValidObjectValues() {
+    String complexExplodedRaw = "dummy[role]=admin&dummy[firstName]=Alex";
+    String complexExplodedRawWithExtras = "something=nothing&dummy[role]=admin&dummy[firstName]=Alex";
+    String complexExplodedRawWithAnotherParameter =
+        "dummy[role]=admin&dummy[firstName]=Alex&silly[role]=user&silly[firstName]=John";
+    JsonObject expected = new JsonObject().put("role", "admin").put("firstName", "Alex");
+
+    return Stream.of(
+        Arguments.of("empty", DEEP_OBJECT_PARAM, "", EMPTY_JSON_OBJECT),
+        Arguments.of(complexExplodedRaw + " (exploded)", DEEP_OBJECT_PARAM, complexExplodedRaw, expected),
+        Arguments.of(complexExplodedRawWithExtras + " (exploded)", DEEP_OBJECT_PARAM, complexExplodedRawWithExtras,
+            expected),
+        Arguments.of(complexExplodedRawWithAnotherParameter + " (exploded)", DEEP_OBJECT_PARAM,
+            complexExplodedRawWithAnotherParameter, expected));
+  }
+
+  @ParameterizedTest(name = "{index} Transform \"Query\" parameter of style \"deepObject\" with object value: {0}")
+  @MethodSource("provideValidObjectValues")
+  void testTransformObjectValid(String scenario, Parameter parameter, String rawValue, Object expectedValue) {
+    assertThat(TRANSFORMER.transformObject(parameter, rawValue)).isEqualTo(expectedValue);
+  }
+
+  @Test
+  void testInvalidTransformation() {
+    String validExplodedRaw = "dummy[role]=admin&dummy[firstName]=Alex";
+    ValidatorException exception =
+        assertThrows(ValidatorException.class, () -> TRANSFORMER.transform(DEEP_OBJECT_ARRAY_PARAM, validExplodedRaw));
+    String expectedMsg = "Transformation in style deepObject to schema type ARRAY is not supported.";
+    assertThat(exception).hasMessageThat().isEqualTo(expectedMsg);
+  }
+
+  @ParameterizedTest(name = "{index} Transform \"Query\" parameter of style \"deepObject\" with primitive value: {0}")
+  @MethodSource("provideValidPrimitiveValues")
+  void testTransformPrimitiveValid(String scenario, Parameter parameter, String rawValue, Object expectedValue) {
+    ValidatorException exception =
+        assertThrows(ValidatorException.class,
+            () -> TRANSFORMER.transformPrimitive(parameter.getSchemaType(), rawValue));
+    String expectedMsg = String.format("Transformation in style deepObject to schema type %s is not supported.",
+        parameter.getSchemaType());
+    assertThat(exception).hasMessageThat().isEqualTo(expectedMsg);
+  }
+}

src/test/resources/io/vertx/tests/contract/impl/parameter_invalid.json

@@ -153,5 +153,18 @@
         "type": "array"
       }
     }
+  },
+  "0014_Query_With_Unsupported_Schema_DeepObject": {
+    "path": "/pets/{petId}",
+    "parameterModel": {
+      "name": "petId",
+      "in": "query",
+      "required": true,
+      "explode": true,
+      "style": "deepObject",
+      "schema": {
+        "type": "array"
+      }
+    }
   }
 }