dry-validation-rust

dry-validation-rust is a performance-oriented hybrid Ruby/Rust validation engine with familiar dry-validation-style contract syntax and a precisely documented compatible subset. Rust handles the immutable declarative schema execution path; Ruby preserves dynamic rules and Ruby-specific semantics.

Note: This is an early-stage project. The side-by-side API is covered by focused tests, differential checks, package verification, and reproducible benchmark evidence, but it is not a full, production-ready drop-in replacement for upstream dry-validation.

Before adoption, review the support matrix, compatibility matrix, and verification evidence for the exact supported surface, platforms, and known boundaries.

New users can follow the Getting started guide to install the gem and build their first contract.

The native extension's Rust API reference is published with the documentation site.

For project participation and reporting routes, see CONTRIBUTING.md, SUPPORT.md, SECURITY.md, GOVERNANCE.md, and the Code of Conduct. Ask usage questions in GitHub Discussions. See the concise roadmap for planned outcomes and project-management policy for issue workflow.

• Rust owns the immutable schema plan, key lookup and normalization, nested traversal, built-in coercion, type checks, native predicates, output filtering, and structural error collection.
• Ruby owns class-level DSL capture, arbitrary rule blocks, injected Ruby objects, macros, custom behavior, and Ruby-specific predicate semantics.

Rewriting arbitrary Ruby blocks into Rust is neither generally possible nor desirable. Calling those blocks through Ruby preserves the feature that makes dry-validation useful: domain validation can be normal Ruby.

• It is not a proven drop-in replacement for upstream dry-validation.
• It is not a full Rust rewrite of the dry-rb validation stack.
• It does not claim full upstream compatibility without fixture-backed, version-pinned differential evidence.
• It does not claim general speedups without representative benchmarks.

When a precompiled gem is published for your platform, install it with:

gem install dry-validation-rust

See the support matrix for the authoritative version and platform status. If a source build is required, see the source-build instructions.

For new work, use require "dry/validation/rust" and subclass Dry::Validation::Rust::Contract. The Getting started guide has a copy-pasteable contract, rule, error-handling, and web-framework examples.

Version, platform, and upstream-reference targets are listed in SUPPORT_MATRIX.md. Supported DSL and semantic differences are listed in COMPATIBILITY.md.

The public side-by-side API is Dry::Validation::Rust::Contract, its nested Result and Values types, and the directly exposed Schema, MessageSet, and Evaluator types. Its compatibility policy is defined in the support matrix, with individual classifications in API_STABILITY.md. The exact-compatibility entrypoints are explicitly experimental and are not covered by that policy.

require "dry/validation/rust" exposes only the Dry::Validation::Rust namespace. It does not define Dry::Validation::Contract or Dry::Schema.

The upstream-like require "dry/validation" and require "dry/schema" entrypoints are deprecated and cannot safely coexist with upstream dry-validation or dry-schema in one Ruby process. Use side-by-side mode for new work; existing applications should follow the exact-mode migration guide.

This section is a summary. Version and platform support is authoritative in SUPPORT_MATRIX.md; feature support is authoritative in COMPATIBILITY.md.

• params, json, and plain schema modes.
• String-key normalization for Params and JSON.
• Integer, float, decimal, boolean, symbol, Date, DateTime, and Time Params coercions.
• Required/optional keys, filled, maybe, hashes, arrays, primitive array members, and arrays of nested hashes.
• Numeric and size predicates in Rust; format, inclusion, exclusion, and Ruby equality predicates in Ruby for semantic fidelity.
• Ordered rules that run only when their schema dependencies succeeded.
• Symbol, dot-string, array, and simple hash rule paths.
• value, values, key?, key.failure, key(path).failure, base.failure, schema_error?, rule_error?, and base_rule_error?.
• rule.each with index:.
• Global and class macros, macro arguments, injected option values, and mutable per-call context.
• Result hashes, message sets, metadata, full messages, filtering, and Ruby pattern matching.
• Contract inheritance and compatible schema reuse.

The complete exclusions and semantic differences are explicit in COMPATIBILITY.md.

Meet the source-build prerequisites first.

Then:

bundle install
bundle exec rake compile
bundle exec rake test

The source gem declares rb_sys ~> 0.9 and builds through the ordinary Ruby native-extension lifecycle.

Representative verification evidence, including its pinned runtime versions, is recorded in VERIFICATION.md.

The test suite covers the native plan, coercion modes, nested data, rules, rule skipping, array rules, macros, options, context, inheritance, external schemas, loading modes, pattern matching, metadata, concurrent calls, malformed input resilience, package contents, and differential compatibility fixtures.

The validation benchmark system has three deliberately separate jobs:

