schemurai 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6c7e69c0dbcafac0bb00bc78aa315932cfd59a141d0727e1a6e4366f80dc416b
+  data.tar.gz: 1ddb9269a448dc6c088a7bf22f341e064c2bb3cd0712da6750fc29545379b268
+SHA512:
+  metadata.gz: 5f201d9a44db39000dc36081d9212e221e3e1ba69d4650dcdd929f9709a401cbb6de1412587344246ed736bec0da0e576b19daadc9d91cda5eb4a4d9924d00a8
+  data.tar.gz: 604dd071010fffc73639338b7f84eefa9328f7c574156cd52077f1d6f6ae9c6ebe0ff1360c2c80c29328659242547b3a3652f0165d926ac944ab1b1fcb025c41

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,206 @@
+# Schemurai
+
+A small, light-weight-dependency JSON Schema validator for Ruby supporting Draft 7,
+Draft 2019-09, and Draft 2020-12. It 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.
+
+```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.
+
+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.
+
+### Thread / Ractor native feature
+
+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" }
+  }
+)
+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.
+
+## 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
+```
+
+Run the linter with:
+
+```sh
+bundle exec rubocop
+```
+
+## AI Disclosure
+
+Large part of this work is generated by OpenAI Codex.

data/lib/schemurai/dialect.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Schemurai
+  module Internal
+    class Dialect
+      TYPE = 1
+      ENUM = 2
+      COMBINER = 4
+      NUMBER = 8
+      STRING = 16
+      ARRAY = 32
+      OBJECT = 64
+
+      Keyword = Data.define(:mask, :subschema_shape) do
+        def initialize(mask:, subschema_shape: nil)
+          super
+        end
+      end
+
+      class << self
+        def register(dialect, default: false)
+          registry[normalize_uri(dialect.uri)] = dialect
+          @default = dialect if default
+          dialect
+        end
+
+        def resolve(uri = nil)
+          return @default if uri.nil?
+
+          registry[normalize_uri(uri)]
+        end
+
+        private def registry
+          @registry ||= {}
+        end
+
+        private def normalize_uri(uri)
+          uri.to_s.delete_suffix("#")
+        end
+      end
+
+      attr_reader :name, :uri, :keywords
+
+      def initialize(name:, uri:, keywords:, ref_siblings:, format_assertion: false)
+        @name = name
+        @uri = uri
+        @keywords = keywords.freeze
+        @ref_siblings = ref_siblings
+        @format_assertion = format_assertion
+        freeze
+      end
+
+      def ref_siblings?
+        @ref_siblings
+      end
+
+      def format_assertion?
+        @format_assertion
+      end
+
+      def draft7?
+        name == :draft7
+      end
+
+      def draft2019?
+        name == :draft2019_09
+      end
+
+      def draft2020?
+        name == :draft2020_12
+      end
+
+      def keyword_mask(schema)
+        schema.each_key.reduce(0) do |mask, keyword|
+          mask | (keywords[keyword]&.mask || 0)
+        end
+      end
+
+      def each_subschema(schema)
+        return enum_for(__method__, schema) unless block_given?
+        return unless schema.is_a?(Hash)
+        return if schema.key?("$ref") && !ref_siblings?
+
+        schema.each do |keyword, value|
+          specification = keywords[keyword]
+          next unless specification&.subschema_shape
+
+          case specification.subschema_shape
+          when :single
+            yield value, [keyword] if schema?(value)
+          when :single_or_list
+            if value.is_a?(Array)
+              value.each_with_index { |child, index| yield child, [keyword, index] if schema?(child) }
+            elsif schema?(value)
+              yield value, [keyword]
+            end
+          when :list
+            Array(value).each_with_index { |child, index| yield child, [keyword, index] if schema?(child) }
+          when :map
+            value.each { |name, child| yield child, [keyword, name] if schema?(child) } if value.is_a?(Hash)
+          when :dependencies
+            if value.is_a?(Hash)
+              value.each do |name, child|
+                yield child, [keyword, name] if schema?(child)
+              end
+            end
+          end
+        end
+      end
+
+      private def schema?(value)
+        value == true || value == false || value.is_a?(Hash)
+      end
+    end
+  end
+
+  private_constant :Internal
+end

