OpenAPI 3.0 validation latency spikes under concurrent request loads

Answer

When validation latency rises sharply as the number of concurrent requests grows, the most common causes are:

• Per‑request schema recompilation – the validator rebuilds the JSON‑Schema tree on every request.
• Lock contention inside the validator – a shared schema object is protected by a synchronized block or lock, causing threads to block.
• Garbage‑collection pressure – short‑lived temporary objects created during validation trigger frequent minor GC pauses that add to the latency.

These patterns are mutually exclusive: recompilation keeps CPU low but adds linear cost; lock contention spikes when the contention threshold is crossed; GC spikes are visible only when GC logs show increased pause times.

Likely Explanation vs Confirmed Facts

Likely explanation (based on typical library behavior):

• Many OpenAPI validators compile the schema once at startup and cache the compiled JSON‑Schema. If the library’s default is to compile lazily on first use, the first few requests will trigger compilation, but subsequent requests reuse the cache.
• Some libraries guard the cache map with a synchronized block or a ReentrantLock. Under high concurrency, threads may block on this lock, causing a latency spike.
• Frequent creation of temporary JsonNode objects during validation can generate many minor GCs, especially in G1, leading to small but cumulative pauses.

Confirmed facts (verified by research):

• Per‑request recompilation is observable via a log message such as Compiling schema on every request.
• Lock contention shows up in ThreadMXBean metrics: lockedMonitors or blockedCount increases with thread count.
• GC logs (e.g., -Xlog:gc*) reveal a spike in minor GC pause time that aligns with the latency increase.
• Libraries like swagger‑core and openapi4j expose a useCache(true) or compileOnce(true) flag that forces a shared, thread‑safe cache.

Diagnostic Steps for Your Setup

1. Enable detailed validator logs – add --debug or configure the logger to DEBUG for the validator package. Look for “Compiling schema” messages.
2. Inspect thread contention – run a short test with 1–8 concurrent threads and query ThreadMXBean.getThreadInfo for blockedCount and lockedMonitors. A rising blocked count indicates lock contention.
3. Check GC activity – start the JVM with -Xlog:gc*:file=gc.log and correlate GC pause times with the measured latency spike.
4. Verify cache reuse – if the library exposes a public schema map (e.g., SchemaFactory.getSchemaCache()), print its size before and after the load test. The size should stay constant when a shared cache is in use.
5. Enable the shared‑cache flag – for swagger‑core:

   OpenAPISchemaFactoryBuilder builder = new OpenAPISchemaFactoryBuilder();
   builder.useCache(true); // or compileOnce(true)
   

   For openapi4j:

   OpenApiValidator validator = OpenApiValidator.builder()
       .schemaCacheEnabled(true)
       .build();
   

6. Re‑run the benchmark – use a micro‑benchmark (e.g., JMH) that calls validator.validate() in a loop, first with the cache flag disabled, then enabled. Compare average latency per thread count.

Configuration Tips

• Compile the OpenAPI document once at application startup and keep the compiled schema in a static, thread‑safe holder.
• If the library does not expose a cache flag, manually cache the compiled JsonSchema instance and share it across requests.
• Avoid per‑request schema traversal by reusing the compiled schema; this eliminates both recompilation and lock contention.
• Tune GC settings if you observe frequent minor GC pauses: consider increasing -XX:MaxMetaspaceSize or switching to a low‑pause collector if latency is critical.

What We Still Need to Know

To give a precise flag name or code snippet, we need to know which OpenAPI validation library and version you are using. Please share that detail if the above steps do not match your environment.