Corvus Go Evaluator

Go Standalone Evaluator

Overview

src-go/corvus-json-schema ports the Corvus.Text.Json.RuntimeEvaluator pipeline to Go, by way of the Rust port (src-rs/corvus-json-schema), which it follows file for file. loader.go and compiler.go build the node graph (schemaNode) and its analyses (marking, in-place cycles, discriminators). plan.go compiles each node to a fail-fast plan, and fused.go fuses an object's keywords across $ref, allOf, if/then/else, dependencies and oneOf/anyOf into one pass. eval.go is the general evaluator: it serves results collection, and the nodes that track evaluated properties or items. Document (document.go) is the instance model: the UTF-8 text plus a flat tape, two words per value. names.go is the property name lookup, pattern.go the regex-free pattern matchers, and internal/ecmaregex the ECMA-262 engine behind every other pattern. internal/ucd holds the Unicode tables that the engine and the formats read.

The module has no dependencies outside the standard library. Keep it that way: the benchmark and Bowtie harnesses are modules of their own for that reason.

The package README describes the design. OPTIMIZATIONS.md maps every optimisation to its counterpart in the C#, Rust and Java evaluators, and its Todo list is the order of the performance work. Keep it current: a technique added to any of the other evaluators should be checked off (or ruled out, with the reason) there.

Build and test

Go 1.25 or later. From src-go/corvus-json-schema:

go vet ./...
gofmt -l .                      # prints nothing when the code is formatted
go test -p 4 ./...              # every test
go test -p 4 -race ./...        # as CI does on Linux and macOS (needs a C compiler; CC=clang works)
JSONSCHEMA_BENCHMARK=<jsonschema-benchmark> go test -p 4 -run TestPlansAgree .   # plans against the general evaluator

The suites read the repository's JSON-Schema-Test-Suite submodule (or JSON_SCHEMA_TEST_SUITE). Every required, optional and format test must pass (draft4/optional/zeroTerminatedFloats.json is excluded, as in the C# runner), and all annotation assertions. Each case runs fail-fast as a document, as bytes and as a string, and through a collector at each level, and the verdicts must agree. SUITE_DRAFT and SUITE_FILTER narrow the run.

TestEmbeddedMetaschemasAreCurrent checks the embedded metaschemas (metaschemas/) against src/Corvus.Text.Json/metaschema. UPDATE_METASCHEMAS=1 copies them again.

src-go/corvus-json-schema-bowtie runs the Bowtie harness over IHOP on the required and annotation suites (go test -p 4 ./... there). CI (.github/workflows/go.yml) runs all of these on Linux x64 and arm64, Windows and macOS, with the oldest Go the module accepts, Go 1.26, Go 1.27 and the latest.

The minimum Go version and Unicode data

go.mod says go 1.25.0. CI tests that exact toolchain, Go 1.26, Go 1.27 and the latest release. Use no language or library feature newer than Go 1.25.

The module takes no Unicode data from the toolchain, so it gives the same results with every Go release. The standard library's unicode package is Unicode 15 in Go 1.25 and 1.26 and Unicode 17 in Go 1.27, and the \p classes and case folding of regexp and the case functions of strings and bytes read it. Never use any of them outside a test file. TestNoToolchainUnicodeData (unicode_test.go) scans the module and fails if one appears.

Use internal/ucd instead. ucd.Category, ucd.Script, ucd.ScriptExtensions and ucd.Binary return a *ucd.Table (Contains, AppendRanges), ucd.Letter() and its siblings are the general category groups, and ucd.Fold and ucd.ToUpper are the simple case mappings. For ASCII-only case rules use asciiLower (uri.go). A regular expression given to regexp must spell out ranges from the tables, as idnEmailLocalRegexp in formats.go and writeRE2 in internal/ecmaregex do.

internal/ucd/tables_gen.go holds Unicode 17, the version V8 answered with in internal/ecmaregex/testdata/v8_oracle.json. internal/ucd/gen_tables.ps1 writes it from the Unicode data of the regress crate that the Rust port depends on, already formatted as gofmt formats it:

pwsh src-go/corvus-json-schema/internal/ucd/gen_tables.ps1 -RegressTables ~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/regress-0.12.0/src/unicodetables.rs

To move to a later Unicode version, generate the tables from a regress release that carries it (pass -UnicodeVersion), record the V8 oracle again with a V8 of the same version (testdata/gen_oracle.js), and update TestTheDataIsUnicode17 in internal/ucd. Do the three together.