From b74bc79c02d277e67a18bd931edbc36209b52eca Mon Sep 17 00:00:00 2001
From: Alan Richardson <alan@compendiumdev.co.uk>
Date: Sun, 26 Jul 2026 11:10:24 +0100
Subject: [PATCH 1/4] Add QUERY support and versioned OpenAPI specs

---
 .../core/query/QueryFilterParams.java         |  10 +
 pom.xml                                       |   2 +-
 .../swaggerizer/SwaggerizerTest.java          |  27 +-
 .../crudui/ApiDocumentationPage.java          |   2 +
 .../thingifier/crudui/CrudUiController.java   |   6 +
 .../crudui/OpenApiDocumentation.java          |  10 +-
 .../thingifier/crudui/SwaggerUiPage.java      |   7 +-
 .../adapter/javalin/CrudUiApplication.java    |  13 +
 .../crudui/CrudUiControllerTest.java          |  27 ++
 .../thingifier/crudui/e2e/CrudUiApiIT.java    |   5 +
 .../adapter/httpserver/HttpRouteVerb.java     |   1 +
 .../adapter/httpserver/ServerRoutes.java      |   4 +
 .../httpserver/SimpleHttpRouteCreator.java    |   7 +-
 .../ThingifierAutoDocGenRouting.java          |  31 ++-
 .../httpserver/ThingifierHttpApiRoutings.java |  47 +++-
 .../internalhttp/InternalHttpMethod.java      |   1 +
 .../conversion/ThingifierHttpApiBridge.java   |   4 +
 .../adapter/javalin/JavalinHttpServer.java    |   2 +
 .../api/ThingifierRestAPIHandler.java         |   8 +
 .../ApiRoutingDefinitionDocGenerator.java     |  51 +++-
 .../thingifier/api/docgen/RoutingVerb.java    |   1 +
 .../api/http/ApiRequestEnvelope.java          |  17 +-
 .../thingifier/api/http/HttpApiRequest.java   |   1 +
 .../api/http/HttpApiRequestValidator.java     |  40 +++
 .../api/http/ThingifierHttpApi.java           |  10 +
 .../api/http/UrlQueryParamParser.java         |  33 ++-
 .../headerparser/ContentTypeHeaderParser.java |   4 +
 .../restapihandlers/RestApiGetHandler.java    |  15 +-
 .../restapihandlers/RestApiQueryHandler.java  |  67 +++++
 .../RestApiDocumentationGenerator.java        |  12 +
 .../OpenApiSpecificationVersion.java          |  40 +++
 .../swaggerizer/SwaggerGenerationConfig.java  |   2 +
 .../thingifier/swaggerizer/SwaggerUiPage.java |  27 +-
 .../thingifier/swaggerizer/Swaggerizer.java   |  61 ++++-
 .../javalin/JavalinHttpServerTest.java        |  33 +++
 .../ApiRoutingDefinitionDocGeneratorTest.java |  23 ++
 .../api/http/ApiRequestEnvelopeTest.java      |  17 ++
 .../RestApiQueryHandlerTest.java              | 247 ++++++++++++++++++
 .../swaggerizer/SwaggerUiPageTest.java        |   5 +
 39 files changed, 874 insertions(+), 46 deletions(-)
 create mode 100644 thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiQueryHandler.java
 create mode 100644 thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApiSpecificationVersion.java
 create mode 100644 thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiQueryHandlerTest.java

diff --git a/ercoremodel/src/main/java/uk/co/compendiumdev/thingifier/core/query/QueryFilterParams.java b/ercoremodel/src/main/java/uk/co/compendiumdev/thingifier/core/query/QueryFilterParams.java
index 95480fd7..bef3ecfb 100644
--- a/ercoremodel/src/main/java/uk/co/compendiumdev/thingifier/core/query/QueryFilterParams.java
+++ b/ercoremodel/src/main/java/uk/co/compendiumdev/thingifier/core/query/QueryFilterParams.java
@@ -39,6 +39,16 @@ public void add(FilterBy aFilterBy) {
         filterBys.add(aFilterBy);
     }
 
+    public void addAll(final QueryFilterParams params) {
+        if (params == null) {
+            return;
+        }
+
+        for (FilterBy filterBy : params.toList()) {
+            add(new FilterBy(filterBy.fieldName, filterBy.filterOperation + filterBy.fieldValue));
+        }
+    }
+
     public FilterBy get(int i) {
         return filterBys.get(i);
     }
diff --git a/pom.xml b/pom.xml
index d9c97fca..606a48cc 100644
--- a/pom.xml
+++ b/pom.xml
@@ -14,7 +14,7 @@
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 
         <thingifier.version>1.5.6-SNAPSHOT</thingifier.version>
-        <swagger-models-version>2.2.27</swagger-models-version>
+        <swagger-models-version>2.2.52</swagger-models-version>
         <gson-version>2.8.6</gson-version>
         <sqlite-jdbc-version>3.53.2.0</sqlite-jdbc-version>
         <snakeyaml-version>2.6</snakeyaml-version>
diff --git a/swaggerizer/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerizerTest.java b/swaggerizer/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerizerTest.java
index 47e8fee1..7cf0d704 100644
--- a/swaggerizer/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerizerTest.java
+++ b/swaggerizer/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerizerTest.java
@@ -1,5 +1,7 @@
 package uk.co.compendiumdev.thingifier.swaggerizer;
 
+import com.google.gson.JsonParser;
+import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 import uk.co.compendiumdev.thingifier.Thingifier;
 import uk.co.compendiumdev.thingifier.api.docgen.RoutingDefinition;
@@ -26,6 +28,29 @@ public void canCreateSwagger() {
         apiDefn.addServer("http://localhost:4567", "local execution");
         apiDefn.setVersion("1.0.1");
 
-        System.out.println(new Swaggerizer(apiDefn).asJson());
+        String swagger = new Swaggerizer(apiDefn).asJson();
+
+        Assertions.assertTrue(openApiVersion(swagger).startsWith("3.1."));
+        Assertions.assertTrue(swagger.contains("\"x-query-operation\""));
+        Assertions.assertTrue(swagger.contains("application/x-www-form-urlencoded"));
+    }
+
+    @Test
+    public void canCreateOpenApi30Swagger() {
+        Thingifier t = new TodoListThingifierTestModel().get();
+
+        ThingifierApiDocumentationDefn apiDefn = new ThingifierApiDocumentationDefn();
+        apiDefn.setThingifier(t);
+        apiDefn.setVersion("1.0.1");
+
+        String swagger = new Swaggerizer(apiDefn).asJson(OpenApiSpecificationVersion.OPENAPI_3_0);
+
+        Assertions.assertTrue(openApiVersion(swagger).startsWith("3.0."));
+        Assertions.assertTrue(swagger.contains("\"x-query-operation\""));
+        Assertions.assertTrue(swagger.contains("application/x-www-form-urlencoded"));
+    }
+
+    private String openApiVersion(final String swagger) {
+        return JsonParser.parseString(swagger).getAsJsonObject().get("openapi").getAsString();
     }
 }