1. an interactive Benchmark.ips/MemoryProfiler showcase for local exploration and screenshots;
2. a repeatable publication runner for README, release, post, and CV evidence;
3. CI regression gates for detecting performance changes on CI hosts.

The detailed protocol and metric wording are documented in docs/BENCHMARKING.md.

Run the representative matrix directly when exploring a change:

ruby -Ilib benchmark/schema_throughput.rb
ENGINE=rust SCENARIO=medium_form ruby -Ilib benchmark/schema_throughput.rb
ENGINE=upstream SCENARIO=nested_object ruby -Ilib benchmark/schema_throughput.rb
IPS_WARMUP=3 IPS_TIME=10 MEMORY_PROFILE_N=5000 \
  SCENARIO=array_of_objects ruby -Ilib benchmark/schema_throughput.rb

Text output uses Benchmark.ips for warmed throughput, MemoryProfiler for Ruby-side allocation detail, and the fixed-run path for peak RSS. A single text run is useful evidence while developing, but it is not the canonical source for README/CV performance claims.

The matrix currently covers eleven validation shapes: small, medium, and large flat forms; deep nesting; arrays of nested objects; an all-invalid error path; sparse optional data; mixed scalar coercions; a large primitive array; wide nested data; and a contract that combines declarative schema work with Ruby-owned dynamic rules.

Use the publication runner before updating benchmark claims:

bundle exec rake compile
bundle exec script/benchmark-publication

By default it performs five independent measurements per engine/scenario. It first calibrates the iteration count for each scenario, then runs each engine in a fresh Ruby process using an engine-specific calibrated N, so a faster engine is not accidentally measured for a much shorter interval. Engine order alternates between runs and scenario order reverses every other run to reduce systematic host drift. Successful results are never discarded automatically. The full default matrix has 110 measurements, so it performs about 9 minutes of measured work before calibration, warmups, and process startup; the runner reports live calibration and measurement progress to stderr.

The runner records the exact Git SHA and dirty state, Ruby/platform/CPU details, YJIT state, Rust toolchain, requested and actually loaded upstream gem versions, protocol settings, every raw measurement, medians, ranges, median absolute deviation, paired throughput ratios, Ruby allocation changes, and peak RSS changes.

Results and checkpoints are written under tmp/benchmarks/ (already ignored by Git). If a run is interrupted, resume it from the printed checkpoint path:

RESUME_FROM=tmp/benchmarks/publication-...checkpoint.json \
  bundle exec script/benchmark-publication

For a longer final evidence run:

RUNS=7 TARGET_SECONDS=10 bundle exec script/benchmark-publication

RETRIES applies only to process/tooling failures. The runner does not retry a successful measurement merely because it is slow or weakens the speedup claim. Publication mode refuses a dirty working tree unless ALLOW_DIRTY=true is set; dirty runs are exploratory and should not become canonical README/CV evidence.

Use FORMAT=json on the lower-level benchmark only when tooling needs one single fixed-run payload:

FORMAT=json ENGINE=all SCENARIO=small_form \
  N=10000 WARMUP=1000 LATENCY_SAMPLES=500 \
  ruby -Ilib benchmark/schema_throughput.rb

Ruby allocation counters are useful for understanding GC pressure, but an allocated-object count is not a whole-process memory measurement. For a same-work comparison of the hybrid and upstream implementations, run:

bundle exec rake compile
bundle exec script/benchmark-memory-footprint

The memory runner uses the same validation count and warmup for both engines in each scenario. On Linux it records current/peak RSS plus PSS and USS around the timed validation loop. Peak RSS includes resident Ruby and Rust/native memory; PSS apportions shared pages and USS reports private resident pages. See docs/MEMORY_BENCHMARKING.md for exact metric semantics and limitations.

These are process-footprint metrics, not cumulative bytes allocated over time. Ruby object counts from GC.stat remain a separate GC-pressure signal.

Ruby allocation counters (GC.stat and the interactive MemoryProfiler section) describe Ruby-side allocation activity. Peak RSS is a whole-process resident high-water mark and already includes resident Ruby and Rust/native memory, but it is not cumulative allocated bytes and it fully counts shared resident pages. Use the separate process-memory runner for same-work RSS/PSS/USS comparisons. Throughput ratios apply to validation calls after contract/plan construction and must not be presented as end-to-end Rails request speedups.

Refresh the allocation-regression baseline only after intentionally reviewing an allocation change:

bundle exec script/record-allocation-baseline

The manual Record Allocation Baseline workflow produces the same JSON as an artifact without changing the repository. Review its value before replacing benchmark/baseline_allocations.json; do not accept an allocation regression merely by refreshing the baseline.

The upstream dry-validation gem remains intentionally outside the project dependencies. Install the comparison version for the same Ruby before running comparison/publication benchmarks. Report the exact upstream version with every published result.