data/lib/schemurai/dialect_keywords.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "dialect"
+
+module Schemurai
+  module Internal
+    module DialectKeywords
+      COMMON = {
+        "type" => Dialect::Keyword.new(mask: Dialect::TYPE),
+        "enum" => Dialect::Keyword.new(mask: Dialect::ENUM),
+        "const" => Dialect::Keyword.new(mask: Dialect::ENUM),
+        "allOf" => Dialect::Keyword.new(mask: Dialect::COMBINER, subschema_shape: :list),
+        "anyOf" => Dialect::Keyword.new(mask: Dialect::COMBINER, subschema_shape: :list),
+        "oneOf" => Dialect::Keyword.new(mask: Dialect::COMBINER, subschema_shape: :list),
+        "not" => Dialect::Keyword.new(mask: Dialect::COMBINER, subschema_shape: :single),
+        "if" => Dialect::Keyword.new(mask: Dialect::COMBINER, subschema_shape: :single),
+        "then" => Dialect::Keyword.new(mask: 0, subschema_shape: :single),
+        "else" => Dialect::Keyword.new(mask: 0, subschema_shape: :single),
+        "maximum" => Dialect::Keyword.new(mask: Dialect::NUMBER),
+        "minimum" => Dialect::Keyword.new(mask: Dialect::NUMBER),
+        "exclusiveMaximum" => Dialect::Keyword.new(mask: Dialect::NUMBER),
+        "exclusiveMinimum" => Dialect::Keyword.new(mask: Dialect::NUMBER),
+        "multipleOf" => Dialect::Keyword.new(mask: Dialect::NUMBER),
+        "maxLength" => Dialect::Keyword.new(mask: Dialect::STRING),
+        "minLength" => Dialect::Keyword.new(mask: Dialect::STRING),
+        "pattern" => Dialect::Keyword.new(mask: Dialect::STRING),
+        "contentEncoding" => Dialect::Keyword.new(mask: Dialect::STRING),
+        "contentMediaType" => Dialect::Keyword.new(mask: Dialect::STRING),
+        "maxItems" => Dialect::Keyword.new(mask: Dialect::ARRAY),
+        "minItems" => Dialect::Keyword.new(mask: Dialect::ARRAY),
+        "uniqueItems" => Dialect::Keyword.new(mask: Dialect::ARRAY),
+        "contains" => Dialect::Keyword.new(mask: Dialect::ARRAY, subschema_shape: :single),
+        "maxProperties" => Dialect::Keyword.new(mask: Dialect::OBJECT),
+        "minProperties" => Dialect::Keyword.new(mask: Dialect::OBJECT),
+        "required" => Dialect::Keyword.new(mask: Dialect::OBJECT),
+        "properties" => Dialect::Keyword.new(mask: Dialect::OBJECT, subschema_shape: :map),
+        "patternProperties" => Dialect::Keyword.new(mask: Dialect::OBJECT, subschema_shape: :map),
+        "additionalProperties" => Dialect::Keyword.new(mask: Dialect::OBJECT, subschema_shape: :single),
+        "propertyNames" => Dialect::Keyword.new(mask: Dialect::OBJECT, subschema_shape: :single)
+      }.freeze
+
+      LEGACY = {
+        "dependencies" => Dialect::Keyword.new(mask: Dialect::OBJECT, subschema_shape: :dependencies),
+        "definitions" => Dialect::Keyword.new(mask: 0, subschema_shape: :map)
+      }.freeze
+
+      MODERN = {
+        "$defs" => Dialect::Keyword.new(mask: 0, subschema_shape: :map),
+        "$recursiveRef" => Dialect::Keyword.new(mask: Dialect::COMBINER),
+        "dependentSchemas" => Dialect::Keyword.new(mask: Dialect::OBJECT, subschema_shape: :map),
+        "dependentRequired" => Dialect::Keyword.new(mask: Dialect::OBJECT),
+        "minContains" => Dialect::Keyword.new(mask: Dialect::ARRAY),
+        "maxContains" => Dialect::Keyword.new(mask: Dialect::ARRAY),
+        "unevaluatedItems" => Dialect::Keyword.new(mask: Dialect::ARRAY, subschema_shape: :single),
+        "unevaluatedProperties" => Dialect::Keyword.new(mask: Dialect::OBJECT, subschema_shape: :single),
+        "contentSchema" => Dialect::Keyword.new(mask: Dialect::STRING, subschema_shape: :single)
+      }.freeze
+
+      private_constant :COMMON, :LEGACY, :MODERN
+
+      module_function def draft7
+        COMMON.merge(
+          LEGACY,
+          "items" => Dialect::Keyword.new(mask: Dialect::ARRAY, subschema_shape: :single_or_list),
+          "additionalItems" => Dialect::Keyword.new(mask: Dialect::ARRAY, subschema_shape: :single)
+        ).freeze
+      end
+
+      module_function def draft2019_09
+        COMMON.merge(
+          LEGACY,
+          MODERN,
+          "items" => Dialect::Keyword.new(mask: Dialect::ARRAY, subschema_shape: :single_or_list),
+          "additionalItems" => Dialect::Keyword.new(mask: Dialect::ARRAY, subschema_shape: :single)
+        ).freeze
+      end
+
+      module_function def draft2020_12
+        COMMON.merge(
+          LEGACY,
+          MODERN,
+          "$dynamicRef" => Dialect::Keyword.new(mask: Dialect::COMBINER),
+          "prefixItems" => Dialect::Keyword.new(mask: Dialect::ARRAY, subschema_shape: :list),
+          "items" => Dialect::Keyword.new(mask: Dialect::ARRAY, subschema_shape: :single)
+        ).freeze
+      end
+    end
+  end
+
+  private_constant :Internal
+end