diff --git a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/ApiDocumentationPage.java b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/ApiDocumentationPage.java
index c6b15375..3e3be68b 100644
--- a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/ApiDocumentationPage.java
+++ b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/ApiDocumentationPage.java
@@ -52,6 +52,8 @@ private void appendHeader(final StringBuilder html) {
         html.append("    <a href=\"/swagger\">Swagger UI</a>\n");
         html.append("    <a href=\"/docs/swagger\">Download OpenAPI</a>\n");
         html.append("    <a href=\"/openapi.json\">Raw OpenAPI JSON</a>\n");
+        html.append("    <a href=\"/openapi-3.1.json\">OpenAPI 3.1 JSON</a>\n");
+        html.append("    <a href=\"/openapi-3.0.json\">OpenAPI 3.0 JSON</a>\n");
         html.append("  </nav>\n");
         html.append("  <h1>").append(escape(title())).append(" API Documentation</h1>\n");
         if (!description().isEmpty()) {
diff --git a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/CrudUiController.java b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/CrudUiController.java
index 1191a8a7..58dd7c95 100644
--- a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/CrudUiController.java
+++ b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/CrudUiController.java
@@ -2,6 +2,7 @@
 
 import java.util.LinkedHashMap;
 import java.util.Map;
+import uk.co.compendiumdev.thingifier.swaggerizer.OpenApiSpecificationVersion;
 import uk.co.compendiumdev.thingifier.yaml.ThingifierYamlException;
 
 public final class CrudUiController {
@@ -188,6 +189,11 @@ public UiHttpResponse openApiJson() {
                 200, new OpenApiDocumentation(workspace.snapshot()).openApiJson());
     }
 
+    public UiHttpResponse openApiJson(final OpenApiSpecificationVersion version) {
+        return UiHttpResponse.json(
+                200, new OpenApiDocumentation(workspace.snapshot()).openApiJson(version));
+    }
+
     public UiHttpResponse downloadOpenApi(final boolean permissive) {
         OpenApiDocumentation openApi = new OpenApiDocumentation(workspace.snapshot());
         Map<String, String> headers = new LinkedHashMap<>();
diff --git a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/OpenApiDocumentation.java b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/OpenApiDocumentation.java
index 145705a3..1140b6c2 100644
--- a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/OpenApiDocumentation.java
+++ b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/OpenApiDocumentation.java
@@ -2,6 +2,7 @@
 
 import java.util.Locale;
 import uk.co.compendiumdev.thingifier.api.docgen.ThingifierApiDocumentationDefn;
+import uk.co.compendiumdev.thingifier.swaggerizer.OpenApiSpecificationVersion;
 import uk.co.compendiumdev.thingifier.swaggerizer.Swaggerizer;
 
 public final class OpenApiDocumentation {
@@ -15,11 +16,16 @@ public OpenApiDocumentation(final WorkspaceSnapshot snapshot) {
     }
 
     public String openApiJson() {
-        return new Swaggerizer(apiDefinition()).asJson();
+        return openApiJson(OpenApiSpecificationVersion.OPENAPI_3_1);
+    }
+
+    public String openApiJson(final OpenApiSpecificationVersion version) {
+        return new Swaggerizer(apiDefinition()).asJson(version);
     }
 
     public String permissiveOpenApiJson() {
-        return new Swaggerizer(apiDefinition()).asJson(true);
+        return new Swaggerizer(apiDefinition())
+                .asJson(OpenApiSpecificationVersion.OPENAPI_3_1, true);
     }
 
     public String downloadFilename(final boolean permissive) {
diff --git a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/SwaggerUiPage.java b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/SwaggerUiPage.java
index 0b3f3b50..34c92da6 100644
--- a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/SwaggerUiPage.java
+++ b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/SwaggerUiPage.java
@@ -33,7 +33,12 @@ public String html() {
                 + "<script>\n"
                 + "window.onload = function () {\n"
                 + "  window.ui = SwaggerUIBundle({\n"
-                + "    url: \"/openapi.json\",\n"
+                + "    urls: [\n"
+                + "      { url: \"/openapi.json\", name: \"OpenAPI 3.1 default\" },\n"
+                + "      { url: \"/openapi-3.1.json\", name: \"OpenAPI 3.1\" },\n"
+                + "      { url: \"/openapi-3.0.json\", name: \"OpenAPI 3.0\" }\n"
+                + "    ],\n"
+                + "    \"urls.primaryName\": \"OpenAPI 3.1 default\",\n"
                 + "    dom_id: \"#swagger-ui\",\n"
                 + "    deepLinking: true,\n"
                 + "    presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],\n"
diff --git a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/adapter/javalin/CrudUiApplication.java b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/adapter/javalin/CrudUiApplication.java
index 2a94b404..d534283e 100644
--- a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/adapter/javalin/CrudUiApplication.java
+++ b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/adapter/javalin/CrudUiApplication.java
@@ -13,6 +13,7 @@
 import uk.co.compendiumdev.thingifier.crudui.DynamicThingifierApiProxy;
 import uk.co.compendiumdev.thingifier.crudui.ResourceReader;
 import uk.co.compendiumdev.thingifier.crudui.UiHttpResponse;
+import uk.co.compendiumdev.thingifier.swaggerizer.OpenApiSpecificationVersion;
 
 public final class CrudUiApplication implements AutoCloseable {
 
@@ -100,6 +101,18 @@ public void configureRoutes() {
                                         request.queryParam("permissive") != null)));
         ServerRoutes.get(
                 "/openapi.json", (request, response) -> write(response, controller.openApiJson()));
+        ServerRoutes.get(
+                "/openapi-3.1.json",
+                (request, response) ->
+                        write(
+                                response,
+                                controller.openApiJson(OpenApiSpecificationVersion.OPENAPI_3_1)));
+        ServerRoutes.get(
+                "/openapi-3.0.json",
+                (request, response) ->
+                        write(
+                                response,
+                                controller.openApiJson(OpenApiSpecificationVersion.OPENAPI_3_0)));
         ServerRoutes.get(
                 "/swagger", (request, response) -> write(response, controller.swaggerUi()));
 
diff --git a/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/CrudUiControllerTest.java b/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/CrudUiControllerTest.java
index b8f4e160..dc6a5250 100644
--- a/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/CrudUiControllerTest.java
+++ b/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/CrudUiControllerTest.java
@@ -7,6 +7,7 @@
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
+import uk.co.compendiumdev.thingifier.swaggerizer.OpenApiSpecificationVersion;
 
 public class CrudUiControllerTest {
 
@@ -296,12 +297,31 @@ public void openApiJsonUsesActiveWorkspaceApiServer() {
             Assertions.assertEquals(200, response.statusCode());
             Assertions.assertEquals("application/json", response.contentType());
             Assertions.assertTrue(response.body().contains("\"openapi\""));
+            Assertions.assertTrue(openApiVersion(response.body()).startsWith("3.1."));
             Assertions.assertTrue(response.body().contains("\"/api\""));
             Assertions.assertTrue(response.body().contains("\"/projects\""));
             Assertions.assertTrue(response.body().contains("\"/projects/{id}/tasks\""));
         }
     }
 
+    @Test
+    public void openApiJsonCanBeGeneratedForOpenApi30() {
+        try (ActiveThingifierWorkspace workspace =
+                ActiveThingifierWorkspace.defaultTodoManagerWorkspace()) {
+            workspace.replaceWithYaml(TestResources.text("/models/project-tasks.yaml"));
+            CrudUiController controller = new CrudUiController(workspace);
+
+            UiHttpResponse response =
+                    controller.openApiJson(OpenApiSpecificationVersion.OPENAPI_3_0);
+
+            Assertions.assertEquals(200, response.statusCode());
+            Assertions.assertEquals("application/json", response.contentType());
+            Assertions.assertTrue(openApiVersion(response.body()).startsWith("3.0."));
+            Assertions.assertTrue(response.body().contains("\"/api\""));
+            Assertions.assertTrue(response.body().contains("\"/projects/{id}/tasks\""));
+        }
+    }
+
     @Test
     public void openApiDownloadAddsAttachmentHeader() {
         try (ActiveThingifierWorkspace workspace =
@@ -356,10 +376,13 @@ public void swaggerUiPageEmbedsUnpkgSwaggerUiForCurrentOpenApiJson() {
             Assertions.assertTrue(response.body().contains("href=\"/favicon.svg\""));
             Assertions.assertTrue(response.body().contains("SwaggerUIBundle"));
             Assertions.assertTrue(response.body().contains("/openapi.json"));
+            Assertions.assertTrue(response.body().contains("/openapi-3.1.json"));
+            Assertions.assertTrue(response.body().contains("/openapi-3.0.json"));
             Assertions.assertTrue(response.body().contains("/css/swagger-copy-for-ai.css"));
             Assertions.assertTrue(response.body().contains("/js/swagger-copy-for-ai.js"));
             Assertions.assertTrue(response.body().contains("window.thingifierSwaggerCopyForAi"));
             Assertions.assertTrue(response.body().contains("openApiUrl: \"/openapi.json\""));
+            Assertions.assertTrue(response.body().contains("\"urls.primaryName\""));
         }
     }
 
@@ -484,4 +507,8 @@ public void faviconResourceIsAvailableAndSimple() {
         Assertions.assertTrue(favicon.contains("#f1c84c"));
         Assertions.assertFalse(favicon.contains("<text"));
     }
+
+    private String openApiVersion(final String openApiJson) {
+        return JsonParser.parseString(openApiJson).getAsJsonObject().get("openapi").getAsString();
+    }
 }
diff --git a/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/e2e/CrudUiApiIT.java b/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/e2e/CrudUiApiIT.java
index 53899a8f..aec5d259 100644
--- a/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/e2e/CrudUiApiIT.java
+++ b/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/e2e/CrudUiApiIT.java
@@ -37,7 +37,12 @@ public void staticPagesAndGeneratedDocumentationAreReachable() {
         assertStatusContains("/swagger", 200, "SwaggerUIBundle");
         assertStatusContains("/swagger", 200, "swagger-copy-for-ai.js");
         assertStatusContains("/openapi.json", 200, "\"openapi\"");
+        assertStatusContains("/openapi-3.1.json", 200, "\"openapi\"");
+        assertStatusContains("/openapi-3.0.json", 200, "\"openapi\"");
         assertStatusContains("/docs/swagger", 200, "\"openapi\"");
+
+        CrudUiApiClient.ApiResult removedAlias = api.get("/openapi-3-1.json");
+        Assertions.assertEquals(404, removedAlias.statusCode(), removedAlias.body());
     }
 
     @Test
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/HttpRouteVerb.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/HttpRouteVerb.java
index 26f0d9e9..0c6c78f5 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/HttpRouteVerb.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/HttpRouteVerb.java
@@ -3,6 +3,7 @@
 public enum HttpRouteVerb {
     GET,
     HEAD,
+    QUERY,
     OPTIONS,
     POST,
     PUT,
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ServerRoutes.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ServerRoutes.java
index 8c10b282..8da6e43d 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ServerRoutes.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ServerRoutes.java
@@ -13,6 +13,10 @@ public static void head(final String path, final HttpRouteHandler handler) {
         route(HttpRouteVerb.HEAD, path, handler);
     }
 
+    public static void query(final String path, final HttpRouteHandler handler) {
+        route(HttpRouteVerb.QUERY, path, handler);
+    }
+
     public static void options(final String path, final HttpRouteHandler handler) {
         route(HttpRouteVerb.OPTIONS, path, handler);
     }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/SimpleHttpRouteCreator.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/SimpleHttpRouteCreator.java
index 606a3afb..56a2febe 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/SimpleHttpRouteCreator.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/SimpleHttpRouteCreator.java
@@ -88,6 +88,9 @@ public static void addHandler(
             case "head":
                 head(endpoint, route);
                 break;
+            case "query":
+                query(endpoint, route);
+                break;
             case "options":
                 options(endpoint, route);
                 break;
@@ -121,7 +124,9 @@ public static void addHandler(
     public static void routeStatusWhenNot(
             final int statuscode, final String endpoint, final List<String> excludedVerbs) {
 
-        String[] verbs = {"get", "options", "head", "put", "post", "patch", "trace", "delete"};
+        String[] verbs = {
+            "get", "options", "head", "query", "put", "post", "patch", "trace", "delete"
+        };
 
         for (String verb : verbs) {
             if (!excludedVerbs.contains(verb)) {
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
index 27b8d810..96ca950f 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
@@ -8,6 +8,7 @@
 import uk.co.compendiumdev.thingifier.api.docgen.ThingifierApiDocumentationDefn;
 import uk.co.compendiumdev.thingifier.htmlgui.htmlgen.DefaultGUIHTML;
 import uk.co.compendiumdev.thingifier.htmlgui.htmlgen.RestApiDocumentationGenerator;
+import uk.co.compendiumdev.thingifier.swaggerizer.OpenApiSpecificationVersion;
 import uk.co.compendiumdev.thingifier.swaggerizer.SwaggerUiPage;
 import uk.co.compendiumdev.thingifier.swaggerizer.Swaggerizer;
 
@@ -25,6 +26,8 @@ public ThingifierAutoDocGenRouting(
         final String docsPath = "%s/docs".formatted(pathPrefix);
         final String swaggerDownloadPath = "%s/docs/swagger".formatted(pathPrefix);
         final String openApiPath = "%s/docs/openapi.json".formatted(pathPrefix);
+        final String openApi30Path = "%s/docs/openapi-3.0.json".formatted(pathPrefix);
+        final String openApi31Path = "%s/docs/openapi-3.1.json".formatted(pathPrefix);
         final String swaggerUiPath = "%s/docs/swagger-ui".formatted(pathPrefix);
 
         // TODO: config to enable docs and configure the URL and add a meta tag for description and
@@ -46,14 +49,9 @@ public ThingifierAutoDocGenRouting(
 
         // guiManagement.appendMenuItem("API documentation","/docs");
 
-        get(
-                openApiPath,
-                (request, response) -> {
-                    response.type("application/json");
-                    response.status(200);
-                    return new Swaggerizer(apiDefn)
-                            .asJsonWithPreferredServer(HttpRequestOrigin.from(request));
-                });
+        registerOpenApiEndpoint(apiDefn, openApiPath, OpenApiSpecificationVersion.OPENAPI_3_1);
+        registerOpenApiEndpoint(apiDefn, openApi31Path, OpenApiSpecificationVersion.OPENAPI_3_1);
+        registerOpenApiEndpoint(apiDefn, openApi30Path, OpenApiSpecificationVersion.OPENAPI_3_0);
 
         get(
                 swaggerUiPath,
@@ -64,6 +62,8 @@ public ThingifierAutoDocGenRouting(
                                     apiDefn,
                                     guiManagement,
                                     openApiPath,
+                                    openApi30Path,
+                                    openApi31Path,
                                     docsPath,
                                     swaggerDownloadPath,
                                     swaggerUiPath)
@@ -103,4 +103,19 @@ public ThingifierAutoDocGenRouting(
                                     permissive != null, HttpRequestOrigin.from(request));
                 });
     }
+
+    private void registerOpenApiEndpoint(
+            final ThingifierApiDocumentationDefn apiDefn,
+            final String path,
+            final OpenApiSpecificationVersion version) {
+        get(
+                path,
+                (request, response) -> {
+                    response.type("application/json");
+                    response.status(200);
+                    return new Swaggerizer(apiDefn)
+                            .asJsonWithPreferredServer(
+                                    version, false, HttpRequestOrigin.from(request));
+                });
+    }
 }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierHttpApiRoutings.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierHttpApiRoutings.java
index 202e1206..9d4942f3 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierHttpApiRoutings.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierHttpApiRoutings.java
@@ -20,6 +20,7 @@
 import uk.co.compendiumdev.thingifier.api.docgen.ApiRoutingDefinitionDocGenerator;
 import uk.co.compendiumdev.thingifier.api.docgen.RoutingDefinition;
 import uk.co.compendiumdev.thingifier.api.docgen.ThingifierApiDocumentationDefn;
+import uk.co.compendiumdev.thingifier.api.http.ThingifierHttpApi;
 
 public class ThingifierHttpApiRoutings {
 
@@ -166,6 +167,27 @@ public ThingifierHttpApiRoutings(
                                 });
                     }
                     break;
+                case QUERY:
+                    if (!defn.status().isReturnedFromCall()) {
+                        query(
+                                defn.url(),
+                                (request, response) -> {
+                                    applyStaticResponse(defn, response);
+                                    return "";
+                                });
+                    } else {
+                        query(
+                                defn.url(),
+                                (request, response) -> {
+                                    final InternalHttpRequest theRequest =
+                                            internalRequestFrom(request);
+                                    final InternalHttpResponse theResponse =
+                                            apiBridge.queryRequest(theRequest);
+                                    return InternalHttpResponseToHttpServer.convert(
+                                            theResponse, response);
+                                });
+                    }
+                    break;
                 default:
                     break;
                 case HEAD:
@@ -188,7 +210,7 @@ public ThingifierHttpApiRoutings(
                         delete(
                                 defn.url(),
                                 (request, response) -> {
-                                    response.status(defn.status().value());
+                                    applyStaticResponse(defn, response);
                                     return "";
                                 });
                     } else {
@@ -210,7 +232,7 @@ public ThingifierHttpApiRoutings(
                         patch(
                                 defn.url(),
                                 (request, response) -> {
-                                    response.status(defn.status().value());
+                                    applyStaticResponse(defn, response);
                                     return "";
                                 });
                     }
@@ -220,7 +242,7 @@ public ThingifierHttpApiRoutings(
                         put(
                                 defn.url(),
                                 (request, response) -> {
-                                    response.status(defn.status().value());
+                                    applyStaticResponse(defn, response);
                                     return "";
                                 });
                     } else {
@@ -242,8 +264,7 @@ public ThingifierHttpApiRoutings(
                         options(
                                 defn.url(),
                                 (request, response) -> {
-                                    response.status(defn.status().value());
-                                    response.header(defn.header(), defn.headerValue());
+                                    applyStaticResponse(defn, response);
                                     return "";
                                 });
                     }
@@ -253,7 +274,7 @@ public ThingifierHttpApiRoutings(
                         trace(
                                 defn.url(),
                                 (request, response) -> {
-                                    response.status(defn.status().value());
+                                    applyStaticResponse(defn, response);
                                     return "";
                                 });
                     }
@@ -291,7 +312,7 @@ public ThingifierHttpApiRoutings(
                     404,
                     apiDefn.getPathPrefix() + "/*",
                     true,
-                    List.of("head", "get", "options", "put", "post", "patch", "delete"));
+                    List.of("head", "get", "query", "options", "put", "post", "patch", "delete"));
         }
     }
 
@@ -345,4 +366,16 @@ private InternalHttpRequest internalRequestFrom(final HttpServerRequest request)
         request.attribute(INTERNAL_HTTP_REQUEST_ATTRIBUTE, internalRequest);
         return internalRequest;
     }
+
+    private void applyStaticResponse(
+            final RoutingDefinition defn, final HttpServerResponse response) {
+        response.status(defn.status().value());
+        if (!defn.header().isEmpty()) {
+            response.header(defn.header(), defn.headerValue());
+        }
+        if (defn.headerValue().contains("QUERY")) {
+            response.header(
+                    ThingifierHttpApi.ACCEPT_QUERY_HEADER, ThingifierHttpApi.QUERY_CONTENT_TYPE);
+        }
+    }
 }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/internalhttp/InternalHttpMethod.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/internalhttp/InternalHttpMethod.java
index c0fa10dc..c40faf83 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/internalhttp/InternalHttpMethod.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/internalhttp/InternalHttpMethod.java
@@ -5,6 +5,7 @@
 public enum InternalHttpMethod {
     GET,
     HEAD,
+    QUERY,
     POST,
     PUT,
     DELETE,
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/internalhttp/conversion/ThingifierHttpApiBridge.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/internalhttp/conversion/ThingifierHttpApiBridge.java
index 695cd7aa..52416456 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/internalhttp/conversion/ThingifierHttpApiBridge.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/internalhttp/conversion/ThingifierHttpApiBridge.java
@@ -50,6 +50,10 @@ public InternalHttpResponse put(final InternalHttpRequest theRequest) {
         return toInternalResponse(thingifierHttpApi.put(toHttpApiRequest(theRequest)));
     }
 
+    public InternalHttpResponse queryRequest(final InternalHttpRequest theRequest) {
+        return toInternalResponse(thingifierHttpApi.queryRequest(toHttpApiRequest(theRequest)));
+    }
+
     public InternalHttpResponse query(final InternalHttpRequest theRequest, final String query) {
         return toInternalResponse(thingifierHttpApi.query(toHttpApiRequest(theRequest), query));
     }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServer.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServer.java
index fea6cad0..64fa15a9 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServer.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServer.java
@@ -350,6 +350,8 @@ private HandlerType handlerType(final HttpRouteVerb verb) {
                 return HandlerType.GET;
             case HEAD:
                 return HandlerType.HEAD;
+            case QUERY:
+                return HandlerType.QUERY;
             case OPTIONS:
                 return HandlerType.OPTIONS;
             case POST:
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/ThingifierRestAPIHandler.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/ThingifierRestAPIHandler.java
index 97c2502d..d59a3c44 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/ThingifierRestAPIHandler.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/ThingifierRestAPIHandler.java
@@ -18,6 +18,7 @@ public class ThingifierRestAPIHandler {
     private final RestApiPostHandler post;
     private final RestApiPutHandler put;
     private final RestApiGetHandler get;
+    private final RestApiQueryHandler query;
 
     public ThingifierRestAPIHandler(final Thingifier aThingifier) {
         this(new DefaultThingifierApiRuntime(aThingifier));
@@ -29,6 +30,7 @@ public ThingifierRestAPIHandler(final ThingifierApiRuntime runtime) {
         this.delete = new RestApiDeleteHandler(runtime);
         this.post = new RestApiPostHandler(runtime);
         this.put = new RestApiPutHandler(runtime);
+        this.query = new RestApiQueryHandler(runtime);
     }
 
     // TODO: we should be able to accept xml with correct content type
@@ -69,6 +71,12 @@ public ApiResponse head(final ApiRequestEnvelope request) {
         return withRepository(response, context);
     }
 
+    public ApiResponse query(final ApiRequestEnvelope request) {
+        ThingifierRequestContext context = contextFrom(request.headers());
+        return withRepository(
+                query.handle(request.path(), request.queryParams(), context), context);
+    }
+
     public ApiResponse delete(final String url, HttpHeadersBlock headers) {
         ThingifierRequestContext context = contextFrom(headers);
         return withRepository(delete.handle(url, context), context);
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGenerator.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGenerator.java
index 43d8418a..ce122ab7 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGenerator.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGenerator.java
@@ -109,6 +109,23 @@ public ApiRoutingDefinition generate(String apiPathPrefix) {
                     .setAsFilterableFrom(entityDefn)
                     .returnPayload(200, entityDefn.getPlural());
 
+            defn.addRouting(
+                            String.format(
+                                    "query all the instances of %s using application/x-www-form-urlencoded query content",
+                                    entityDefn.getName()),
+                            RoutingVerb.QUERY,
+                            pluralUrl,
+                            RoutingStatus.returnedFromCall())
+                    .addPossibleStatus(
+                            RoutingStatus.returnValue(
+                                    200,
+                                    String.format("All the matching %s", entityDefn.getPlural())))
+                    .addPossibleStatus(RoutingStatus.returnValue(400))
+                    .addPossibleStatus(RoutingStatus.returnValue(413))
+                    .addPossibleStatus(RoutingStatus.returnValue(415))
+                    .setAsFilterableFrom(entityDefn)
+                    .returnPayload(200, entityDefn.getPlural());
+
             defn.addRouting(
                             String.format(
                                     "headers for all the instances of %s", entityDefn.getName()),
@@ -164,7 +181,7 @@ public ApiRoutingDefinition generate(String apiPathPrefix) {
                     RoutingVerb.OPTIONS,
                     pluralUrl,
                     RoutingStatus.returnValue(204, "the endpoint verb options"),
-                    new ResponseHeader("Allow", "OPTIONS, GET, HEAD, POST"));
+                    new ResponseHeader("Allow", "OPTIONS, GET, HEAD, POST, QUERY"));
 
             // the following are not handled so return 405
             defn.addRouting(
@@ -228,6 +245,14 @@ public ApiRoutingDefinition generate(String apiPathPrefix) {
                                             "Could not find a specific %s", entityDefn.getName())));
             ;
 
+            defn.addRouting(
+                            "method not allowed",
+                            RoutingVerb.QUERY,
+                            aUrlWGuid,
+                            RoutingStatus.returnValue(405),
+                            new ResponseHeader("Allow", "OPTIONS, GET, HEAD, POST, PUT, DELETE"))
+                    .addRequestUrlParam(entityDefn.getField(uniqueIdFieldName));
+
             // we should be able to amend things with a GUID e.g. POST project/GUID with body
             defn.addRouting(
                             String.format(
@@ -414,6 +439,22 @@ private void addRoutingsForRelationship(
                         RoutingStatus.returnValue(
                                 200, String.format("all the related the %s items", toName)));
 
+        defn.addRouting(
+                        String.format(
+                                "query all the %s items related to %s, with given %s, by the relationship named %s using application/x-www-form-urlencoded query content",
+                                toName, fromName, uniqueIdFieldName, relationshipName),
+                        RoutingVerb.QUERY,
+                        aUrl,
+                        RoutingStatus.returnedFromCall())
+                .addPossibleStatus(
+                        RoutingStatus.returnValue(
+                                200, String.format("all the matching related %s items", toName)))
+                .addPossibleStatus(RoutingStatus.returnValue(400))
+                .addPossibleStatus(RoutingStatus.returnValue(413))
+                .addPossibleStatus(RoutingStatus.returnValue(415))
+                .setAsFilterableFrom(relationship.getTo())
+                .returnPayload(200, relationship.getTo().getPlural());
+
         defn.addRouting(
                         String.format(
                                 "headers for the %s items related to %s, with given %s, by the relationship named %s",
@@ -431,7 +472,7 @@ private void addRoutingsForRelationship(
                 RoutingVerb.OPTIONS,
                 aUrl,
                 RoutingStatus.returnValue(200),
-                new ResponseHeader("Allow", "OPTIONS, GET, HEAD, POST"));
+                new ResponseHeader("Allow", "OPTIONS, GET, HEAD, POST, QUERY"));
 
         // we can post if there is no guid as it will create the 'thing' and the relationship
         // connection
@@ -511,6 +552,12 @@ private void addRoutingsForRelationship(
                 "method not allowed", RoutingVerb.HEAD, aUrlDelete, RoutingStatus.returnValue(405));
         defn.addRouting(
                 "method not allowed", RoutingVerb.GET, aUrlDelete, RoutingStatus.returnValue(405));
+        defn.addRouting(
+                "method not allowed",
+                RoutingVerb.QUERY,
+                aUrlDelete,
+                RoutingStatus.returnValue(405),
+                new ResponseHeader("Allow", "OPTIONS, DELETE"));
         defn.addRouting(
                 "method not allowed",
                 RoutingVerb.PATCH,
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/RoutingVerb.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/RoutingVerb.java
index 282a9b61..a8494423 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/RoutingVerb.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/RoutingVerb.java
@@ -3,6 +3,7 @@
 public enum RoutingVerb {
     GET,
     HEAD,
+    QUERY,
     DELETE,
     PATCH,
     PUT,
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/ApiRequestEnvelope.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/ApiRequestEnvelope.java
index dfc382ea..a94b6c1d 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/ApiRequestEnvelope.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/ApiRequestEnvelope.java
@@ -35,12 +35,19 @@ public static ApiRequestEnvelope from(
         if (verb == ThingifierHttpApi.HttpVerb.POST || verb == ThingifierHttpApi.HttpVerb.PUT) {
             bodyFields = new BodyParser(request, thingNames).bodyFields();
         }
+        QueryFilterParams queryParams = request.getFilterableQueryParams();
+        if (verb == ThingifierHttpApi.HttpVerb.QUERY) {
+            queryParams = queryContentAndUriQueryParams(request);
+        }
         return new ApiRequestEnvelope(
-                verb,
-                request.getPath(),
-                request.getFilterableQueryParams(),
-                request.getHeaders(),
-                bodyFields);
+                verb, request.getPath(), queryParams, request.getHeaders(), bodyFields);
+    }
+
+    private static QueryFilterParams queryContentAndUriQueryParams(final HttpApiRequest request) {
+        QueryFilterParams params = new QueryFilterParams();
+        params.addAll(request.getFilterableQueryParams());
+        params.addAll(new UrlQueryParamParser().parseStrict(request.getBody()));
+        return params;
     }
 
     public ThingifierHttpApi.HttpVerb verb() {
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/HttpApiRequest.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/HttpApiRequest.java
index ea76ff0d..52c128bd 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/HttpApiRequest.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/HttpApiRequest.java
@@ -33,6 +33,7 @@ public void removePrefixFromPath(String prefix) {
     public enum VERB {
         GET,
         HEAD,
+        QUERY,
         POST,
         PUT,
         DELETE,
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/HttpApiRequestValidator.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/HttpApiRequestValidator.java
index 9519b986..8e5748f8 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/HttpApiRequestValidator.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/HttpApiRequestValidator.java
@@ -2,6 +2,7 @@
 
 import java.util.ArrayList;
 import uk.co.compendiumdev.thingifier.api.http.bodyparser.BodyParser;
+import uk.co.compendiumdev.thingifier.api.http.headers.headerparser.ContentTypeHeaderParser;
 import uk.co.compendiumdev.thingifier.api.http.headers.headervalidator.AcceptHeaderValidator;
 import uk.co.compendiumdev.thingifier.api.http.headers.headervalidator.ContentTypeHeaderValidator;
 import uk.co.compendiumdev.thingifier.api.response.ApiResponse;
@@ -41,6 +42,12 @@ public boolean validateSyntax(
             }
         }
 
+        if (apiResponse == null) {
+            if (verb == ThingifierHttpApi.HttpVerb.QUERY) {
+                apiResponse = validateQueryContent(request);
+            }
+        }
+
         if (apiResponse == null) {
             // only validate content if it contains content
             if (verb == ThingifierHttpApi.HttpVerb.POST
@@ -71,6 +78,39 @@ public boolean validateSyntax(
         return this.isValid;
     }
 
+    private ApiResponse validateQueryContent(final HttpApiRequest request) {
+        final ContentTypeHeaderParser contentType =
+                new ContentTypeHeaderParser(request.getContentTypeHeader());
+
+        if (contentType.isMissing()) {
+            return queryContentError(400, "Missing Content-Type for QUERY request");
+        }
+
+        if (!contentType.isFormUrlEncoded()) {
+            ApiResponse response =
+                    queryContentError(
+                            this.apiConfig.statusCodes().contentTypeNotSupported(),
+                            "Unsupported QUERY Content Type - " + request.getContentTypeHeader());
+            response.setHeader("Accept", ThingifierHttpApi.QUERY_CONTENT_TYPE);
+            return response;
+        }
+
+        try {
+            new UrlQueryParamParser().parseStrict(request.getBody());
+        } catch (IllegalArgumentException e) {
+            return queryContentError(400, e.getMessage());
+        }
+
+        return null;
+    }
+
+    private ApiResponse queryContentError(final int statusCode, final String message) {
+        return ApiResponse.error(statusCode, message)
+                .setHeader(
+                        ThingifierHttpApi.ACCEPT_QUERY_HEADER,
+                        ThingifierHttpApi.QUERY_CONTENT_TYPE);
+    }
+
     public ApiResponse getErrorApiResponse() {
         return this.errorResponse;
     }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/ThingifierHttpApi.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/ThingifierHttpApi.java
index 41a5206b..bf89260f 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/ThingifierHttpApi.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/ThingifierHttpApi.java
@@ -14,6 +14,8 @@ public final class ThingifierHttpApi {
     // TODO: each 'session' could have its own thingifier to support multiple users
     // TODO: would need the ability to create and delete sessions
     public static final String HTTP_SESSION_HEADER_NAME = "X-THING-HTTP-SESSION-GUID";
+    public static final String ACCEPT_QUERY_HEADER = "Accept-Query";
+    public static final String QUERY_CONTENT_TYPE = "application/x-www-form-urlencoded";
 
     private final Thingifier thingifier;
     private final JsonThing jsonThing;
@@ -26,6 +28,7 @@ public enum HttpVerb {
         POST,
         PUT,
         HEAD,
+        QUERY,
         // NOT Handled
         OPTIONS,
         PATCH,
@@ -146,6 +149,9 @@ public ApiResponse routeAndProcessRequest(final HttpApiRequest request, HttpVerb
             case HEAD:
                 apiResponse = thingifier.api().get(envelope);
                 break;
+            case QUERY:
+                apiResponse = thingifier.api().query(envelope);
+                break;
             case DELETE:
                 apiResponse = thingifier.api().delete(envelope);
                 break;
@@ -182,6 +188,10 @@ public HttpApiResponse put(final HttpApiRequest request) {
         return handleRequest(request, HttpVerb.PUT);
     }
 
+    public HttpApiResponse queryRequest(final HttpApiRequest request) {
+        return handleRequest(request, HttpVerb.QUERY);
+    }
+
     public HttpApiResponse query(final HttpApiRequest request, final String query) {
 
         HttpApiResponse httpResponse = runTheHttpApiRequestHooksOn(request);
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/UrlQueryParamParser.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/UrlQueryParamParser.java
index 7dd9842c..495674d3 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/UrlQueryParamParser.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/UrlQueryParamParser.java
@@ -1,6 +1,7 @@
 package uk.co.compendiumdev.thingifier.api.http;
 
 import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
 import uk.co.compendiumdev.thingifier.core.query.FilterBy;
 import uk.co.compendiumdev.thingifier.core.query.QueryFilterParams;
 
@@ -19,6 +20,16 @@ public String urlDecode(final String possiblyUrlEncodedString) {
     }
 
     public QueryFilterParams parse(final String rawUrlParams) {
+        try {
+            return parseStrict(rawUrlParams);
+        } catch (IllegalArgumentException e) {
+            // TODO: should really have added a logger by now and avoid System.out
+            System.out.println(e.getMessage());
+            return new QueryFilterParams();
+        }
+    }
+
+    public QueryFilterParams parseStrict(final String rawUrlParams) {
 
         QueryFilterParams filters = new QueryFilterParams();
 
@@ -32,21 +43,29 @@ public QueryFilterParams parse(final String rawUrlParams) {
             return filters;
         }
 
-        String rawDecoded = urlDecode(parseThis);
+        String rawDecoded = urlDecodeStrict(parseThis);
         String[] rawParams = rawDecoded.split("&");
 
         for (String rawParam : rawParams) {
-            try {
-                FilterBy aFilterBy = parseToFilterBy(rawParam);
-                filters.add(aFilterBy);
-            } catch (Exception e) {
-                // TODO: should really have added a logger by now and avoid System.out
-                System.out.println(e.getMessage());
+            String param = rawParam.trim();
+            if (param.isEmpty()) {
+                continue;
             }
+
+            FilterBy aFilterBy = parseToFilterBy(param);
+            if (aFilterBy.fieldName == null || aFilterBy.fieldName.trim().isEmpty()) {
+                throw new IllegalArgumentException(
+                        "Malformed query content: field name is missing");
+            }
+            filters.add(aFilterBy);
         }
         return filters;
     }
 
+    private String urlDecodeStrict(final String possiblyUrlEncodedString) {
+        return URLDecoder.decode(possiblyUrlEncodedString, StandardCharsets.UTF_8);
+    }
+
     private FilterBy parseToFilterBy(final String rawParam) {
         String param = rawParam.trim();
         String fieldName = getFieldNameFrom(param);
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/headers/headerparser/ContentTypeHeaderParser.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/headers/headerparser/ContentTypeHeaderParser.java
index b89939f2..00c59145 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/headers/headerparser/ContentTypeHeaderParser.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/http/headers/headerparser/ContentTypeHeaderParser.java
@@ -20,6 +20,10 @@ public boolean isJSON() {
         return header.contains("application/json");
     }
 
+    public boolean isFormUrlEncoded() {
+        return header.contains("application/x-www-form-urlencoded");
+    }
+
     public boolean isMissing() {
         return (header.isEmpty());
     }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiGetHandler.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiGetHandler.java
index 152ad09b..79d260dd 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiGetHandler.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiGetHandler.java
@@ -7,7 +7,11 @@
 import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.ThingReadRequestMapping;
 import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.ThingReadResultApiMapper;
 import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.ThingifierApiRuntime;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.CollectionRoute;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.RelationshipCollectionRoute;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.ThingRoute;
 import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.ThingRouteMapper;
+import uk.co.compendiumdev.thingifier.api.http.ThingifierHttpApi;
 import uk.co.compendiumdev.thingifier.api.http.ThingifierRequestContext;
 import uk.co.compendiumdev.thingifier.api.http.headers.HttpHeadersBlock;
 import uk.co.compendiumdev.thingifier.api.response.ApiResponse;
@@ -52,15 +56,20 @@ public ApiResponse handle(
         QueryFilterParams effectiveQueryParams =
                 allowFiltering ? queryParams : new QueryFilterParams();
 
+        ThingRoute route = new ThingRouteMapper(runtime.schema()).map(url);
         ThingReadRequestMapping mapping =
-                new ThingReadRequestMapper(runtime.schema())
-                        .map(new ThingRouteMapper(runtime.schema()).map(url), effectiveQueryParams);
+                new ThingReadRequestMapper(runtime.schema()).map(route, effectiveQueryParams);
         if (mapping.isError()) {
             return apiMapper.map(mapping.getError());
         }
 
         queryResults = runtime.queryService().execute(mapping.getQuery(), context.store());
 
-        return apiMapper.map(url, queryResults);
+        ApiResponse response = apiMapper.map(url, queryResults);
+        if (route instanceof CollectionRoute || route instanceof RelationshipCollectionRoute) {
+            response.setHeader(
+                    ThingifierHttpApi.ACCEPT_QUERY_HEADER, ThingifierHttpApi.QUERY_CONTENT_TYPE);
+        }
+        return response;
     }
 }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiQueryHandler.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiQueryHandler.java
new file mode 100644
index 00000000..64388f03
--- /dev/null
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiQueryHandler.java
@@ -0,0 +1,67 @@
+package uk.co.compendiumdev.thingifier.api.restapihandlers;
+
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.ApiMappingError;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.ThingReadRequestMapper;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.ThingReadRequestMapping;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.ThingReadResultApiMapper;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.ThingifierApiRuntime;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.CollectionRoute;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.InstanceRoute;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.RelationshipCollectionRoute;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.RelationshipInstanceRoute;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.ThingRoute;
+import uk.co.compendiumdev.thingifier.adapter.http.apihandlers.route.ThingRouteMapper;
+import uk.co.compendiumdev.thingifier.api.http.ThingifierHttpApi;
+import uk.co.compendiumdev.thingifier.api.http.ThingifierRequestContext;
+import uk.co.compendiumdev.thingifier.api.response.ApiResponse;
+import uk.co.compendiumdev.thingifier.core.query.QueryFilterParams;
+import uk.co.compendiumdev.thingifier.core.query.RepositoryQueryResult;
+
+public final class RestApiQueryHandler {
+
+    private final ThingifierApiRuntime runtime;
+
+    public RestApiQueryHandler(final ThingifierApiRuntime runtime) {
+        this.runtime = runtime;
+    }
+
+    public ApiResponse handle(
+            final String url,
+            final QueryFilterParams queryParams,
+            final ThingifierRequestContext context) {
+        ThingReadResultApiMapper apiMapper = new ThingReadResultApiMapper(runtime.apiConfig());
+        ThingRoute route = new ThingRouteMapper(runtime.schema()).map(url);
+
+        if (route instanceof InstanceRoute) {
+            return methodNotAllowed("OPTIONS, GET, HEAD, POST, PUT, DELETE");
+        }
+
+        if (route instanceof RelationshipInstanceRoute) {
+            return methodNotAllowed("OPTIONS, DELETE");
+        }
+
+        if (!(route instanceof CollectionRoute || route instanceof RelationshipCollectionRoute)) {
+            return apiMapper.map(
+                    ApiMappingError.withMessage(
+                            404, String.format("Could not find an instance with %s", url)));
+        }
+
+        ThingReadRequestMapping mapping =
+                new ThingReadRequestMapper(runtime.schema()).map(route, queryParams);
+        if (mapping.isError()) {
+            return apiMapper.map(mapping.getError());
+        }
+
+        RepositoryQueryResult queryResults =
+                runtime.queryService().execute(mapping.getQuery(), context.store());
+        return apiMapper
+                .map(url, queryResults)
+                .setHeader(
+                        ThingifierHttpApi.ACCEPT_QUERY_HEADER,
+                        ThingifierHttpApi.QUERY_CONTENT_TYPE);
+    }
+
+    private ApiResponse methodNotAllowed(final String allowHeader) {
+        return ApiResponse.error(405, "Method Not Allowed").setHeader("Allow", allowHeader);
+    }
+}
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
index 68101e84..0f3a12bc 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
@@ -12,6 +12,7 @@
 import uk.co.compendiumdev.thingifier.api.docgen.ThingifierApiDocumentationDefn;
 import uk.co.compendiumdev.thingifier.api.ermodelconversion.JsonThing;
 import uk.co.compendiumdev.thingifier.api.ermodelconversion.XmlThing;
+import uk.co.compendiumdev.thingifier.api.http.ThingifierHttpApi;
 import uk.co.compendiumdev.thingifier.api.http.bodyparser.xml.GenericXMLPrettyPrinter;
 import uk.co.compendiumdev.thingifier.apiconfig.ThingifierApiConfig;
 import uk.co.compendiumdev.thingifier.core.domain.definitions.EntityDefinition;
@@ -400,6 +401,13 @@ public String getApiDocumentation(
                                     routingDefn.verb(),
                                     routingDefn.url(),
                                     routingDefn.getDocumentation()));
+                    if (routingDefn.verb() == RoutingVerb.QUERY) {
+                        output.append(
+                                paragraph(
+                                        "QUERY content uses <i>Content-Type: "
+                                                + ThingifierHttpApi.QUERY_CONTENT_TYPE
+                                                + "</i> with fields such as <i>title=Task&amp;sortBy=-id</i>."));
+                    }
                 }
             }
         }
@@ -441,6 +449,10 @@ public String getApiDocumentation(
         if (apiDocDefn.willShowSwaggerUiLink()) {
             output.append(paragraph(href("Open Swagger UI", prependPath + "/docs/swagger-ui")));
         }
+        output.append(
+                paragraph(href("[openapi 3.1 json]", prependPath + "/docs/openapi-3.1.json")));
+        output.append(
+                paragraph(href("[openapi 3.0 json]", prependPath + "/docs/openapi-3.0.json")));
         output.append(
                 paragraph(href("[download normal swagger file]", prependPath + "/docs/swagger")));
         output.append(
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApiSpecificationVersion.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApiSpecificationVersion.java
new file mode 100644
index 00000000..e520f551
--- /dev/null
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApiSpecificationVersion.java
@@ -0,0 +1,40 @@
+package uk.co.compendiumdev.thingifier.swaggerizer;
+
+import io.swagger.v3.oas.models.SpecVersion;
+
+public enum OpenApiSpecificationVersion {
+    OPENAPI_3_0("3.0", "3.0.1", "OpenAPI 3.0", SpecVersion.V30),
+    OPENAPI_3_1("3.1", "3.1.0", "OpenAPI 3.1", SpecVersion.V31);
+
+    private final String versionNumber;
+    private final String documentVersion;
+    private final String displayName;
+    private final SpecVersion specVersion;
+
+    OpenApiSpecificationVersion(
+            final String versionNumber,
+            final String documentVersion,
+            final String displayName,
+            final SpecVersion specVersion) {
+        this.versionNumber = versionNumber;
+        this.documentVersion = documentVersion;
+        this.displayName = displayName;
+        this.specVersion = specVersion;
+    }
+
+    public String versionNumber() {
+        return versionNumber;
+    }
+
+    public String documentVersion() {
+        return documentVersion;
+    }
+
+    public String displayName() {
+        return displayName;
+    }
+
+    public SpecVersion specVersion() {
+        return specVersion;
+    }
+}
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerGenerationConfig.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerGenerationConfig.java
index 77eacbbe..fba3d759 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerGenerationConfig.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerGenerationConfig.java
@@ -5,4 +5,6 @@ public class SwaggerGenerationConfig {
     // include endpoints with only a 405 status code?
     public boolean includeMethodNotAllowedEndpoints = false;
     public boolean includeFieldValidation = true;
+    public OpenApiSpecificationVersion openApiSpecificationVersion =
+            OpenApiSpecificationVersion.OPENAPI_3_1;
 }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java
index e0b174d0..9d3d149a 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java
@@ -17,6 +17,8 @@ public final class SwaggerUiPage {
     private final ThingifierApiDocumentationDefn apiDefn;
     private final DefaultGUIHTML guiManagement;
     private final String openApiUrl;
+    private final String openApi30Url;
+    private final String openApi31Url;
     private final String docsUrl;
     private final String downloadUrl;
     private final String canonicalUrl;
@@ -25,12 +27,16 @@ public SwaggerUiPage(
             final ThingifierApiDocumentationDefn apiDefn,
             final DefaultGUIHTML guiManagement,
             final String openApiUrl,
+            final String openApi30Url,
+            final String openApi31Url,
             final String docsUrl,
             final String downloadUrl,
             final String canonicalUrl) {
         this.apiDefn = apiDefn;
         this.guiManagement = guiManagement;
         this.openApiUrl = openApiUrl;
+        this.openApi30Url = openApi30Url;
+        this.openApi31Url = openApi31Url;
         this.docsUrl = docsUrl;
         this.downloadUrl = downloadUrl;
         this.canonicalUrl = canonicalUrl;
@@ -51,6 +57,14 @@ public String html() {
         html.append("<a href='")
                 .append(escapeHtmlAttribute(downloadUrl))
                 .append("'>Download OpenAPI JSON</a>");
+        html.append(" | ");
+        html.append("<a href='")
+                .append(escapeHtmlAttribute(openApi31Url))
+                .append("'>OpenAPI 3.1 JSON</a>");
+        html.append(" | ");
+        html.append("<a href='")
+                .append(escapeHtmlAttribute(openApi30Url))
+                .append("'>OpenAPI 3.0 JSON</a>");
         html.append("</p>");
         html.append("<div id='swagger-ui'></div>");
         html.append("<script src='")
@@ -63,7 +77,18 @@ public String html() {
         html.append("window.onload = function () {");
         html.append("document.documentElement.classList.remove(\"dark-mode\");");
         html.append("window.ui = SwaggerUIBundle({");
-        html.append("url: \"").append(escapeJavaScriptString(openApiUrl)).append("\",");
+        html.append("urls: [");
+        html.append("{url: \"")
+                .append(escapeJavaScriptString(openApiUrl))
+                .append("\", name: \"OpenAPI 3.1 default\"},");
+        html.append("{url: \"")
+                .append(escapeJavaScriptString(openApi31Url))
+                .append("\", name: \"OpenAPI 3.1\"},");
+        html.append("{url: \"")
+                .append(escapeJavaScriptString(openApi30Url))
+                .append("\", name: \"OpenAPI 3.0\"}");
+        html.append("],");
+        html.append("\"urls.primaryName\": \"OpenAPI 3.1 default\",");
         html.append("dom_id: \"#swagger-ui\",");
         html.append("deepLinking: true,");
         html.append("syntaxHighlight: {activated: false},");
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java
index b2400bd5..27ce6700 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java
@@ -1,5 +1,6 @@
 package uk.co.compendiumdev.thingifier.swaggerizer;
 
+import io.swagger.v3.core.util.Json;
 import io.swagger.v3.core.util.Json31;
 import io.swagger.v3.oas.models.*;
 import io.swagger.v3.oas.models.info.Info;
@@ -20,6 +21,7 @@
 import uk.co.compendiumdev.thingifier.api.docgen.RoutingDefinition;
 import uk.co.compendiumdev.thingifier.api.docgen.RoutingStatus;
 import uk.co.compendiumdev.thingifier.api.docgen.ThingifierApiDocumentationDefn;
+import uk.co.compendiumdev.thingifier.api.http.ThingifierHttpApi;
 import uk.co.compendiumdev.thingifier.core.domain.definitions.EntityDefinition;
 import uk.co.compendiumdev.thingifier.core.domain.definitions.field.definition.Field;
 import uk.co.compendiumdev.thingifier.core.domain.definitions.field.definition.FieldType;
@@ -48,10 +50,15 @@ public Swaggerizer(ThingifierApiDocumentationDefn apiDefn) {
        Swagger file for normal usage
     */
     public OpenAPI swagger() {
+        return swagger(OpenApiSpecificationVersion.OPENAPI_3_1);
+    }
+
+    public OpenAPI swagger(final OpenApiSpecificationVersion version) {
         SwaggerGenerationConfig config = new SwaggerGenerationConfig();
 
         config.includeMethodNotAllowedEndpoints = false;
         config.includeFieldValidation = true;
+        config.openApiSpecificationVersion = version;
 
         return swagger(config);
     }
@@ -60,17 +67,23 @@ public OpenAPI swagger() {
        Swagger file for use in testing
     */
     public OpenAPI swaggerPermissive() {
+        return swaggerPermissive(OpenApiSpecificationVersion.OPENAPI_3_1);
+    }
+
+    public OpenAPI swaggerPermissive(final OpenApiSpecificationVersion version) {
         SwaggerGenerationConfig config = new SwaggerGenerationConfig();
 
         config.includeMethodNotAllowedEndpoints = true;
         config.includeFieldValidation = false;
+        config.openApiSpecificationVersion = version;
 
         return swagger(config);
     }
 
     public OpenAPI swagger(SwaggerGenerationConfig config) {
 
-        OpenAPI api = new OpenAPI();
+        OpenAPI api = new OpenAPI(config.openApiSpecificationVersion.specVersion());
+        api.setOpenapi(config.openApiSpecificationVersion.documentVersion());
 
         final Thingifier thingifier = apiDefn.getThingifier();
 
@@ -361,6 +374,12 @@ private void setOperationVerb(RoutingDefinition subroute, PathItem path, Operati
             case HEAD:
                 path.setHead(operation);
                 break;
+            case QUERY:
+                operation.addExtension("x-http-method", "QUERY");
+                operation.addExtension(
+                        "x-query-content-types", List.of(ThingifierHttpApi.QUERY_CONTENT_TYPE));
+                path.addExtension("x-query-operation", operation);
+                break;
             case PATCH:
                 path.setPatch(operation);
                 break;
@@ -509,21 +528,42 @@ private static String joinStrings(List<String> description, String postfix) {
     // TODO: the output from swaggerizer json could be cached
 
     public String asJson() {
-        return asJson(false);
+        return asJson(OpenApiSpecificationVersion.OPENAPI_3_1, false);
     }
 
     public String asJsonWithPreferredServer(final String preferredServerUrl) {
-        return asJsonWithPreferredServer(false, preferredServerUrl);
+        return asJsonWithPreferredServer(
+                OpenApiSpecificationVersion.OPENAPI_3_1, false, preferredServerUrl);
     }
 
     public String asJsonWithPreferredServer(
             final boolean permissive, final String preferredServerUrl) {
-        final OpenAPI api = permissive ? swaggerPermissive() : swagger();
+        return asJsonWithPreferredServer(
+                OpenApiSpecificationVersion.OPENAPI_3_1, permissive, preferredServerUrl);
+    }
+
+    public String asJsonWithPreferredServer(
+            final OpenApiSpecificationVersion version,
+            final boolean permissive,
+            final String preferredServerUrl) {
+        final OpenAPI api = permissive ? swaggerPermissive(version) : swagger(version);
         preferServer(api, preferredServerUrl);
-        return Json31.pretty(api);
+        return pretty(api, version);
     }
 
     public String asJson(boolean permissive) {
+        return asJson(OpenApiSpecificationVersion.OPENAPI_3_1, permissive);
+    }
+
+    public String asJson(final OpenApiSpecificationVersion version) {
+        return asJson(version, false);
+    }
+
+    public String asJson(final OpenApiSpecificationVersion version, boolean permissive) {
+        if (version != OpenApiSpecificationVersion.OPENAPI_3_1) {
+            return pretty(permissive ? swaggerPermissive(version) : swagger(version), version);
+        }
+
         if (apiNormal == null) {
             apiNormal = swagger();
         }
@@ -531,12 +571,19 @@ public String asJson(boolean permissive) {
             apiPermissive = swaggerPermissive();
         }
         if (permissive) {
-            return Json31.pretty(apiPermissive);
+            return pretty(apiPermissive, version);
         } else {
-            return Json31.pretty(apiNormal);
+            return pretty(apiNormal, version);
         }
     }
 
+    private String pretty(final OpenAPI api, final OpenApiSpecificationVersion version) {
+        if (version == OpenApiSpecificationVersion.OPENAPI_3_0) {
+            return Json.pretty(api);
+        }
+        return Json31.pretty(api);
+    }
+
     private void preferServer(final OpenAPI api, final String preferredServerUrl) {
         if (preferredServerUrl == null || preferredServerUrl.trim().isEmpty()) {
             return;
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServerTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServerTest.java
index 1954a863..3e92b256 100644
--- a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServerTest.java
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/adapter/javalin/JavalinHttpServerTest.java
@@ -75,6 +75,29 @@ void contentTypeCanBeSuppressedForResponseWithBody() throws Exception {
         }
     }
 
+    @Test
+    void queryMethodRoutesThroughJavalinAdapter() throws Exception {
+        int port = availablePort();
+        HttpRouteRegistry registry = new HttpRouteRegistry();
+        registry.add(
+                HttpRouteVerb.QUERY,
+                "/search",
+                (request, response) -> {
+                    response.type("text/plain");
+                    response.status(200);
+                    return request.method() + ":" + request.body();
+                });
+
+        try (JavalinHttpServer server = new JavalinHttpServer(port, "/public", registry)) {
+            server.start();
+
+            String response = rawHttp("QUERY", "/search", port, "title=Task");
+
+            Assertions.assertTrue(response.startsWith("HTTP/1.1 200 OK"));
+            Assertions.assertTrue(response.endsWith("QUERY:title=Task"));
+        }
+    }
+
     @Test
     void forcedBodyCanBeSentWithNoContentStatus() throws Exception {
         int port = availablePort();
@@ -165,8 +188,15 @@ private int availablePort() throws Exception {
 
     private String rawHttp(final String method, final String path, final int port)
             throws Exception {
+        return rawHttp(method, path, port, "");
+    }
+
+    private String rawHttp(
+            final String method, final String path, final int port, final String body)
+            throws Exception {
         try (Socket socket = new Socket("localhost", port)) {
             socket.setSoTimeout(5000);
+            byte[] bodyBytes = body.getBytes(StandardCharsets.ISO_8859_1);
             socket.getOutputStream()
                     .write(
                             (method
@@ -174,8 +204,11 @@ private String rawHttp(final String method, final String path, final int port)
                                             + path
                                             + " HTTP/1.1\r\nHost: localhost:"
                                             + port
+                                            + "\r\nContent-Length: "
+                                            + bodyBytes.length
                                             + "\r\nConnection: close\r\n\r\n")
                                     .getBytes(StandardCharsets.ISO_8859_1));
+            socket.getOutputStream().write(bodyBytes);
             return new String(socket.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
         }
     }
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGeneratorTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGeneratorTest.java
index 41d9bac3..de484605 100644
--- a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGeneratorTest.java
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGeneratorTest.java
@@ -22,6 +22,18 @@ public void entityCollectionPostDocumentsValidationAndConflictStatuses() {
         Assertions.assertTrue(statuses(route).containsAll(Set.of(201, 400, 422, 409)));
     }
 
+    @Test
+    public void entityCollectionQueryDocumentsQueryStatusesAndDiscovery() {
+        ApiRoutingDefinition definition =
+                new ApiRoutingDefinitionDocGenerator(model()).generate("");
+
+        RoutingDefinition query = route(definition, RoutingVerb.QUERY, "todos");
+        RoutingDefinition options = route(definition, RoutingVerb.OPTIONS, "todos");
+
+        Assertions.assertTrue(statuses(query).containsAll(Set.of(200, 400, 413, 415)));
+        Assertions.assertEquals("OPTIONS, GET, HEAD, POST, QUERY", options.headerValue());
+    }
+
     @Test
     public void entityInstanceWritesDocumentValidationAndConflictStatuses() {
         ApiRoutingDefinition definition =
@@ -36,6 +48,8 @@ public void entityInstanceWritesDocumentValidationAndConflictStatuses() {
         Assertions.assertTrue(
                 statuses(route(definition, RoutingVerb.DELETE, "todos/:id"))
                         .containsAll(Set.of(204, 404)));
+        Assertions.assertEquals(
+                405, route(definition, RoutingVerb.QUERY, "todos/:id").status().value());
     }
 
     @Test
@@ -46,9 +60,18 @@ public void relationshipWritesDocumentValidationAndConflictStatuses() {
         Assertions.assertTrue(
                 statuses(route(definition, RoutingVerb.POST, "projects/:id/tasks"))
                         .containsAll(Set.of(201, 400, 404, 422, 409)));
+        Assertions.assertTrue(
+                statuses(route(definition, RoutingVerb.QUERY, "projects/:id/tasks"))
+                        .containsAll(Set.of(200, 400, 413, 415)));
+        Assertions.assertEquals(
+                "OPTIONS, GET, HEAD, POST, QUERY",
+                route(definition, RoutingVerb.OPTIONS, "projects/:id/tasks").headerValue());
         Assertions.assertTrue(
                 statuses(route(definition, RoutingVerb.DELETE, "projects/:id/tasks/:id"))
                         .containsAll(Set.of(204, 400, 404, 422, 409)));
+        Assertions.assertEquals(
+                405,
+                route(definition, RoutingVerb.QUERY, "projects/:id/tasks/:id").status().value());
     }
 
     private Thingifier model() {
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/http/ApiRequestEnvelopeTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/http/ApiRequestEnvelopeTest.java
index 12ff8a6b..b4635d0d 100644
--- a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/http/ApiRequestEnvelopeTest.java
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/http/ApiRequestEnvelopeTest.java
@@ -44,4 +44,21 @@ public void postEnvelopeParsesBodyIntoTypedBodyFieldsOnceAtTheEdge() {
                                         "relationships.project.guid".equals(entry.getKey())
                                                 && "p1".equals(entry.getValue())));
     }
+
+    @Test
+    public void queryEnvelopeCombinesUriAndBodyQueryParams() {
+        HttpApiRequest request =
+                new HttpApiRequest("/tasks")
+                        .setFilterableQueryParams("status=Open")
+                        .setBody("title=Task");
+
+        ApiRequestEnvelope envelope =
+                ApiRequestEnvelope.from(
+                        request, ThingifierHttpApi.HttpVerb.QUERY, List.of("task", "tasks"));
+
+        Assertions.assertEquals(ThingifierHttpApi.HttpVerb.QUERY, envelope.verb());
+        Assertions.assertEquals(2, envelope.queryParams().size());
+        Assertions.assertEquals("status", envelope.queryParams().get(0).fieldName);
+        Assertions.assertEquals("title", envelope.queryParams().get(1).fieldName);
+    }
 }
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiQueryHandlerTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiQueryHandlerTest.java
new file mode 100644
index 00000000..e7870c43
--- /dev/null
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/restapihandlers/RestApiQueryHandlerTest.java
@@ -0,0 +1,247 @@
+package uk.co.compendiumdev.thingifier.api.restapihandlers;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import uk.co.compendiumdev.thingifier.Thingifier;
+import uk.co.compendiumdev.thingifier.api.http.HttpApiRequest;
+import uk.co.compendiumdev.thingifier.api.http.HttpApiResponse;
+import uk.co.compendiumdev.thingifier.api.http.ThingifierHttpApi;
+import uk.co.compendiumdev.thingifier.core.EntityRelModel;
+import uk.co.compendiumdev.thingifier.core.domain.definitions.Cardinality;
+import uk.co.compendiumdev.thingifier.core.domain.definitions.EntityDefinition;
+import uk.co.compendiumdev.thingifier.core.domain.definitions.field.definition.Field;
+import uk.co.compendiumdev.thingifier.core.domain.definitions.field.definition.FieldType;
+import uk.co.compendiumdev.thingifier.core.domain.instances.EntityInstance;
+import uk.co.compendiumdev.thingifier.core.domain.instances.EntityInstanceDraft;
+import uk.co.compendiumdev.thingifier.core.repository.ThingStore;
+
+public class RestApiQueryHandlerTest {
+
+    @Test
+    public void queryEntityCollectionUsesFormBodyFilters() {
+        Thingifier thingifier = taskProjectThingifier();
+        EntityInstance matching = createTask(thingifier, "Keep", "Open");
+        createTask(thingifier, "Skip", "Open");
+
+        HttpApiResponse response =
+                new ThingifierHttpApi(thingifier).queryRequest(query("tasks", "title=Keep"));
+
+        Assertions.assertEquals(200, response.getStatusCode());
+        Assertions.assertTrue(response.apiResponse().isCollection());
+        Assertions.assertEquals(1, response.apiResponse().getReturnedInstanceCollection().size());
+        Assertions.assertEquals(
+                matching, response.apiResponse().getReturnedInstanceCollection().get(0));
+        Assertions.assertEquals(
+                ThingifierHttpApi.QUERY_CONTENT_TYPE,
+                response.getHeaders().get(ThingifierHttpApi.ACCEPT_QUERY_HEADER));
+    }
+
+    @Test
+    public void queryEntityCollectionCombinesUriParamsAndBodyParams() {
+        Thingifier thingifier = taskProjectThingifier();
+        EntityInstance matching = createTask(thingifier, "Keep", "Open");
+        createTask(thingifier, "Keep", "Closed");
+        createTask(thingifier, "Skip", "Open");
+
+        HttpApiRequest request =
+                query("tasks", "title=Keep").setFilterableQueryParams("status=Open");
+        HttpApiResponse response = new ThingifierHttpApi(thingifier).queryRequest(request);
+
+        Assertions.assertEquals(200, response.getStatusCode());
+        Assertions.assertEquals(1, response.apiResponse().getReturnedInstanceCollection().size());
+        Assertions.assertEquals(
+                matching, response.apiResponse().getReturnedInstanceCollection().get(0));
+    }
+
+    @Test
+    public void queryRelationshipCollectionFiltersRelatedInstancesOnly() {
+        Thingifier thingifier = taskProjectThingifier();
+        ThingStore store = storeFor(thingifier);
+        EntityInstance project = createProject(thingifier, "Project");
+        EntityInstance matching = createTask(thingifier, "Keep", "Open");
+        EntityInstance relatedButFilteredOut = createTask(thingifier, "Skip", "Open");
+        createTask(thingifier, "Keep", "Open");
+        store.relationships().connect(project, "tasks", matching);
+        store.relationships().connect(project, "tasks", relatedButFilteredOut);
+
+        HttpApiResponse response =
+                new ThingifierHttpApi(thingifier)
+                        .queryRequest(
+                                query(
+                                        "projects/" + project.getPrimaryKeyValue() + "/tasks",
+                                        "title=Keep"));
+
+        Assertions.assertEquals(200, response.getStatusCode());
+        Assertions.assertEquals(1, response.apiResponse().getReturnedInstanceCollection().size());
+        Assertions.assertEquals(
+                matching, response.apiResponse().getReturnedInstanceCollection().get(0));
+    }
+
+    @Test
+    public void querySingleInstanceIsMethodNotAllowed() {
+        Thingifier thingifier = taskProjectThingifier();
+        EntityInstance task = createTask(thingifier, "Task", "Open");
+
+        HttpApiResponse response =
+                new ThingifierHttpApi(thingifier)
+                        .queryRequest(query("tasks/" + task.getPrimaryKeyValue(), "title=Task"));
+
+        Assertions.assertEquals(405, response.getStatusCode());
+        Assertions.assertEquals(
+                "OPTIONS, GET, HEAD, POST, PUT, DELETE", response.getHeaders().get("Allow"));
+    }
+
+    @Test
+    public void queryRelationshipLinkIsMethodNotAllowed() {
+        Thingifier thingifier = taskProjectThingifier();
+        EntityInstance project = createProject(thingifier, "Project");
+        EntityInstance task = createTask(thingifier, "Task", "Open");
+
+        HttpApiResponse response =
+                new ThingifierHttpApi(thingifier)
+                        .queryRequest(
+                                query(
+                                        "projects/"
+                                                + project.getPrimaryKeyValue()
+                                                + "/tasks/"
+                                                + task.getPrimaryKeyValue(),
+                                        "title=Task"));
+
+        Assertions.assertEquals(405, response.getStatusCode());
+        Assertions.assertEquals("OPTIONS, DELETE", response.getHeaders().get("Allow"));
+    }
+
+    @Test
+    public void missingRelationshipParentKeepsExistingNotFoundBehaviour() {
+        Thingifier thingifier = taskProjectThingifier();
+
+        HttpApiResponse response =
+                new ThingifierHttpApi(thingifier)
+                        .queryRequest(query("projects/missing/tasks", "title=Task"));
+
+        Assertions.assertEquals(404, response.getStatusCode());
+    }
+
+    @Test
+    public void missingContentTypeIsBadRequest() {
+        Thingifier thingifier = taskProjectThingifier();
+        HttpApiRequest request = new HttpApiRequest("tasks").setBody("title=Task");
+
+        HttpApiResponse response = new ThingifierHttpApi(thingifier).queryRequest(request);
+
+        Assertions.assertEquals(400, response.getStatusCode());
+        Assertions.assertEquals(
+                ThingifierHttpApi.QUERY_CONTENT_TYPE,
+                response.getHeaders().get(ThingifierHttpApi.ACCEPT_QUERY_HEADER));
+    }
+
+    @Test
+    public void unsupportedQueryContentTypeReturnsUnsupportedMediaType() {
+        Thingifier thingifier = taskProjectThingifier();
+        HttpApiRequest request =
+                new HttpApiRequest("tasks")
+                        .addHeader("Content-Type", "application/json")
+                        .setBody("{\"title\":\"Task\"}");
+
+        HttpApiResponse response = new ThingifierHttpApi(thingifier).queryRequest(request);
+
+        Assertions.assertEquals(415, response.getStatusCode());
+        Assertions.assertEquals(
+                ThingifierHttpApi.QUERY_CONTENT_TYPE, response.getHeaders().get("Accept"));
+        Assertions.assertEquals(
+                ThingifierHttpApi.QUERY_CONTENT_TYPE,
+                response.getHeaders().get(ThingifierHttpApi.ACCEPT_QUERY_HEADER));
+    }
+
+    @Test
+    public void malformedQueryContentIsBadRequest() {
+        Thingifier thingifier = taskProjectThingifier();
+
+        HttpApiResponse response =
+                new ThingifierHttpApi(thingifier).queryRequest(query("tasks", "title=%"));
+
+        Assertions.assertEquals(400, response.getStatusCode());
+    }
+
+    @Test
+    public void queryBodyHonoursMaxRequestBodyLength() {
+        Thingifier thingifier = taskProjectThingifier();
+        thingifier.apiConfig().statusCodes().setMaxRequestBodyLengthBytes(3);
+
+        HttpApiResponse response =
+                new ThingifierHttpApi(thingifier).queryRequest(query("tasks", "title=Task"));
+
+        Assertions.assertEquals(413, response.getStatusCode());
+    }
+
+    @Test
+    public void emptyQueryBodyIsValidAndReturnsUnfilteredCollection() {
+        Thingifier thingifier = taskProjectThingifier();
+        createTask(thingifier, "One", "Open");
+        createTask(thingifier, "Two", "Closed");
+
+        HttpApiResponse response =
+                new ThingifierHttpApi(thingifier).queryRequest(query("tasks", ""));
+
+        Assertions.assertEquals(200, response.getStatusCode());
+        Assertions.assertEquals(2, response.apiResponse().getReturnedInstanceCollection().size());
+    }
+
+    @Test
+    public void getCollectionAdvertisesQuerySupport() {
+        Thingifier thingifier = taskProjectThingifier();
+
+        HttpApiResponse response =
+                new ThingifierHttpApi(thingifier).get(new HttpApiRequest("tasks"));
+
+        Assertions.assertEquals(200, response.getStatusCode());
+        Assertions.assertEquals(
+                ThingifierHttpApi.QUERY_CONTENT_TYPE,
+                response.getHeaders().get(ThingifierHttpApi.ACCEPT_QUERY_HEADER));
+    }
+
+    private Thingifier taskProjectThingifier() {
+        Thingifier thingifier = new Thingifier();
+        EntityDefinition task = thingifier.defineThing("task", "tasks");
+        task.addAsPrimaryKeyField(Field.is("guid", FieldType.AUTO_GUID));
+        task.addField(Field.is("title", FieldType.STRING));
+        task.addField(Field.is("status", FieldType.STRING));
+
+        EntityDefinition project = thingifier.defineThing("project", "projects");
+        project.addAsPrimaryKeyField(Field.is("guid", FieldType.AUTO_GUID));
+        project.addField(Field.is("title", FieldType.STRING));
+
+        thingifier
+                .defineRelationship(project, task, "tasks", Cardinality.ONE_TO_MANY())
+                .whenReversed(Cardinality.ONE_TO_MANY(), "task-of");
+        return thingifier;
+    }
+
+    private EntityInstance createTask(
+            final Thingifier thingifier, final String title, final String status) {
+        EntityDefinition task = thingifier.getDefinitionNamed("task");
+        return storeFor(thingifier)
+                .entities()
+                .create(
+                        EntityInstanceDraft.forEntity(task)
+                                .withField("title", title)
+                                .withField("status", status));
+    }
+
+    private EntityInstance createProject(final Thingifier thingifier, final String title) {
+        EntityDefinition project = thingifier.getDefinitionNamed("project");
+        return storeFor(thingifier)
+                .entities()
+                .create(EntityInstanceDraft.forEntity(project).withField("title", title));
+    }
+
+    private ThingStore storeFor(final Thingifier thingifier) {
+        return thingifier.getStore(EntityRelModel.DEFAULT_DATABASE_NAME);
+    }
+
+    private HttpApiRequest query(final String path, final String body) {
+        return new HttpApiRequest(path)
+                .addHeader("Content-Type", ThingifierHttpApi.QUERY_CONTENT_TYPE)
+                .setBody(body);
+    }
+}
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPageTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPageTest.java
index 6cbdef9f..ad5dd5e7 100644
--- a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPageTest.java
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPageTest.java
@@ -17,6 +17,8 @@ void includesCopyForAiAssetsAndOpenApiConfiguration() {
                                 apiDefn,
                                 new DefaultGUIHTML(),
                                 "/mirror/docs/openapi.json",
+                                "/mirror/docs/openapi-3.0.json",
+                                "/mirror/docs/openapi-3.1.json",
                                 "/mirror/docs",
                                 "/mirror/docs/swagger",
                                 "/mirror/docs/swagger-ui")
@@ -26,5 +28,8 @@ void includesCopyForAiAssetsAndOpenApiConfiguration() {
         Assertions.assertTrue(html.contains("/js/swagger-copy-for-ai.js"));
         Assertions.assertTrue(html.contains("window.thingifierSwaggerCopyForAi"));
         Assertions.assertTrue(html.contains("openApiUrl: \"/mirror/docs/openapi.json\""));
+        Assertions.assertTrue(html.contains("/mirror/docs/openapi-3.0.json"));
+        Assertions.assertTrue(html.contains("/mirror/docs/openapi-3.1.json"));
+        Assertions.assertTrue(html.contains("\"urls.primaryName\": \"OpenAPI 3.1 default\""));
     }
 }

From 5e5daf637760eff5e9beecbf1cbd522f6883bc61 Mon Sep 17 00:00:00 2001
From: Alan Richardson <alan@compendiumdev.co.uk>
Date: Sun, 26 Jul 2026 11:25:42 +0100
Subject: [PATCH 2/4] Add OpenAPI 3.2 spec output

---
 .../swaggerizer/SwaggerizerTest.java          |  25 ++++
 .../crudui/ApiDocumentationPage.java          |   1 +
 .../thingifier/crudui/SwaggerUiPage.java      |   1 +
 .../adapter/javalin/CrudUiApplication.java    |   6 +
 .../crudui/CrudUiControllerTest.java          |  21 +++
 .../thingifier/crudui/e2e/CrudUiApiIT.java    |   1 +
 .../ThingifierAutoDocGenRouting.java          |   3 +
 .../RestApiDocumentationGenerator.java        |   2 +
 .../swaggerizer/OpenApi32Finalizer.java       |  89 +++++++++++++
 .../OpenApiSpecificationVersion.java          |  14 +-
 .../thingifier/swaggerizer/SwaggerUiPage.java |  10 ++
 .../thingifier/swaggerizer/Swaggerizer.java   |  25 +++-
 .../RestApiDocumentationGeneratorTest.java    |   1 +
 .../swaggerizer/OpenApi32FinalizerTest.java   | 122 ++++++++++++++++++
 .../swaggerizer/SwaggerUiPageTest.java        |   2 +
 15 files changed, 318 insertions(+), 5 deletions(-)
 create mode 100644 thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApi32Finalizer.java
 create mode 100644 thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApi32FinalizerTest.java

diff --git a/swaggerizer/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerizerTest.java b/swaggerizer/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerizerTest.java
index 7cf0d704..c58e36f0 100644
--- a/swaggerizer/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerizerTest.java
+++ b/swaggerizer/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerizerTest.java
@@ -1,5 +1,6 @@
 package uk.co.compendiumdev.thingifier.swaggerizer;
 
+import com.google.gson.JsonObject;
 import com.google.gson.JsonParser;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
@@ -50,6 +51,30 @@ public void canCreateOpenApi30Swagger() {
         Assertions.assertTrue(swagger.contains("application/x-www-form-urlencoded"));
     }
 
+    @Test
+    public void canCreateOpenApi32Swagger() {
+        Thingifier t = new TodoListThingifierTestModel().get();
+
+        ThingifierApiDocumentationDefn apiDefn = new ThingifierApiDocumentationDefn();
+        apiDefn.setThingifier(t);
+        apiDefn.setVersion("1.0.1");
+
+        String swagger = new Swaggerizer(apiDefn).asJson(OpenApiSpecificationVersion.OPENAPI_3_2);
+        JsonObject document = JsonParser.parseString(swagger).getAsJsonObject();
+        JsonObject todos = document.getAsJsonObject("paths").getAsJsonObject("/todos");
+        JsonObject query = todos.getAsJsonObject("query");
+
+        Assertions.assertEquals("3.2.0", openApiVersion(swagger));
+        Assertions.assertTrue(todos.has("query"));
+        Assertions.assertFalse(swagger.contains("\"x-query-operation\""));
+        Assertions.assertFalse(swagger.contains("\"x-http-method\""));
+        Assertions.assertFalse(swagger.contains("\"x-query-content-types\""));
+        Assertions.assertTrue(
+                query.getAsJsonObject("requestBody")
+                        .getAsJsonObject("content")
+                        .has("application/x-www-form-urlencoded"));
+    }
+
     private String openApiVersion(final String swagger) {
         return JsonParser.parseString(swagger).getAsJsonObject().get("openapi").getAsString();
     }
diff --git a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/ApiDocumentationPage.java b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/ApiDocumentationPage.java
index 3e3be68b..59c9dab3 100644
--- a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/ApiDocumentationPage.java
+++ b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/ApiDocumentationPage.java
@@ -53,6 +53,7 @@ private void appendHeader(final StringBuilder html) {
         html.append("    <a href=\"/docs/swagger\">Download OpenAPI</a>\n");
         html.append("    <a href=\"/openapi.json\">Raw OpenAPI JSON</a>\n");
         html.append("    <a href=\"/openapi-3.1.json\">OpenAPI 3.1 JSON</a>\n");
+        html.append("    <a href=\"/openapi-3.2.json\">OpenAPI 3.2 JSON</a>\n");
         html.append("    <a href=\"/openapi-3.0.json\">OpenAPI 3.0 JSON</a>\n");
         html.append("  </nav>\n");
         html.append("  <h1>").append(escape(title())).append(" API Documentation</h1>\n");
diff --git a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/SwaggerUiPage.java b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/SwaggerUiPage.java
index 34c92da6..44372170 100644
--- a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/SwaggerUiPage.java
+++ b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/SwaggerUiPage.java
@@ -36,6 +36,7 @@ public String html() {
                 + "    urls: [\n"
                 + "      { url: \"/openapi.json\", name: \"OpenAPI 3.1 default\" },\n"
                 + "      { url: \"/openapi-3.1.json\", name: \"OpenAPI 3.1\" },\n"
+                + "      { url: \"/openapi-3.2.json\", name: \"OpenAPI 3.2\" },\n"
                 + "      { url: \"/openapi-3.0.json\", name: \"OpenAPI 3.0\" }\n"
                 + "    ],\n"
                 + "    \"urls.primaryName\": \"OpenAPI 3.1 default\",\n"
diff --git a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/adapter/javalin/CrudUiApplication.java b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/adapter/javalin/CrudUiApplication.java
index d534283e..fa13dc83 100644
--- a/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/adapter/javalin/CrudUiApplication.java
+++ b/thingifier-crud-ui/src/main/java/uk/co/compendiumdev/thingifier/crudui/adapter/javalin/CrudUiApplication.java
@@ -107,6 +107,12 @@ public void configureRoutes() {
                         write(
                                 response,
                                 controller.openApiJson(OpenApiSpecificationVersion.OPENAPI_3_1)));
+        ServerRoutes.get(
+                "/openapi-3.2.json",
+                (request, response) ->
+                        write(
+                                response,
+                                controller.openApiJson(OpenApiSpecificationVersion.OPENAPI_3_2)));
         ServerRoutes.get(
                 "/openapi-3.0.json",
                 (request, response) ->
diff --git a/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/CrudUiControllerTest.java b/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/CrudUiControllerTest.java
index dc6a5250..a818667f 100644
--- a/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/CrudUiControllerTest.java
+++ b/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/CrudUiControllerTest.java
@@ -322,6 +322,26 @@ public void openApiJsonCanBeGeneratedForOpenApi30() {
         }
     }
 
+    @Test
+    public void openApiJsonCanBeGeneratedForOpenApi32() {
+        try (ActiveThingifierWorkspace workspace =
+                ActiveThingifierWorkspace.defaultTodoManagerWorkspace()) {
+            workspace.replaceWithYaml(TestResources.text("/models/project-tasks.yaml"));
+            CrudUiController controller = new CrudUiController(workspace);
+
+            UiHttpResponse response =
+                    controller.openApiJson(OpenApiSpecificationVersion.OPENAPI_3_2);
+
+            Assertions.assertEquals(200, response.statusCode());
+            Assertions.assertEquals("application/json", response.contentType());
+            Assertions.assertEquals("3.2.0", openApiVersion(response.body()));
+            Assertions.assertTrue(response.body().contains("\"/api\""));
+            Assertions.assertTrue(response.body().contains("\"/projects/{id}/tasks\""));
+            Assertions.assertTrue(response.body().contains("\"query\""));
+            Assertions.assertFalse(response.body().contains("\"x-query-operation\""));
+        }
+    }
+
     @Test
     public void openApiDownloadAddsAttachmentHeader() {
         try (ActiveThingifierWorkspace workspace =
@@ -377,6 +397,7 @@ public void swaggerUiPageEmbedsUnpkgSwaggerUiForCurrentOpenApiJson() {
             Assertions.assertTrue(response.body().contains("SwaggerUIBundle"));
             Assertions.assertTrue(response.body().contains("/openapi.json"));
             Assertions.assertTrue(response.body().contains("/openapi-3.1.json"));
+            Assertions.assertTrue(response.body().contains("/openapi-3.2.json"));
             Assertions.assertTrue(response.body().contains("/openapi-3.0.json"));
             Assertions.assertTrue(response.body().contains("/css/swagger-copy-for-ai.css"));
             Assertions.assertTrue(response.body().contains("/js/swagger-copy-for-ai.js"));
diff --git a/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/e2e/CrudUiApiIT.java b/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/e2e/CrudUiApiIT.java
index aec5d259..e99b0d18 100644
--- a/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/e2e/CrudUiApiIT.java
+++ b/thingifier-crud-ui/src/test/java/uk/co/compendiumdev/thingifier/crudui/e2e/CrudUiApiIT.java
@@ -38,6 +38,7 @@ public void staticPagesAndGeneratedDocumentationAreReachable() {
         assertStatusContains("/swagger", 200, "swagger-copy-for-ai.js");
         assertStatusContains("/openapi.json", 200, "\"openapi\"");
         assertStatusContains("/openapi-3.1.json", 200, "\"openapi\"");
+        assertStatusContains("/openapi-3.2.json", 200, "\"openapi\"");
         assertStatusContains("/openapi-3.0.json", 200, "\"openapi\"");
         assertStatusContains("/docs/swagger", 200, "\"openapi\"");
 
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
index 96ca950f..8586eca6 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
@@ -28,6 +28,7 @@ public ThingifierAutoDocGenRouting(
         final String openApiPath = "%s/docs/openapi.json".formatted(pathPrefix);
         final String openApi30Path = "%s/docs/openapi-3.0.json".formatted(pathPrefix);
         final String openApi31Path = "%s/docs/openapi-3.1.json".formatted(pathPrefix);
+        final String openApi32Path = "%s/docs/openapi-3.2.json".formatted(pathPrefix);
         final String swaggerUiPath = "%s/docs/swagger-ui".formatted(pathPrefix);
 
         // TODO: config to enable docs and configure the URL and add a meta tag for description and
@@ -51,6 +52,7 @@ public ThingifierAutoDocGenRouting(
 
         registerOpenApiEndpoint(apiDefn, openApiPath, OpenApiSpecificationVersion.OPENAPI_3_1);
         registerOpenApiEndpoint(apiDefn, openApi31Path, OpenApiSpecificationVersion.OPENAPI_3_1);
+        registerOpenApiEndpoint(apiDefn, openApi32Path, OpenApiSpecificationVersion.OPENAPI_3_2);
         registerOpenApiEndpoint(apiDefn, openApi30Path, OpenApiSpecificationVersion.OPENAPI_3_0);
 
         get(
@@ -64,6 +66,7 @@ public ThingifierAutoDocGenRouting(
                                     openApiPath,
                                     openApi30Path,
                                     openApi31Path,
+                                    openApi32Path,
                                     docsPath,
                                     swaggerDownloadPath,
                                     swaggerUiPath)
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
index 0f3a12bc..b87c11a5 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
@@ -451,6 +451,8 @@ public String getApiDocumentation(
         }
         output.append(
                 paragraph(href("[openapi 3.1 json]", prependPath + "/docs/openapi-3.1.json")));
+        output.append(
+                paragraph(href("[openapi 3.2 json]", prependPath + "/docs/openapi-3.2.json")));
         output.append(
                 paragraph(href("[openapi 3.0 json]", prependPath + "/docs/openapi-3.0.json")));
         output.append(
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApi32Finalizer.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApi32Finalizer.java
new file mode 100644
index 00000000..81f97252
--- /dev/null
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApi32Finalizer.java
@@ -0,0 +1,89 @@
+package uk.co.compendiumdev.thingifier.swaggerizer;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import uk.co.compendiumdev.thingifier.api.http.ThingifierHttpApi;
+
+public final class OpenApi32Finalizer {
+
+    private final Gson gson = new GsonBuilder().disableHtmlEscaping().setPrettyPrinting().create();
+
+    public String finalizeJson(final String openApi31Json) {
+        final JsonObject document = JsonParser.parseString(openApi31Json).getAsJsonObject();
+        document.addProperty("openapi", OpenApiSpecificationVersion.OPENAPI_3_2.documentVersion());
+        promoteQueryOperations(document);
+        return gson.toJson(document);
+    }
+
+    private void promoteQueryOperations(final JsonObject document) {
+        final JsonObject paths = objectAt(document, "paths");
+        if (paths == null) {
+            return;
+        }
+
+        for (String pathName : paths.keySet()) {
+            final JsonObject path = objectAt(paths, pathName);
+            if (path == null || !path.has("x-query-operation")) {
+                continue;
+            }
+
+            final JsonElement queryOperation = path.remove("x-query-operation");
+            if (queryOperation == null || !queryOperation.isJsonObject()) {
+                continue;
+            }
+
+            final JsonObject query = queryOperation.getAsJsonObject();
+            query.remove("x-http-method");
+            query.remove("x-query-content-types");
+            ensureFormEncodedRequestBody(query);
+            path.add("query", query);
+        }
+    }
+
+    private void ensureFormEncodedRequestBody(final JsonObject operation) {
+        JsonObject requestBody = objectAt(operation, "requestBody");
+        if (requestBody == null) {
+            requestBody = new JsonObject();
+            operation.add("requestBody", requestBody);
+        }
+
+        if (!requestBody.has("required")) {
+            requestBody.addProperty("required", false);
+        }
+
+        JsonObject content = objectAt(requestBody, "content");
+        if (content == null) {
+            content = new JsonObject();
+            requestBody.add("content", content);
+        }
+
+        JsonObject formMediaType = objectAt(content, ThingifierHttpApi.QUERY_CONTENT_TYPE);
+        if (formMediaType == null) {
+            formMediaType = new JsonObject();
+            content.add(ThingifierHttpApi.QUERY_CONTENT_TYPE, formMediaType);
+        }
+
+        if (!formMediaType.has("schema") || !formMediaType.get("schema").isJsonObject()) {
+            formMediaType.add("schema", permissiveFormSchema());
+        }
+    }
+
+    private JsonObject permissiveFormSchema() {
+        final JsonObject schema = new JsonObject();
+        schema.addProperty("type", "object");
+        final JsonObject additionalProperties = new JsonObject();
+        additionalProperties.addProperty("type", "string");
+        schema.add("additionalProperties", additionalProperties);
+        return schema;
+    }
+
+    private JsonObject objectAt(final JsonObject parent, final String name) {
+        if (parent == null || !parent.has(name) || !parent.get(name).isJsonObject()) {
+            return null;
+        }
+        return parent.getAsJsonObject(name);
+    }
+}
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApiSpecificationVersion.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApiSpecificationVersion.java
index e520f551..fbe52e74 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApiSpecificationVersion.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApiSpecificationVersion.java
@@ -4,7 +4,8 @@
 
 public enum OpenApiSpecificationVersion {
     OPENAPI_3_0("3.0", "3.0.1", "OpenAPI 3.0", SpecVersion.V30),
-    OPENAPI_3_1("3.1", "3.1.0", "OpenAPI 3.1", SpecVersion.V31);
+    OPENAPI_3_1("3.1", "3.1.0", "OpenAPI 3.1", SpecVersion.V31),
+    OPENAPI_3_2("3.2", "3.2.0", "OpenAPI 3.2", SpecVersion.V31);
 
     private final String versionNumber;
     private final String documentVersion;
@@ -37,4 +38,15 @@ public String displayName() {
     public SpecVersion specVersion() {
         return specVersion;
     }
+
+    public OpenApiSpecificationVersion swaggerCoreGenerationVersion() {
+        if (this == OPENAPI_3_2) {
+            return OPENAPI_3_1;
+        }
+        return this;
+    }
+
+    public boolean requiresOpenApi32Finalization() {
+        return this == OPENAPI_3_2;
+    }
 }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java
index 9d3d149a..1dbf0934 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPage.java
@@ -19,6 +19,7 @@ public final class SwaggerUiPage {
     private final String openApiUrl;
     private final String openApi30Url;
     private final String openApi31Url;
+    private final String openApi32Url;
     private final String docsUrl;
     private final String downloadUrl;
     private final String canonicalUrl;
@@ -29,6 +30,7 @@ public SwaggerUiPage(
             final String openApiUrl,
             final String openApi30Url,
             final String openApi31Url,
+            final String openApi32Url,
             final String docsUrl,
             final String downloadUrl,
             final String canonicalUrl) {
@@ -37,6 +39,7 @@ public SwaggerUiPage(
         this.openApiUrl = openApiUrl;
         this.openApi30Url = openApi30Url;
         this.openApi31Url = openApi31Url;
+        this.openApi32Url = openApi32Url;
         this.docsUrl = docsUrl;
         this.downloadUrl = downloadUrl;
         this.canonicalUrl = canonicalUrl;
@@ -62,6 +65,10 @@ public String html() {
                 .append(escapeHtmlAttribute(openApi31Url))
                 .append("'>OpenAPI 3.1 JSON</a>");
         html.append(" | ");
+        html.append("<a href='")
+                .append(escapeHtmlAttribute(openApi32Url))
+                .append("'>OpenAPI 3.2 JSON</a>");
+        html.append(" | ");
         html.append("<a href='")
                 .append(escapeHtmlAttribute(openApi30Url))
                 .append("'>OpenAPI 3.0 JSON</a>");
@@ -84,6 +91,9 @@ public String html() {
         html.append("{url: \"")
                 .append(escapeJavaScriptString(openApi31Url))
                 .append("\", name: \"OpenAPI 3.1\"},");
+        html.append("{url: \"")
+                .append(escapeJavaScriptString(openApi32Url))
+                .append("\", name: \"OpenAPI 3.2\"},");
         html.append("{url: \"")
                 .append(escapeJavaScriptString(openApi30Url))
                 .append("\", name: \"OpenAPI 3.0\"}");
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java
index 27ce6700..2fe4140c 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/swaggerizer/Swaggerizer.java
@@ -58,7 +58,7 @@ public OpenAPI swagger(final OpenApiSpecificationVersion version) {
 
         config.includeMethodNotAllowedEndpoints = false;
         config.includeFieldValidation = true;
-        config.openApiSpecificationVersion = version;
+        config.openApiSpecificationVersion = version.swaggerCoreGenerationVersion();
 
         return swagger(config);
     }
@@ -75,15 +75,18 @@ public OpenAPI swaggerPermissive(final OpenApiSpecificationVersion version) {
 
         config.includeMethodNotAllowedEndpoints = true;
         config.includeFieldValidation = false;
-        config.openApiSpecificationVersion = version;
+        config.openApiSpecificationVersion = version.swaggerCoreGenerationVersion();
 
         return swagger(config);
     }
 
     public OpenAPI swagger(SwaggerGenerationConfig config) {
 
-        OpenAPI api = new OpenAPI(config.openApiSpecificationVersion.specVersion());
-        api.setOpenapi(config.openApiSpecificationVersion.documentVersion());
+        final OpenApiSpecificationVersion generationVersion =
+                config.openApiSpecificationVersion.swaggerCoreGenerationVersion();
+
+        OpenAPI api = new OpenAPI(generationVersion.specVersion());
+        api.setOpenapi(generationVersion.documentVersion());
 
         final Thingifier thingifier = apiDefn.getThingifier();
 
@@ -546,6 +549,15 @@ public String asJsonWithPreferredServer(
             final OpenApiSpecificationVersion version,
             final boolean permissive,
             final String preferredServerUrl) {
+        if (version.requiresOpenApi32Finalization()) {
+            return new OpenApi32Finalizer()
+                    .finalizeJson(
+                            asJsonWithPreferredServer(
+                                    OpenApiSpecificationVersion.OPENAPI_3_1,
+                                    permissive,
+                                    preferredServerUrl));
+        }
+
         final OpenAPI api = permissive ? swaggerPermissive(version) : swagger(version);
         preferServer(api, preferredServerUrl);
         return pretty(api, version);
@@ -560,6 +572,11 @@ public String asJson(final OpenApiSpecificationVersion version) {
     }
 
     public String asJson(final OpenApiSpecificationVersion version, boolean permissive) {
+        if (version.requiresOpenApi32Finalization()) {
+            return new OpenApi32Finalizer()
+                    .finalizeJson(asJson(OpenApiSpecificationVersion.OPENAPI_3_1, permissive));
+        }
+
         if (version != OpenApiSpecificationVersion.OPENAPI_3_1) {
             return pretty(permissive ? swaggerPermissive(version) : swagger(version), version);
         }
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGeneratorTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGeneratorTest.java
index 3a0067d0..1b16ade5 100644
--- a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGeneratorTest.java
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGeneratorTest.java
@@ -25,6 +25,7 @@ void apiDocumentationShowsSwaggerUiLinkByDefault() {
 
         Assertions.assertTrue(docs.contains("href='/mirror/docs/swagger-ui'"));
         Assertions.assertTrue(docs.contains("Open Swagger UI"));
+        Assertions.assertTrue(docs.contains("href='/mirror/docs/openapi-3.2.json'"));
     }
 
     @Test
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApi32FinalizerTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApi32FinalizerTest.java
new file mode 100644
index 00000000..f1fa4b76
--- /dev/null
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/OpenApi32FinalizerTest.java
@@ -0,0 +1,122 @@
+package uk.co.compendiumdev.thingifier.swaggerizer;
+
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+class OpenApi32FinalizerTest {
+
+    @Test
+    void promotesQueryExtensionToPathItemQueryOperation() {
+        final String source =
+                """
+                {
+                  "openapi": "3.1.0",
+                  "paths": {
+                    "/todos": {
+                      "get": {
+                        "responses": {
+                          "200": {
+                            "description": "OK"
+                          }
+                        }
+                      },
+                      "x-query-operation": {
+                        "summary": "query todos",
+                        "x-http-method": "QUERY",
+                        "x-query-content-types": [
+                          "application/x-www-form-urlencoded"
+                        ],
+                        "responses": {
+                          "200": {
+                            "description": "OK"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+                """;
+
+        final JsonObject document =
+                JsonParser.parseString(new OpenApi32Finalizer().finalizeJson(source))
+                        .getAsJsonObject();
+        final JsonObject todos = document.getAsJsonObject("paths").getAsJsonObject("/todos");
+        final JsonObject query = todos.getAsJsonObject("query");
+        final JsonObject formMediaType =
+                query.getAsJsonObject("requestBody")
+                        .getAsJsonObject("content")
+                        .getAsJsonObject("application/x-www-form-urlencoded");
+
+        Assertions.assertEquals("3.2.0", document.get("openapi").getAsString());
+        Assertions.assertTrue(todos.has("get"));
+        Assertions.assertTrue(todos.has("query"));
+        Assertions.assertFalse(todos.has("x-query-operation"));
+        Assertions.assertEquals("query todos", query.get("summary").getAsString());
+        Assertions.assertFalse(query.has("x-http-method"));
+        Assertions.assertFalse(query.has("x-query-content-types"));
+        Assertions.assertFalse(query.getAsJsonObject("requestBody").get("required").getAsBoolean());
+        Assertions.assertEquals(
+                "object", formMediaType.getAsJsonObject("schema").get("type").getAsString());
+        Assertions.assertEquals(
+                "string",
+                formMediaType
+                        .getAsJsonObject("schema")
+                        .getAsJsonObject("additionalProperties")
+                        .get("type")
+                        .getAsString());
+    }
+
+    @Test
+    void preservesExistingFormRequestBodySchema() {
+        final String source =
+                """
+                {
+                  "openapi": "3.1.0",
+                  "paths": {
+                    "/todos": {
+                      "x-query-operation": {
+                        "requestBody": {
+                          "required": true,
+                          "content": {
+                            "application/x-www-form-urlencoded": {
+                              "schema": {
+                                "type": "object",
+                                "properties": {
+                                  "title": {
+                                    "type": "string"
+                                  }
+                                }
+                              }
+                            }
+                          }
+                        },
+                        "responses": {
+                          "200": {
+                            "description": "OK"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+                """;
+
+        final JsonObject query =
+                JsonParser.parseString(new OpenApi32Finalizer().finalizeJson(source))
+                        .getAsJsonObject()
+                        .getAsJsonObject("paths")
+                        .getAsJsonObject("/todos")
+                        .getAsJsonObject("query");
+
+        Assertions.assertTrue(query.getAsJsonObject("requestBody").get("required").getAsBoolean());
+        Assertions.assertTrue(
+                query.getAsJsonObject("requestBody")
+                        .getAsJsonObject("content")
+                        .getAsJsonObject("application/x-www-form-urlencoded")
+                        .getAsJsonObject("schema")
+                        .getAsJsonObject("properties")
+                        .has("title"));
+    }
+}
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPageTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPageTest.java
index ad5dd5e7..282ca8b4 100644
--- a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPageTest.java
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/swaggerizer/SwaggerUiPageTest.java
@@ -19,6 +19,7 @@ void includesCopyForAiAssetsAndOpenApiConfiguration() {
                                 "/mirror/docs/openapi.json",
                                 "/mirror/docs/openapi-3.0.json",
                                 "/mirror/docs/openapi-3.1.json",
+                                "/mirror/docs/openapi-3.2.json",
                                 "/mirror/docs",
                                 "/mirror/docs/swagger",
                                 "/mirror/docs/swagger-ui")
@@ -30,6 +31,7 @@ void includesCopyForAiAssetsAndOpenApiConfiguration() {
         Assertions.assertTrue(html.contains("openApiUrl: \"/mirror/docs/openapi.json\""));
         Assertions.assertTrue(html.contains("/mirror/docs/openapi-3.0.json"));
         Assertions.assertTrue(html.contains("/mirror/docs/openapi-3.1.json"));
+        Assertions.assertTrue(html.contains("/mirror/docs/openapi-3.2.json"));
         Assertions.assertTrue(html.contains("\"urls.primaryName\": \"OpenAPI 3.1 default\""));
     }
 }

From 079442d3e1b252fc33cfca9da4418cedf986c184 Mon Sep 17 00:00:00 2001
From: Alan Richardson <alan@compendiumdev.co.uk>
Date: Sun, 26 Jul 2026 12:04:16 +0100
Subject: [PATCH 3/4] Handle headerless routing definitions

---
 .../thingifier/api/docgen/RoutingDefinition.java       |  6 ++++++
 .../docgen/ApiRoutingDefinitionDocGeneratorTest.java   | 10 ++++++++++
 2 files changed, 16 insertions(+)

diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/RoutingDefinition.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/RoutingDefinition.java
index 46ec8c63..7139ee6d 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/RoutingDefinition.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/api/docgen/RoutingDefinition.java
@@ -62,6 +62,9 @@ public String urlWithParamFormatter(String prefix, String postfix) {
     }
 
     public String header() {
+        if (header == null) {
+            return "";
+        }
         if (header.headerName == null) {
             return "";
         }
@@ -70,6 +73,9 @@ public String header() {
     }
 
     public String headerValue() {
+        if (header == null) {
+            return "";
+        }
         if (header.headerValue == null) {
             return "";
         }
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGeneratorTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGeneratorTest.java
index de484605..27840924 100644
--- a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGeneratorTest.java
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/api/docgen/ApiRoutingDefinitionDocGeneratorTest.java
@@ -52,6 +52,16 @@ public void entityInstanceWritesDocumentValidationAndConflictStatuses() {
                 405, route(definition, RoutingVerb.QUERY, "todos/:id").status().value());
     }
 
+    @Test
+    public void routeDefinitionWithoutHeaderReturnsEmptyHeaderDetails() {
+        RoutingDefinition route =
+                new RoutingDefinition(
+                        RoutingVerb.DELETE, "todos", RoutingStatus.returnValue(405), null);
+
+        Assertions.assertEquals("", route.header());
+        Assertions.assertEquals("", route.headerValue());
+    }
+
     @Test
     public void relationshipWritesDocumentValidationAndConflictStatuses() {
         ApiRoutingDefinition definition =

From 448d1156f75f74187bec2c52f9ab5b6e2c7eca03 Mon Sep 17 00:00:00 2001
From: Alan Richardson <alan@compendiumdev.co.uk>
Date: Sun, 26 Jul 2026 13:05:13 +0100
Subject: [PATCH 4/4] Add versioned OpenAPI download links

---
 .../ThingifierAutoDocGenRouting.java          | 17 +++++++++-
 .../RestApiDocumentationGenerator.java        | 34 ++++++++++++-------
 .../RestApiDocumentationGeneratorTest.java    | 16 +++++++--
 3 files changed, 51 insertions(+), 16 deletions(-)

diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
index 8586eca6..cf93dbce 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/adapter/httpserver/ThingifierAutoDocGenRouting.java
@@ -116,9 +116,24 @@ private void registerOpenApiEndpoint(
                 (request, response) -> {
                     response.type("application/json");
                     response.status(200);
+                    final boolean permissive = request.queryParam("permissive") != null;
+                    if (request.queryParam("download") != null) {
+                        response.header(
+                                "Content-Disposition",
+                                "attachment; filename=\"%s\""
+                                        .formatted(openApiDownloadFilename(path, permissive)));
+                    }
                     return new Swaggerizer(apiDefn)
                             .asJsonWithPreferredServer(
-                                    version, false, HttpRequestOrigin.from(request));
+                                    version, permissive, HttpRequestOrigin.from(request));
                 });
     }
+
+    private String openApiDownloadFilename(final String path, final boolean permissive) {
+        final String filename = path.substring(path.lastIndexOf("/") + 1);
+        if (permissive) {
+            return "permissive-" + filename;
+        }
+        return filename;
+    }
 }
diff --git a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
index b87c11a5..48ee0e44 100644
--- a/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
+++ b/thingifier/src/main/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGenerator.java
@@ -449,19 +449,7 @@ public String getApiDocumentation(
         if (apiDocDefn.willShowSwaggerUiLink()) {
             output.append(paragraph(href("Open Swagger UI", prependPath + "/docs/swagger-ui")));
         }
-        output.append(
-                paragraph(href("[openapi 3.1 json]", prependPath + "/docs/openapi-3.1.json")));
-        output.append(
-                paragraph(href("[openapi 3.2 json]", prependPath + "/docs/openapi-3.2.json")));
-        output.append(
-                paragraph(href("[openapi 3.0 json]", prependPath + "/docs/openapi-3.0.json")));
-        output.append(
-                paragraph(href("[download normal swagger file]", prependPath + "/docs/swagger")));
-        output.append(
-                paragraph(
-                        href(
-                                "[download swagger file with less validation]",
-                                prependPath + "/docs/swagger?permissive")));
+        output.append(openApiVersionLinks());
 
         output.append(defaultGui.getEndOfMainContentMarker());
         output.append(defaultGui.getPageFooter());
@@ -469,6 +457,26 @@ public String getApiDocumentation(
         return output.toString();
     }
 
+    private String openApiVersionLinks() {
+        StringBuilder links = new StringBuilder();
+        links.append("<ul>%n".formatted());
+        links.append(openApiVersionLink("3.0", prependPath + "/docs/openapi-3.0.json"));
+        links.append(openApiVersionLink("3.1", prependPath + "/docs/openapi-3.1.json"));
+        links.append(openApiVersionLink("3.2", prependPath + "/docs/openapi-3.2.json"));
+        links.append("</ul>%n".formatted());
+        return links.toString();
+    }
+
+    private String openApiVersionLink(final String version, final String specUrl) {
+        return "<li>OpenAPI v %s JSON %s %s - %s %s</li>%n"
+                .formatted(
+                        version,
+                        href("[standard validation]", specUrl),
+                        href("[download]", specUrl + "?download"),
+                        href("[less validation]", specUrl + "?permissive"),
+                        href("[download]", specUrl + "?permissive&amp;download"));
+    }
+
     private String resolveDocsTitle(final ThingifierApiDocumentationDefn apiDocDefn) {
         if (apiDocDefn != null
                 && apiDocDefn.getSeoTitle() != null
diff --git a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGeneratorTest.java b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGeneratorTest.java
index 1b16ade5..0486a743 100644
--- a/thingifier/src/test/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGeneratorTest.java
+++ b/thingifier/src/test/java/uk/co/compendiumdev/thingifier/htmlgui/htmlgen/RestApiDocumentationGeneratorTest.java
@@ -25,7 +25,18 @@ void apiDocumentationShowsSwaggerUiLinkByDefault() {
 
         Assertions.assertTrue(docs.contains("href='/mirror/docs/swagger-ui'"));
         Assertions.assertTrue(docs.contains("Open Swagger UI"));
-        Assertions.assertTrue(docs.contains("href='/mirror/docs/openapi-3.2.json'"));
+        Assertions.assertTrue(docs.contains("<li>OpenAPI v 3.0 JSON"));
+        Assertions.assertTrue(docs.contains("<li>OpenAPI v 3.1 JSON"));
+        Assertions.assertTrue(docs.contains("<li>OpenAPI v 3.2 JSON"));
+        Assertions.assertTrue(
+                docs.contains("href='/mirror/docs/openapi-3.2.json'>[standard validation]</a>"));
+        Assertions.assertTrue(docs.contains("href='/mirror/docs/openapi-3.2.json?download'"));
+        Assertions.assertTrue(docs.contains("href='/mirror/docs/openapi-3.2.json?permissive'"));
+        Assertions.assertTrue(
+                docs.contains("href='/mirror/docs/openapi-3.2.json?permissive&amp;download'"));
+        Assertions.assertFalse(docs.contains("download normal swagger file"));
+        Assertions.assertFalse(docs.contains("download swagger file with less validation"));
+        Assertions.assertFalse(docs.contains("Add <code>?download</code>"));
     }
 
     @Test
@@ -45,6 +56,7 @@ void apiDocumentationCanHideSwaggerUiLink() {
 
         Assertions.assertFalse(docs.contains("href='/mirror/docs/swagger-ui'"));
         Assertions.assertFalse(docs.contains("Open Swagger UI"));
-        Assertions.assertTrue(docs.contains("href='/mirror/docs/swagger'"));
+        Assertions.assertFalse(docs.contains("href='/mirror/docs/swagger'"));
+        Assertions.assertTrue(docs.contains("<li>OpenAPI v 3.0 JSON"));
     }
 }