Measure native JSON plan deserialization independently of validation calls:

cargo bench --locked --manifest-path ext/dry_validation_rust/Cargo.toml --bench plan_compile

CI runs this non-blocking benchmark on Ubuntu and retains the combined Criterion reports as the native-benchmarks artifact for 30 days. On 2026-08-14, the following 100-sample Criterion results were measured locally on x86_64 Linux (kernel 7.0.0-29-generic, AMD Ryzen 7 5800H) with Rust 1.90.0. Each generated Params-mode plan has validate_keys enabled; every field is a required string with one min_size(1) predicate. These figures are local baseline evidence, not a cross-host performance guarantee.

Measure the native Params-mode coercion path independently for common and Ruby-fallback literals:

cargo bench --locked --manifest-path ext/dry_validation_rust/Cargo.toml --bench coercion

CI runs the plan-compilation and coercion benchmarks non-blockingly on Ubuntu and retains their combined Criterion reports as the native-benchmarks artifact for 30 days.

The following coercion results were measured locally on 2026-08-14 with CRuby 3.4.4, Rust 1.90.0, and dry-validation-rust 0.1.0.pre4 on x86_64 Linux (kernel 7.0.0-29-generic, AMD Ryzen 7 5800H). Criterion used 100 samples with a 500 ms warm-up and 1 s measurement period per case. These are host-local baseline observations, not cross-host performance guarantees. Infinity exercises the intentional non-finite-float rejection path; the datetime-shaped date literal exercises the Ruby fallback path.

Measure the native comparison, size, and parity predicate paths with Ruby values created once before timing:

cargo bench --locked --manifest-path ext/dry_validation_rust/Cargo.toml --bench predicates

CI runs the plan-compilation, coercion, and predicate benchmarks non-blockingly on Ubuntu and retains their combined Criterion reports as the native-benchmarks artifact for 30 days.

The following results were measured locally on 2026-08-15 with CRuby 3.4.4, Rust 1.90.0, and dry-validation-rust 0.1.0.pre4 on x86_64 Linux (kernel 7.0.0-29-generic, AMD Ryzen 7 5800H). Criterion used 100 samples with a 500 ms warm-up and 1 s measurement period per case. Every input passes its predicate; values and predicate plans are prepared before the timed loop. These are host-local baseline observations, not cross-host performance guarantees.

Measure the native engine end-to-end with plans and Ruby Hash inputs prepared before Criterion begins timing:

cargo bench --locked --manifest-path ext/dry_validation_rust/Cargo.toml --bench full_schema

The following results were measured locally on 2026-08-15 with CRuby 3.4.4, Rust 1.90.0, and dry-validation-rust 0.1.0.pre4 on x86_64 Linux (kernel 7.0.0-29-generic, AMD Ryzen 7 5800H). Criterion used 100 samples with a 3-second warm-up and a 5-second measurement period per scenario. Plans and inputs are built once; mixed-validity scenarios cycle their prebuilt inputs. These figures measure Engine::call only, and are host-local baseline evidence—not a comparison with the Ruby contract benchmark or a cross-host performance guarantee.

The following publication runs compare the hybrid engine with dry-validation 1.11.1 (dry-schema 1.16.0 and dry-types 1.9.1) on CRuby 3.3.7, x86_64 Linux, and an AMD Ryzen 7 5800H. They are host-local evidence, not a cross-host guarantee or an end-to-end Rails request benchmark.

The throughput run measured commit e26bbb18e90f in seven isolated Ruby processes per engine and scenario, targeting 10 seconds each. It measures validation calls after contract/plan construction; ranges show the full set of successful measurements.

The separate process-memory run measured commit 0f2f46414bc9, also with seven runs and identical validation count/warmup for both engines within each scenario. Peak RSS is a whole-process high-water mark during the loop; the Linux-only PSS and USS measurements are taken after it. PSS apportions shared pages and USS counts private resident pages.

Ruby object reduction is a GC.stat count, not a byte total; negative values mean the hybrid path allocated more Ruby objects. None of RSS, PSS, or USS is a measure of cumulative allocated bytes. Reproduce fresh evidence with the publication runners above rather than extrapolating these host-local figures.

The native engine currently reads and creates Ruby objects, so it runs under the GVL. Rust reduces Ruby method dispatch and intermediate DSL execution; it does not automatically make validation parallel.

A future batch API could copy supported values into Rust-owned memory and release the GVL, but serialization/copy cost and Ruby object semantics make that a separate feature—not a free property of using Rust.

This code is MIT licensed and independent. dry-validation and its related dry-rb projects are MIT licensed as well, which permits reimplementation and derivative work subject to preserving required notices when source is copied. See NOTICE.md. The distinct gem name and explicit non-affiliation are intentional.