data/lib/schemurai/dialects/draft2019_09.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../dialect_keywords"
+
+module Schemurai
+  module Internal
+    module Dialects
+      module Draft201909
+        META_SCHEMA_URI = "https://json-schema.org/draft/2019-09/schema"
+        KEYWORDS = DialectKeywords.draft2019_09
+
+        DIALECT = Dialect.new(
+          name: :draft2019_09,
+          uri: META_SCHEMA_URI,
+          keywords: KEYWORDS,
+          ref_siblings: true
+        )
+
+        Dialect.register(DIALECT)
+
+        private_constant :META_SCHEMA_URI, :KEYWORDS
+      end
+    end
+  end
+
+  private_constant :Internal
+end

data/lib/schemurai/dialects/draft2020_12.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../dialect_keywords"
+
+module Schemurai
+  module Internal
+    module Dialects
+      module Draft202012
+        META_SCHEMA_URI = "https://json-schema.org/draft/2020-12/schema"
+        KEYWORDS = DialectKeywords.draft2020_12
+
+        DIALECT = Dialect.new(
+          name: :draft2020_12,
+          uri: META_SCHEMA_URI,
+          keywords: KEYWORDS,
+          ref_siblings: true
+        )
+
+        Dialect.register(DIALECT)
+
+        private_constant :META_SCHEMA_URI, :KEYWORDS
+      end
+    end
+  end
+
+  private_constant :Internal
+end

data/lib/schemurai/dialects/draft7.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../dialect_keywords"
+
+module Schemurai
+  module Internal
+    module Dialects
+      module Draft7
+        META_SCHEMA_URI = "http://json-schema.org/draft-07/schema"
+        KEYWORDS = DialectKeywords.draft7
+
+        DIALECT = Dialect.new(
+          name: :draft7,
+          uri: META_SCHEMA_URI,
+          keywords: KEYWORDS,
+          ref_siblings: false
+        )
+
+        Dialect.register(DIALECT, default: true)
+
+        private_constant :META_SCHEMA_URI, :KEYWORDS
+      end
+    end
+  end
+
+  private_constant :Internal
+end

data/lib/schemurai/evaluation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Schemurai
+  # Internal result of evaluating one schema location. Draft 7 only needs the
+  # validity bit, but newer drafts also propagate the instance locations
+  # consumed by applicators for unevaluatedProperties and unevaluatedItems.
+  class Evaluation
+    EMPTY_LOCATIONS = [].freeze
+
+    attr_reader :evaluated_properties, :evaluated_items
+
+    def self.valid(evaluated_properties: EMPTY_LOCATIONS, evaluated_items: EMPTY_LOCATIONS)
+      if evaluated_properties.equal?(EMPTY_LOCATIONS) && evaluated_items.equal?(EMPTY_LOCATIONS)
+        return @valid ||= new(true, EMPTY_LOCATIONS, EMPTY_LOCATIONS)
+      end
+
+      new(true, evaluated_properties, evaluated_items)
+    end
+
+    def self.invalid
+      @invalid ||= new(false, EMPTY_LOCATIONS, EMPTY_LOCATIONS)
+    end
+
+    def initialize(valid, evaluated_properties, evaluated_items)
+      @valid = valid
+      @evaluated_properties = evaluated_properties.freeze
+      @evaluated_items = evaluated_items.freeze
+      freeze
+    end
+
+    def valid?
+      @valid
+    end
+
+    def merge(other)
+      return self.class.invalid unless valid? && other.valid?
+
+      self.class.valid(
+        evaluated_properties: (evaluated_properties | other.evaluated_properties),
+        evaluated_items: (evaluated_items | other.evaluated_items)
+      )
+    end
+  end
+
+  private_constant :Evaluation
+end