openapi3: cache compiled JSON Schema 2020-12 validator per *Schema

[efritz]

useJSONSchema2020 calls newJSONSchemaValidator(schema) on every invocation. Compilation is expensive (marshal → unmarshal → keyword transform → jsonschema.Compile), and openapi3filter automatically takes this path for every OpenAPI 3.1 request, making it dominant per-request overhead for long-lived servers.

This PR caches the compiled *jsonSchemaValidator in a package-level sync.Map keyed by *Schema: first call compiles, subsequent calls do a single Load, races converge via LoadOrStore. Compilation failures are not cached (deterministic given the schema; sentinel value not worth the complexity).

Benchmark

Scratch benchmark validating a small object schema repeatedly (darwin/arm64, M4 Pro, -benchtime=2s):

	ns/op	B/op	allocs/op
Before	39,030	59,628	714
After	832	1,434	34
	~47×	~42×	~21×

benchmark source

package openapi3_test

import (
    "testing"

    "github.com/getkin/kin-openapi/openapi3"
)

func BenchmarkJSONSchema2020Validator(b *testing.B) {
    maxLen := uint64(64)
    age0, age150 := float64(0), float64(150)
    schema := &openapi3.Schema{
        Type: &openapi3.Types{"object"},
        Properties: openapi3.Schemas{
            "name":  &openapi3.SchemaRef{Value: &openapi3.Schema{Type: &openapi3.Types{"string"}, MinLength: 1, MaxLength: &maxLen}},
            "age":   &openapi3.SchemaRef{Value: &openapi3.Schema{Type: &openapi3.Types{"integer"}, Min: &age0, Max: &age150}},
            "email": &openapi3.SchemaRef{Value: &openapi3.Schema{Type: &openapi3.Types{"string"}, Format: "email"}},
        },
        Required: []string{"name", "age"},
    }
    value := map[string]any{"name": "Jane Doe", "age": 30, "email": "jane@example.com"}

    if err := schema.VisitJSON(value, openapi3.EnableJSONSchema2020()); err != nil {
        b.Fatal(err)
    }
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        if err := schema.VisitJSON(value, openapi3.EnableJSONSchema2020()); err != nil {
            b.Fatal(err)
        }
    }
}

[fenollp]

Please also demonstrate that updating the schema updates the cache.

[efritz]

Ah; maybe this approach doesn't work in general for an upstream patch.

In my usage, I assumed that once we're on this code path there would be no reasonable updates to the Schema object, so the cache would be useful for the lifetime of the schema.

Should the cache be busted on any change to the Schema, if we can cache validators at all?

[fenollp]

Yes. A way to update the cached data needs to exist.

If you can't come up with a satisfying cache key, one way to do this could be to piggy back on the Validate() call such that it does the compilation+caching at that time, not "on every invocation".

---

WRT your other approach I am not getting it. Please flesh it out more.

[efritz]

@fenollp We could also go with this approach: https://github.com/getkin/kin-openapi/compare/master...efritz:kin-openapi:cache-jsonschema2020-validator-2?expand=1

However, we'd still need an answer to the cache invalidation problem for general application.

[thanhtrann293]

We hit the same cost in production-style benchmarks (openapi3filter behind nethttp-middleware, one request with a patterned path parameter and a two-property JSON body: 1 737 → 88 allocs/op, 145 → 10 KB/op, ~400 → ~18 µs/op with a cache), and are running a fork with one while this is open. Two things from that work that may help here:

1. A pointer-keyed package map pins every schema it has seen. A server that reloads its document, or a test suite that loads thousands (APIs-guru's directory), keeps every old *Schema and its compiled validator alive. Keying by weak.Pointer[Schema] and deleting the entry with runtime.AddCleanup(schema, ...) avoids that (both are available at the module's go 1.25); on the full openapi3 test binary we measured no change in CPU or peak RSS.
2. Per-validation format validators (WithStringFormatValidators and kin) are read by the compiled validator's format checks, so a validator compiled with them must not be shared; compiling for the call when any are set keeps them honoured.

On the invalidation question: @fenollp's suggestion of doing the compilation in (*Schema).Validate() gives an explicit update point. Validate would compile and store (replacing any entry for that schema), VisitJSON would use the stored validator when there is one and compile for the call otherwise, so changing a schema and validating it again updates the cache, and callers that never call Validate see no change.

@efritz, are you still working on this? If not, I am happy to open a PR along those lines (weak-keyed entries, filled and replaced by Validate, per-validation formats bypassing it) with tests for the update, the cleanup and concurrent use.

[fenollp]

@thanhtrann293 feel free to open a PR