schemurai 3.1.0-x86_64-linux-gnu

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c00a32ecafec6236c7388c796820927005741e1eae12a5262d5366996887b0f0
+  data.tar.gz: 9da3a657e747265fe2715ab51ac15ad90fa863bec2db4ef24fd2efc947c4619b
+SHA512:
+  metadata.gz: '09a726ce41e47fab7e4683633d7f6d44819cf1bad4e5bec07612472c41146f24563fde88818549f20b7d001a407def2a007fba5b606062a044efd43d1842a517'
+  data.tar.gz: e135537f2b8edb27ee819d5c5be6b81cc09628c4ec58883664d12b085c7654b8283ffcfae99633f6d6e6d80bdce53528a97a9513525463e25597613833af5790

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kuya Kohara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,395 @@
+# Schemurai
+
+[![Gem Version](https://badge.fury.io/rb/schemurai.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/schemurai)
+[![test / rspec](https://github.com/oakcask/schemurai/actions/workflows/test--rspec.yaml/badge.svg)](https://github.com/oakcask/schemurai/actions/workflows/test--rspec.yaml)
+[![lint / rubocop](https://github.com/oakcask/schemurai/actions/workflows/lint--rubocop.yaml/badge.svg)](https://github.com/oakcask/schemurai/actions/workflows/lint--rubocop.yaml)
+[![lint / rbs](https://github.com/oakcask/schemurai/actions/workflows/lint--rbs.yaml/badge.svg)](https://github.com/oakcask/schemurai/actions/workflows/lint--rbs.yaml)
+
+A JSON Schema validator for Ruby with reusable compiled schemas and detailed
+validation errors. It supports Draft 7, Draft 2019-09, and Draft 2020-12 and
+covers the required cases in the official JSON-Schema-Test-Suite, as well as
+the applicable optional tests for numeric
+precision, ECMA-262 regular expressions, content validation, anchors, and dynamic
+references. The dialect is selected from the schema's `$schema` URI; schemas that
+omit `$schema` use Draft 7 for compatibility.
+
+Choose the default Ruby evaluator, the Ruby VM backend, or the optional
+experimental Rust native backend. See [backend selection](#backend-selection)
+for setup and requirements.
+
+Schemurai ships RBS declarations for its public API in `sig/schemurai.rbs`.
+
+```ruby
+require "schemurai"
+
+schema = {
+  "$schema" => "https://json-schema.org/draft/2020-12/schema",
+  "type" => "object",
+  "properties" => {
+    "order_id" => { "type" => "string", "pattern" => "^ord_[0-9]{6}$" },
+    "customer" => { "$ref" => "#/$defs/customer" },
+    "items" => {
+      "type" => "array",
+      "minItems" => 1,
+      "items" => { "$ref" => "#/$defs/line_item" }
+    },
+    "created_at" => { "type" => "string", "format" => "date-time" }
+  },
+  "required" => %w[order_id customer items created_at],
+  "additionalProperties" => false,
+  "$defs" => {
+    "customer" => {
+      "type" => "object",
+      "properties" => {
+        "id" => { "type" => "integer", "minimum" => 1 },
+        "name" => { "type" => "string", "minLength" => 1 },
+        "tier" => { "enum" => %w[standard premium] }
+      },
+      "required" => %w[id name],
+      "additionalProperties" => false
+    },
+    "line_item" => {
+      "type" => "object",
+      "properties" => {
+        "sku" => { "type" => "string", "pattern" => "^SKU-[A-Z0-9]{8}$" },
+        "quantity" => { "type" => "integer", "minimum" => 1 },
+        "unit_price" => { "type" => "number", "minimum" => 0 }
+      },
+      "required" => %w[sku quantity unit_price],
+      "additionalProperties" => false
+    }
+  }
+}
+
+order = {
+  "order_id" => "ord_123456",
+  "customer" => { "id" => 42, "name" => "Ada Lovelace", "tier" => "premium" },
+  "items" => [
+    { "sku" => "SKU-ABC12345", "quantity" => 2, "unit_price" => 19.95 }
+  ],
+  "created_at" => "2026-08-31T10:15:00+09:00"
+}
+
+validator = Schemurai.compile(schema, format: true)
+validator.valid?(order) # => true
+
+invalid_order = order.merge(
+  "items" => [order.fetch("items").first.merge("quantity" => 0)]
+)
+result = validator.validate(invalid_order)
+result.valid? # => false
+result.errors.each do |error|
+  puts "#{error.instance_path}: #{error.message}"
+end
+```
+
+For repeated validation, compile the schema once and reuse the validator. A
+schema registry owns the compiled resource graph, so schemas compiled by the
+same registry also share their compiled external references.
+
+```ruby
+registry = Schemurai::SchemaRegistry.new(
+  schemas: {
+    "https://example.test/positive" => { "type" => "integer", "minimum" => 1 }
+  }
+)
+validator = registry.compile({"$ref" => "https://example.test/positive"})
+
+validator.valid?(1) # => true
+validator.valid?(0) # => false
+validator.validate(0).errors # detailed errors, without recompiling the schema
+```
+
+`Schemurai.compile` is a convenience for compiling a standalone
+validator. Repeatedly compiling the same schema object with one registry reuses
+its compiled schema graph. `Schemurai.validate` and `.valid?` continue
+to accept raw JSON-like schemas and perform compilation internally.
+
+Schema inputs are checked recursively before compilation. They must use the
+built-in JSON-shaped Ruby classes described in
+[`docs/compatibility-domain.md`](docs/compatibility-domain.md); rejected values
+are never retained by a registry.
+
+To resolve external references, pass a mapping of URIs to schemas using
+`schemas:`.
+
+```ruby
+Schemurai.valid?(
+  { "$ref" => "https://example.test/positive" },
+  3,
+  schemas: { "https://example.test/positive" => { "type" => "integer", "minimum" => 1 } }
+)
+```
+
+Draft 2019-09 and Draft 2020-12 support their dialect-specific keywords, including
+`$recursiveRef` / `$dynamicRef`, `$defs`, `dependentSchemas`, `dependentRequired`,
+`minContains`, `maxContains`, and the `unevaluated*` applicators. Enable optional
+validation for `contentEncoding` and `contentMediaType` with `content: true`.
+Enable optional format assertions with `format: true`; support for each format is
+listed separately below.
+
+### Validation errors
+
+```ruby
+result = Schemurai.validate(
+  { "$ref" => "https://example.test/positive" },
+  -1,
+  schemas: { "https://example.test/positive" => { "type" => "integer", "minimum" => 1 } }
+)
+
+validation_error = result.errors[0]
+p validation_error.keyword # => "minimum"
+p validation_error.instance_path # => ""
+p validation_error.schema_path # => "/$ref/minimum"
+p validation_error.message # => "number must be greater than or equal to 1"
+```
+
+`Result#errors` contains `Schemurai::ValidationError` objects.
+Check the following attributes to investigate schema errors:
+
+- `keyword` identifies the failed JSON Schema keyword. Schemurai uses
+  `falseSchema` for a boolean `false` schema, which has no keyword of its own.
+- `instance_path` is a JSON Pointer to the value that failed validation.
+- `schema_path` is a JSON Pointer to the schema location that produced the
+  error.
+- `message` is a human-readable `String` describing the failure.
+
+An empty path points to the instance or schema root. Error order is stable.
+The presence and type of `message` are part of the public API, but its exact
+wording is not. Use `keyword`, `instance_path`, and `schema_path`, rather than
+matching `message`, when handling errors programmatically. `ValidationError#to_h`
+returns these four attributes as a Hash.
+
+### Thread / Ractor support
+
+To share a registry between threads or Ractors, finish registering schemas and
+make the registry shareable first. This eagerly compiles every registered
+schema, resolves all references, and makes the registry deeply immutable.
+
+```ruby
+registry = Schemurai::SchemaRegistry.new(
+  schemas: {
+    "https://example.test/positive" => { "type" => "integer", "minimum" => 1 },
+    "https://example.test/value" => { "$ref" => "https://example.test/positive" }
+  },
+  # enable virtual machine backend that is faster for iterative validation.
+  backend: :vm
+)
+registry.make_shareable
+
+# Each thread or Ractor creates and owns its validator.
+validator = registry.validator_for("https://example.test/value")
+```
+
+`make_shareable` calls `Ractor.make_shareable` internally. It raises a
+`ResolutionError` if a reference cannot be resolved. After it returns,
+`validator_for` is read-only and may be called concurrently, while `compile` is
+no longer available. A `Validator` contains per-validation mutable state and
+must not be shared between threads or Ractors. With the VM and native backends,
+the registry compiles and shares its bytecode before this transition. The native
+backend also prepares shared native instruction tables for all four combinations
+of `content` and `format`; `validator_for` does not recompile them in each Ractor.
+Native regex search caches and Ruby runtime helper state belong to each
+validator. Preparing these tables adds time and memory to `make_shareable`.
+
+### Meta-schema validation
+
+Meta-schema validation is opt-in so ordinary compilation does not pay its
+additional time and memory cost. Set `validate_schema: true` when creating a
+`SchemaRegistry` to validate every schema registered through `schemas:` and
+every schema passed to `compile`. The convenience `compile`, `validate`, and
+`valid?` methods accept the same option and apply it to their internal registry.
+Schemas without `$schema` use the Draft 7 meta-schema. An invalid schema raises
+`Schemurai::InvalidSchemaError`, whose `result` contains the detailed validation
+errors.
+
+```ruby
+Schemurai.compile(schema, validate_schema: true)
+
+registry = Schemurai::SchemaRegistry.new(
+  schemas: external_schemas,
+  validate_schema: true
+)
+validator = registry.compile(schema)
+
+result = Schemurai.validate_schema(schema)
+result.valid? # whether the schema itself is valid
+```
+
+`SchemaRegistry#validate_schema` and `#valid_schema?` perform explicit checks
+regardless of the registry option and reuse meta-schema graph data within that
+registry. The stateful validator used for a check is temporary; no global
+validator is retained.
+
+### Opt-in validation limits (experimental)
+
+`max_errors:` and `timeout:` are optional kwargs. Both default to `nil`
+(unlimited) and apply independently to each validation call. `max_errors` must
+be a nonnegative Integer; `timeout` must be finite nonnegative Integer or Float
+seconds. No settings object is needed.
+
+```ruby
+validator = Schemurai.compile(schema, max_errors: 100, timeout: 0.1)
+begin
+  result = validator.validate(order)
+rescue Schemurai::LimitExceeded => error
+  # Evaluation is incomplete; no partial result is returned.
+  warn "Validation stopped at #{error.limit}"
+end
+
+validator.validate(order, max_errors: 10) # retains the compiled timeout
+validator.validate(order, timeout: nil)  # retains the compiled error cap
+validator.validate(order, max_errors: nil, timeout: nil) # disables both
+validator.valid?(order) # applies the timeout, ignores max_errors
+```
+
+`SchemaRegistry#compile`, `#validator_for`, the convenience `validate` / `valid?`
+methods and explicit meta-schema checks also accept these kwargs. Overrides
+replace only the specified option. Settings belong to each compiled validator;
+a shareable registry retains no mutable invocation counters.
+
+The error cap checks before constructing the next emitted diagnostic. Exactly
+`max_errors` errors may be returned; attempting another raises `LimitExceeded`
+with `limit == :max_errors`, `maximum` and `attempted` counts. Suppressed
+applicator trials do not consume the cap. Boolean checks ignore the error cap
+and use the ordinary evaluator when no timeout is set.
+
+The timeout uses a monotonic elapsed-time deadline, including diagnostic
+rendering and native runtime helper calls and retries. It checks at entry,
+before returning and every 256 checkpoints in evaluation, container scans and
+structural traversal.
+Ruby string/content operations also check before and after expensive calls.
+Zero seconds stops even a trivial call. Expiry raises `LimitExceeded` with
+`limit == :timeout`; `maximum` and `attempted` are configured and elapsed seconds.
+Native returns an exhaustion status and releases Rust resources before Ruby
+raises. A limit hit is terminal. Native validation does not fall back to VM
+execution, with or without invocation limits.
+
+This implementation never uses Ruby `Timeout`, timer threads, signals or
+asynchronous exception injection. It is cooperative: one regexp search, scalar
+operation, JSON decode, allocation or custom format callback may overrun until
+the next checkpoint. GC and descheduling count toward elapsed time; the polling
+interval bounds skipped checkpoints, not elapsed overrun. Compilation,
+registration and automatic compile-time meta-schema validation are outside the
+timeout. Explicit meta-schema checks can set their own timeout.
+
+Use the error cap to bound diagnostic count and the timeout to bound prolonged
+traversal. They protect different resources: a deadline does not bound the
+number of diagnostics, and an error cap cannot stop a long successful check.
+Input byte size and nesting depth belong at the parsing boundary. An error cap
+does not bound the size of an individual message. Preempting individual scalar
+operations requires operation-specific limits or a supervised worker process.
+The backends retain their respective Ruby, VM and native execution paths and
+native memoization. Timed native bulk pattern/format/content and Fixnum contains
+scans use per-item evaluation so successful scans can poll.
+
+### Backend selection
+
+`Schemurai.backend`, `SchemaRegistry#backend`, and `Validator#backend` expose
+the selected backend. Pass `backend: :ruby` to force the Ruby oracle or
+`backend: :vm` to ahead-of-time compile schemas for the validator virtual machine.
+Pass `backend: :native` to use the experimental Rust VM extension. Releases
+include precompiled gems on RubyGems.org for CRuby 4.0 on these platforms:
+
+| OS | CPU | libc | Gem platform |
+| --- | --- | --- | --- |
+| Linux | x64 | glibc 2.36+ | `x86_64-linux-gnu` |
+| Linux | arm64 | glibc 2.36+ | `aarch64-linux-gnu` |
+| Linux | x64 | musl (Alpine 3.23+) | `x86_64-linux-musl` |
+| Linux | arm64 | musl (Alpine 3.23+) | `aarch64-linux-musl` |
+| macOS 14+ | x64 | — | `x86_64-darwin` |
+| macOS 14+ | arm64 | — | `arm64-darwin` |
+
+RubyGems/Bundler selects the matching platform gem during normal installation;
+these gems need no C compiler, Rust, or Ruby development headers. Each platform
+gem bundles its supported Ruby minor ABIs and restricts `required_ruby_version`
+to that range. Ruby patch releases share the same binary. To build from source,
+use `gem install schemurai --platform ruby` or Bundler's `force_ruby_platform`.
+See [native gem releases](docs/native-gem-releases.md) for the build matrix.
+
+Building the native extension from source requires a C toolchain, Ruby
+development headers, and Rust 1.93 or newer. If cargo is absent, installation of
+the source gem skips the optional native
+extension and Ruby/VM remain available; explicitly selecting `:native` then
+raises `LoadError`. Native execution borrows Ruby values directly; its current coverage and
+remaining VM delegation are documented below.
+Schema graph construction remains shared Ruby infrastructure. Environment-based selection
+is documented in [`docs/backend-selection.md`](docs/backend-selection.md).
+
+## JSON Schema conformance
+
+| Capability | Draft 7 | Draft 2019-09 | Draft 2020-12 |
+| --- | --- | --- | --- |
+| Required JSON-Schema-Test-Suite cases | Supported | Supported | Supported |
+| Dialect-specific references | `$ref` | `$ref`, `$recursiveRef` | `$ref`, `$dynamicRef` |
+| `unevaluatedItems` / `unevaluatedProperties` | Not applicable | Supported | Supported |
+| `contentEncoding` / `contentMediaType` assertions | Opt-in[^content] | Opt-in[^content] | Opt-in[^content] |
+
+The required-suite row covers every required case for the listed dialect in the
+[official JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite).
+The applicable top-level optional cases are also tested, including arbitrary
+precision numbers, ECMA-262 regular expressions, anchors, cross-draft references,
+and dynamic references.
+
+### Format assertion support
+
+Formats are annotations by default in each standard dialect. Pass `format: true`
+to enable the supported assertions below.[^format]
+
+| Format | Assertion support |
+| --- | --- |
+| `date` | Supported |
+| `time` | Supported |
+| `date-time` | Supported |
+| `duration` | Supported |
+| `email` | Not supported |
+| `idn-email` | Not supported |
+| `hostname` | Not supported |
+| `idn-hostname` | Not supported |
+| `ipv4` | Supported |
+| `ipv6` | Supported |
+| `uri` | Not supported |
+| `uri-reference` | Not supported |
+| `iri` | Not supported |
+| `iri-reference` | Not supported |
+| `uuid` | Supported |
+| `uri-template` | Not supported |
+| `json-pointer` | Supported |
+| `relative-json-pointer` | Supported |
+| `regex` | Not supported |
+
+Unsupported and unknown formats remain annotations when assertion is enabled by
+the caller.
+
+[^content]: Pass `content: true` to assert Base64 `contentEncoding` and JSON
+    `contentMediaType`. Other encodings and media types remain annotations.
+[^format]: A custom Draft 2020-12 meta-schema that declares the Format-Assertion
+    vocabulary can assert supported formats without the option and rejects
+    unsupported formats during schema compilation.
+
+## Development
+
+Run the test suite with:
+
+```sh
+bundle exec rspec
+```
+
+Verify the reviewed official-suite classifications with:
+
+```sh
+ruby script/oracle-cases --summary
+```
+
+The serialized oracle tools are `script/oracle-runner` and
+`script/oracle-compare`.
+
+Run the linter with:
+
+```sh
+bundle exec rubocop
+```
+
+## AI Disclosure
+
+Large part of this work is generated by OpenAI Codex.

data/lib/schemurai/backend.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Schemurai
+  module Backend
+    VM_FEATURE = "vm/evaluator"
+    CHOICES = %i[default ruby vm native].freeze
+
+    module_function def requested
+      value = ENV.fetch("SCHEMURAI_BACKEND", "default").to_sym
+      return value if CHOICES.include?(value)
+
+      raise Error, "unknown Schemurai backend #{value.inspect}"
+    end
+
+    module_function def resolve(selection = requested)
+      selection = selection.to_sym
+      raise Error, "unknown Schemurai backend #{selection.inspect}" unless CHOICES.include?(selection)
+
+      selection = production_default if selection == :default
+      load_vm! if selection == :vm
+      require_relative "native/evaluator" if selection == :native
+      selection
+    end
+
+    module_function def production_default
+      :ruby
+    end
+
+    module_function def load_vm!
+      require_relative VM_FEATURE
+      require_relative "vm/limited_evaluator"
+    end
+  end
+end

data/lib/schemurai/container_checks/array_diagnostics.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "../evaluation"
+require_relative "../error_message"
+
+module Schemurai
+  module Internal
+    module ContainerChecks
+      module ArrayDiagnostics
+        private def check_array(rules, value, prior_evaluation)
+          evaluation = nil
+          if rules.max_items && value.length > rules.max_items
+            return Evaluation.invalid unless collecting_array_errors?
+
+            array_error("maxItems", rules, value)
+          end
+          if rules.min_items && value.length < rules.min_items
+            return Evaluation.invalid unless collecting_array_errors?
+
+            array_error("minItems", rules, value)
+          end
+          if rules.unique && !unique_items?(value)
+            return Evaluation.invalid unless collecting_array_errors?
+
+            array_error("uniqueItems", rules, value)
+          end
+
+          if (prefix_items = rules.prefix_items)
+            prefix_items.each_with_index do |child, index|
+              @budget&.checkpoint
+              break if index >= value.length
+              valid = evaluate_child_at(child, value[index], index, "prefixItems", index)
+              return Evaluation.invalid if !valid && !collecting_array_errors?
+              (evaluation ||= tracked_evaluation).record_item(index)
+            end
+          end
+
+          items = rules.items
+          if rules.items_list
+            items.each_with_index do |child, index|
+              @budget&.checkpoint
+              break if index >= value.length
+              valid = evaluate_child_at(child, value[index], index, "items", index)
+              return Evaluation.invalid if !valid && !collecting_array_errors?
+              (evaluation ||= tracked_evaluation).record_item(index)
+            end
+            if value.length > items.length && (additional = rules.additional)
+              (items.length...value.length).each do |index|
+                @budget&.checkpoint
+                valid = evaluate_child_at(additional, value[index], index, "additionalItems")
+                return Evaluation.invalid if !valid && !collecting_array_errors?
+                (evaluation ||= tracked_evaluation).record_item(index)
+              end
+            end
+          elsif items
+            start = rules.prefix_items&.length || 0
+            (start...value.length).each do |index|
+              @budget&.checkpoint
+              valid = evaluate_child_at(items, value[index], index, "items")
+              return Evaluation.invalid if !valid && !collecting_array_errors?
+              (evaluation ||= tracked_evaluation).record_item(index)
+            end
+          end
+
+          if (contains = rules.contains)
+            matched = nil
+            index = 0
+            while index < value.length
+              @budget&.checkpoint
+              (matched ||= []) << index if trial(contains, value[index]).valid?
+              index += 1
+            end
+            matched_count = matched ? matched.length : 0
+            unless matched_count.between?(rules.min_contains, rules.max_contains)
+              return Evaluation.invalid unless collecting_array_errors?
+
+              array_error("contains", rules, value, matched_count)
+            end
+            if matched
+              matched.each { |index| (evaluation ||= tracked_evaluation).record_item(index) }
+            end
+          end
+
+          if (unevaluated = rules.unevaluated)
+            prior_items = prior_evaluation.evaluated_items
+            index = 0
+            while index < value.length
+              @budget&.checkpoint
+              if prior_items.include?(index) || evaluation&.evaluated_items&.include?(index)
+                index += 1
+                next
+              end
+              valid = evaluate_child_at(unevaluated, value[index], index, "unevaluatedItems")
+              return Evaluation.invalid if !valid && !collecting_array_errors?
+              (evaluation ||= tracked_evaluation).record_item(index)
+              index += 1
+            end
+          end
+          return Evaluation.valid unless evaluation
+
+          evaluation
+        end
+
+        private def collecting_array_errors? = @errors
+
+        private def array_error(keyword, rules, value, actual = nil)
+          add_error(keyword) do
+            case keyword
+            when "maxItems" then ErrorMessage.size(keyword, rules.max_items, value.length)
+            when "minItems" then ErrorMessage.size(keyword, rules.min_items, value.length)
+            when "uniqueItems" then ErrorMessage.unique_items
+            when "contains" then ErrorMessage.contains(actual, rules.min_contains, rules.max_contains)
+            end
+          end
+        end
+      end
+    end
+  end
+end