From cb2c21824b24a244fdb9b1f34dcb08fc9f49d09a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vin=C3=ADcius=20Ribeiro?=
<9574254+vinirib@users.noreply.github.com>
Date: Tue, 10 Nov 2026 20:19:35 -0300
Subject: [PATCH 1/2] perf: inject only the schema definitions a compiled
schema can reach
SchemaDefinitionsInjectionTransformer injected a deep copy of all of
components.schemas into every schema the validator compiles. Compiled schemas
are cached, so each cache entry kept its own copy of the whole definitions
block and the retained heap grew with the number of schemas validated times
the size of the specification.
It now injects only the definitions the schema can reach: the ones it refers
to and the ones those refer to in turn. A discriminator mapping counts as a
reference, with or without the #/components/schemas/ path. Each injected
definition is still a deep copy, and the transformation context still carries
the full set.
On a specification with 117 operations and 479 component schemas, validating
every operation once retained 1917 MB before and 109 MB after, and the first
validation of an operation went from 86 ms to 14 ms. Validation reports are
unchanged.
Fixes #42
---
...SchemaDefinitionsInjectionTransformer.java | 65 ++++++++++++-
...maDefinitionsInjectionTransformerTest.java | 95 +++++++++++++++++++
2 files changed, 159 insertions(+), 1 deletion(-)
create mode 100644 openapi-request-validator-core/src/test/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformerTest.java
diff --git a/openapi-request-validator-core/src/main/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformer.java b/openapi-request-validator-core/src/main/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformer.java
index e331ee10..c1aa0f2f 100644
--- a/openapi-request-validator-core/src/main/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformer.java
+++ b/openapi-request-validator-core/src/main/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformer.java
@@ -3,13 +3,27 @@
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
+import java.util.ArrayDeque;
+import java.util.Deque;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+
/**
* Simple transformer than injects schema definitions into the `#/components/schemas` path so that references resolve correctly.
+ *
+ * Only the definitions the schema can reach are injected: the ones it refers to, and the ones those refer to in turn.
+ * A compiled schema is cached, so every definition injected here is retained for as long as the cache entry lives.
+ * Injecting all of them made the retained size grow with (number of schemas validated) x (size of the specification),
+ * even when the specification was loaded fully resolved and the schema referred to none of them.
*/
public class SchemaDefinitionsInjectionTransformer extends SchemaTransformer {
private static final SchemaDefinitionsInjectionTransformer INSTANCE = new SchemaDefinitionsInjectionTransformer();
+ private static final String SCHEMA_REF_PREFIX = "#/components/schemas/";
+ private static final String MAPPING_FIELD = "mapping";
+
public static SchemaDefinitionsInjectionTransformer getInstance() {
return INSTANCE;
}
@@ -20,6 +34,55 @@ public void apply(final JsonNode schemaObject, final SchemaTransformationContext
return;
}
- ((ObjectNode) schemaObject).putObject(COMPONENTS_FIELD).set(SCHEMAS_FIELD, context.getSchemaDefinitions().deepCopy());
+ final JsonNode definitions = context.getSchemaDefinitions();
+ final ObjectNode injected = ((ObjectNode) schemaObject).putObject(COMPONENTS_FIELD).putObject(SCHEMAS_FIELD);
+ if (definitions == null) {
+ return;
+ }
+ // In the order they are declared, so the injected block does not depend on traversal order.
+ final Set referenced = referencedDefinitions(schemaObject, definitions);
+ definitions.fields().forEachRemaining(definition -> {
+ if (referenced.contains(definition.getKey())) {
+ injected.set(definition.getKey(), definition.getValue().deepCopy());
+ }
+ });
+ }
+
+ /**
+ * The names of the definitions reachable from the given schema, directly or through other definitions.
+ *
+ * Any text value that points at a definition counts, not only the value of a {@code $ref}, and so does a
+ * discriminator mapping that names a definition without the path.
+ */
+ private static Set referencedDefinitions(final JsonNode schemaObject, final JsonNode definitions) {
+ final Set referenced = new HashSet<>();
+ final Deque pending = new ArrayDeque<>();
+ pending.push(schemaObject);
+ while (!pending.isEmpty()) {
+ final JsonNode node = pending.pop();
+ if (node.isObject()) {
+ for (final Map.Entry field : node.properties()) {
+ if (MAPPING_FIELD.equals(field.getKey()) && field.getValue().isObject()) {
+ field.getValue().forEach(target -> reference(target.asText(), definitions, referenced, pending));
+ }
+ pending.push(field.getValue());
+ }
+ } else if (node.isArray()) {
+ node.forEach(pending::push);
+ } else if (node.isTextual() && node.textValue().startsWith(SCHEMA_REF_PREFIX)) {
+ reference(node.textValue().substring(SCHEMA_REF_PREFIX.length()), definitions, referenced, pending);
+ }
+ }
+ return referenced;
+ }
+
+ private static void reference(final String name,
+ final JsonNode definitions,
+ final Set referenced,
+ final Deque pending) {
+ final JsonNode definition = definitions.get(name);
+ if (definition != null && referenced.add(name)) {
+ pending.push(definition);
+ }
}
}
diff --git a/openapi-request-validator-core/src/test/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformerTest.java b/openapi-request-validator-core/src/test/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformerTest.java
new file mode 100644
index 00000000..4130a3bd
--- /dev/null
+++ b/openapi-request-validator-core/src/test/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformerTest.java
@@ -0,0 +1,95 @@
+package com.atlassian.oai.validator.schema.transform;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class SchemaDefinitionsInjectionTransformerTest {
+
+ private static final ObjectMapper MAPPER = new ObjectMapper();
+
+ private static final String DEFINITIONS = "{"
+ + "\"Order\":{\"type\":\"object\",\"properties\":{\"customer\":{\"$ref\":\"#/components/schemas/Customer\"}}},"
+ + "\"Customer\":{\"type\":\"object\",\"properties\":{\"address\":{\"$ref\":\"#/components/schemas/Address\"}}},"
+ + "\"Address\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}}},"
+ + "\"Folder\":{\"type\":\"object\",\"properties\":{\"children\":{\"type\":\"array\","
+ + "\"items\":{\"$ref\":\"#/components/schemas/Folder\"}}}},"
+ + "\"Cat\":{\"type\":\"object\"},"
+ + "\"Dog\":{\"type\":\"object\"},"
+ + "\"Unrelated\":{\"type\":\"object\"}"
+ + "}";
+
+ private final SchemaDefinitionsInjectionTransformer classUnderTest = SchemaDefinitionsInjectionTransformer.getInstance();
+
+ @Test
+ public void injectsNothing_whenSchemaRefersToNoDefinition() throws Exception {
+ final ObjectNode schema = schema("{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"}}}");
+
+ classUnderTest.apply(schema, context());
+
+ assertEquals(List.of(), injected(schema));
+ }
+
+ @Test
+ public void injectsReferencedDefinitions_andTheOnesTheyReferTo() throws Exception {
+ final ObjectNode schema = schema("{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/Order\"}}");
+
+ classUnderTest.apply(schema, context());
+
+ assertEquals(List.of("Order", "Customer", "Address"), injected(schema));
+ }
+
+ @Test
+ public void injectsSelfReferencingDefinition_once() throws Exception {
+ final ObjectNode schema = schema("{\"$ref\":\"#/components/schemas/Folder\"}");
+
+ classUnderTest.apply(schema, context());
+
+ assertEquals(List.of("Folder"), injected(schema));
+ }
+
+ @Test
+ public void injectsDefinitionsNamedByDiscriminatorMapping_withAndWithoutPath() throws Exception {
+ final ObjectNode schema = schema("{\"oneOf\":[{\"type\":\"object\"},{\"type\":\"object\"}],"
+ + "\"discriminator\":{\"propertyName\":\"kind\","
+ + "\"mapping\":{\"cat\":\"#/components/schemas/Cat\",\"dog\":\"Dog\"}}}");
+
+ classUnderTest.apply(schema, context());
+
+ assertEquals(List.of("Cat", "Dog"), injected(schema));
+ }
+
+ @Test
+ public void injectsCopies_soTheSharedDefinitionsAreNeverMutated() throws Exception {
+ final SchemaTransformationContext context = context();
+ final ObjectNode schema = schema("{\"$ref\":\"#/components/schemas/Address\"}");
+
+ classUnderTest.apply(schema, context);
+ ((ObjectNode) schema.at("/components/schemas/Address")).put("additionalProperties", false);
+
+ assertTrue(schema.at("/components/schemas/Address").has("additionalProperties"));
+ assertFalse(context.getSchemaDefinitions().get("Address").has("additionalProperties"));
+ }
+
+ private static List injected(final JsonNode schema) {
+ final List names = new ArrayList<>();
+ schema.at("/components/schemas").fieldNames().forEachRemaining(names::add);
+ return names;
+ }
+
+ private static ObjectNode schema(final String json) throws Exception {
+ return (ObjectNode) MAPPER.readTree(json);
+ }
+
+ private static SchemaTransformationContext context() throws Exception {
+ return SchemaTransformationContext.create().withDefinitions(MAPPER.readTree(DEFINITIONS)).build();
+ }
+}
From bb90ed4473aa69cdd2adceaaee1badef10b6cc2c Mon Sep 17 00:00:00 2001
From: Vinicius Ribeiro
Date: Tue, 10 Nov 2026 23:22:26 -0300
Subject: [PATCH 2/2] fix: inject definitions referenced by a nested or encoded
reference
A reference can point inside a definition
(#/components/schemas/Order/properties/customer) and can percent-encode or
JSON Pointer escape the definition name (My%20Type, a~1b). Both resolved
before and were skipped by the reachability walk, so the definition was not
injected and the reference failed to resolve.
Also iterate the definitions with properties() instead of the deprecated
fields().
---
...SchemaDefinitionsInjectionTransformer.java | 30 +++++++++++++++----
...maDefinitionsInjectionTransformerTest.java | 22 ++++++++++++++
2 files changed, 46 insertions(+), 6 deletions(-)
diff --git a/openapi-request-validator-core/src/main/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformer.java b/openapi-request-validator-core/src/main/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformer.java
index c1aa0f2f..ad483a87 100644
--- a/openapi-request-validator-core/src/main/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformer.java
+++ b/openapi-request-validator-core/src/main/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformer.java
@@ -3,6 +3,8 @@
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
import java.util.ArrayDeque;
import java.util.Deque;
import java.util.HashSet;
@@ -39,13 +41,13 @@ public void apply(final JsonNode schemaObject, final SchemaTransformationContext
if (definitions == null) {
return;
}
- // In the order they are declared, so the injected block does not depend on traversal order.
final Set referenced = referencedDefinitions(schemaObject, definitions);
- definitions.fields().forEachRemaining(definition -> {
+ // In the order they are declared, so the injected block does not depend on traversal order.
+ for (final Map.Entry definition : definitions.properties()) {
if (referenced.contains(definition.getKey())) {
injected.set(definition.getKey(), definition.getValue().deepCopy());
}
- });
+ }
}
/**
@@ -70,19 +72,35 @@ private static Set referencedDefinitions(final JsonNode schemaObject, fi
} else if (node.isArray()) {
node.forEach(pending::push);
} else if (node.isTextual() && node.textValue().startsWith(SCHEMA_REF_PREFIX)) {
- reference(node.textValue().substring(SCHEMA_REF_PREFIX.length()), definitions, referenced, pending);
+ reference(definitionName(node.textValue()), definitions, referenced, pending);
}
}
return referenced;
}
+ // A reference can point inside a definition, e.g. #/components/schemas/Order/properties/customer
+ private static String definitionName(final String reference) {
+ final int end = reference.indexOf('/', SCHEMA_REF_PREFIX.length());
+ return end < 0 ? reference.substring(SCHEMA_REF_PREFIX.length()) : reference.substring(SCHEMA_REF_PREFIX.length(), end);
+ }
+
private static void reference(final String name,
final JsonNode definitions,
final Set referenced,
final Deque pending) {
- final JsonNode definition = definitions.get(name);
- if (definition != null && referenced.add(name)) {
+ final String key = definitions.has(name) ? name : decoded(name);
+ final JsonNode definition = definitions.get(key);
+ if (definition != null && referenced.add(key)) {
pending.push(definition);
}
}
+
+ // A reference is a URI fragment holding a JSON Pointer, so it can percent-encode the name and escape '~' and '/' in it.
+ private static String decoded(final String name) {
+ try {
+ return URLDecoder.decode(name.replace("+", "%2B"), StandardCharsets.UTF_8).replace("~1", "/").replace("~0", "~");
+ } catch (final IllegalArgumentException e) {
+ return name;
+ }
+ }
}
diff --git a/openapi-request-validator-core/src/test/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformerTest.java b/openapi-request-validator-core/src/test/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformerTest.java
index 4130a3bd..63db4cd6 100644
--- a/openapi-request-validator-core/src/test/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformerTest.java
+++ b/openapi-request-validator-core/src/test/java/com/atlassian/oai/validator/schema/transform/SchemaDefinitionsInjectionTransformerTest.java
@@ -24,6 +24,8 @@ public class SchemaDefinitionsInjectionTransformerTest {
+ "\"items\":{\"$ref\":\"#/components/schemas/Folder\"}}}},"
+ "\"Cat\":{\"type\":\"object\"},"
+ "\"Dog\":{\"type\":\"object\"},"
+ + "\"Line Item\":{\"type\":\"object\"},"
+ + "\"Tax/Rate\":{\"type\":\"object\"},"
+ "\"Unrelated\":{\"type\":\"object\"}"
+ "}";
@@ -56,6 +58,26 @@ public void injectsSelfReferencingDefinition_once() throws Exception {
assertEquals(List.of("Folder"), injected(schema));
}
+ @Test
+ public void injectsDefinition_whenReferenceGoesIntoIt() throws Exception {
+ final ObjectNode schema = schema("{\"$ref\":\"#/components/schemas/Order/properties/customer\"}");
+
+ classUnderTest.apply(schema, context());
+
+ assertEquals(List.of("Order", "Customer", "Address"), injected(schema));
+ }
+
+ @Test
+ public void injectsDefinition_whenReferenceEncodesItsName() throws Exception {
+ final ObjectNode schema = schema("{\"type\":\"object\",\"properties\":{"
+ + "\"item\":{\"$ref\":\"#/components/schemas/Line%20Item\"},"
+ + "\"rate\":{\"$ref\":\"#/components/schemas/Tax~1Rate\"}}}");
+
+ classUnderTest.apply(schema, context());
+
+ assertEquals(List.of("Line Item", "Tax/Rate"), injected(schema));
+ }
+
@Test
public void injectsDefinitionsNamedByDiscriminatorMapping_withAndWithoutPath() throws Exception {
final ObjectNode schema = schema("{\"oneOf\":[{\"type\":\"object\"},{\"type\":\"object\"}],"