schemurai 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2b340649fb4d070d05390ec257487c1f37e45287ef16325f0cfe3e4fb10ae72
-  data.tar.gz: e9e93301abe43e21ff297b66a3d9cb4d43376c8ac2b80ee4e650c1705f5dbc99
+  metadata.gz: f1b157d6e772537cab2886ef6d89bd547992c7359b73a13a49b9d9cfcdcc9808
+  data.tar.gz: f0e8e28536c58c95cf1848db949dad8007df0c7a6550dd8b0fd76439841617cd
 SHA512:
-  metadata.gz: a134b68cc4c6a2fc991822d63f841e6bec085a1c33109aca32e75feebd4cd95ca28dad001835591b200515170aa44bbf2c32275a610b2f7acc878d41f8a46bab
-  data.tar.gz: f9fd8b9be4432b61d153be039e39e59b0749ada777e15ebbebf007c69d237d356f5b6feea1c790d8e51201e6bedda0cc26e0c533f499e49062e461f78fa03bd3
+  metadata.gz: b6f8206124aab29ae13908951efdd011e276ca347a75c0abf79da9fb3a9988f91a0a59b0ec559b85a88f01d5975b9ea251f9f14bb7aba634b7c8f3625c288167
+  data.tar.gz: 3fcd551c456cb81b53842c0736ae9e629676ca8c7c0e43017ee43991b00b995fde7a530f1c0cb38f81d5e7bb640b68a8ad8ad388934af73b06b4ef77c4e46a34

data/README.md

@@ -1,5 +1,9 @@
 # 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)
+
 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
@@ -116,6 +120,38 @@ 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

data/lib/schemurai/error_message.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Schemurai
+  module Internal
+    # Builds validation messages shared by every evaluator backend.
+    module ErrorMessage
+      module_function def false_schema = "value is not allowed by this schema"
+
+      module_function def type(expected, value)
+        expected = Array(expected).map { |name| name.inspect }.join(" or ")
+        "value has type #{json_type(value).inspect}, but must have type #{expected}"
+      end
+
+      module_function def enum = "value must equal one of the values defined by `enum`"
+      module_function def const = "value must equal the value defined by `const`"
+
+      module_function def numeric_limit(keyword, limit)
+        comparison = {
+          "maximum" => "less than or equal to",
+          "minimum" => "greater than or equal to",
+          "exclusiveMaximum" => "less than",
+          "exclusiveMinimum" => "greater than"
+        }.fetch(keyword)
+        "number must be #{comparison} #{display_number(limit)}"
+      end
+
+      module_function def multiple_of(divisor) = "number must be a multiple of #{display_number(divisor)}"
+
+      module_function def size(keyword, limit, actual)
+        subject, unit, comparison = {
+          "maxLength" => ["string", "characters", "at most"],
+          "minLength" => ["string", "characters", "at least"],
+          "maxItems" => ["array", "items", "at most"],
+          "minItems" => ["array", "items", "at least"],
+          "maxProperties" => ["object", "properties", "at most"],
+          "minProperties" => ["object", "properties", "at least"]
+        }.fetch(keyword)
+        unit = {"characters" => "character", "items" => "item", "properties" => "property"}.fetch(unit) if limit == 1
+        "#{subject} must contain #{comparison} #{limit} #{unit} (found #{actual})"
+      end
+
+      module_function def pattern(pattern) = "string must match pattern #{pattern.inspect}"
+      module_function def invalid_pattern(pattern) = "schema pattern #{pattern.inspect} is not a valid regular expression"
+      module_function def format(name) = "string must match the #{name} format"
+      module_function def content_encoding = "string must be valid base64"
+      module_function def content_media_type = "string must contain valid JSON"
+      module_function def unique_items = "array items must be unique"
+
+      module_function def contains(actual, minimum, maximum)
+        expected = if maximum.infinite?
+          "at least #{minimum}"
+        elsif minimum == maximum
+          "exactly #{minimum}"
+        elsif minimum.zero?
+          "at most #{maximum}"
+        else
+          "between #{minimum} and #{maximum}"
+        end
+        "array must contain #{expected} items matching `contains` (found #{actual})"
+      end
+
+      module_function def required(name) = "object is missing required property #{name.inspect}"
+
+      module_function def dependent_required(name, required_name)
+        "property #{required_name.inspect} is required when property #{name.inspect} is present"
+      end
+
+      module_function def any_of = "value must match at least one subschema"
+      module_function def one_of(matches) = "value must match exactly one subschema (matched #{matches})"
+      module_function def not = "value must not match the subschema"
+
+      module_function def json_type(value)
+        case value
+        when nil then "null"
+        when true, false then "boolean"
+        when Hash then "object"
+        when Array then "array"
+        when String then "string"
+        when Numeric
+          if value.is_a?(Complex)
+            value.class.name
+          elsif value.finite? && value.to_i == value
+            "integer"
+          else
+            "number"
+          end
+        else
+          value.class.name
+        end
+      end
+      private_class_method :json_type
+
+      module_function def display_number(value)
+        rational = value.is_a?(Rational) ? value : Rational(value.to_s)
+        return rational.numerator.to_s if rational.denominator == 1
+
+        rational.to_f.to_s
+      end
+      private_class_method :display_number
+    end
+  end
+end

data/lib/schemurai/evaluator.rb

@@ -3,6 +3,7 @@
 require "json"
 require "base64"
 require_relative "evaluation"
+require_relative "error_message"
 
 module Schemurai
   module Internal
@@ -333,7 +334,7 @@ module Schemurai
         schema = node.schema
         return Evaluation.valid if schema == true
         if schema == false
-          add_error("falseSchema", "boolean schema is false", append_keyword: false)
+          add_error("falseSchema", append_keyword: false) { ErrorMessage.false_schema }
           return Evaluation.invalid
         end
         return Evaluation.valid unless schema.is_a?(Hash)
@@ -442,15 +443,15 @@ module Schemurai
         types = Array(schema["type"])
         return if types.any? { |type| type?(value, type) }
 
-        add_error("type", "expected #{types.join(" or ")}")
+        add_error("type") { ErrorMessage.type(types, value) }
       end
 
       private def check_enum(schema, value)
         if schema.key?("enum") && !schema["enum"].any? { |candidate| json_equal?(candidate, value) }
-          add_error("enum", "value is not in enum")
+          add_error("enum") { ErrorMessage.enum }
         end
         if schema.key?("const") && !json_equal?(schema["const"], value)
-          add_error("const", "value does not equal const")
+          add_error("const") { ErrorMessage.const }
         end
       end
 
@@ -472,7 +473,7 @@ module Schemurai
             matches << result if result.valid?
           end
           if matches.empty?
-            add_error("anyOf", "no subschema matched")
+            add_error("anyOf") { ErrorMessage.any_of }
           else
             matches.each { |result| evaluation = evaluation.merge(result) }
           end
@@ -487,12 +488,12 @@ module Schemurai
           if matches.length == 1
             evaluation = evaluation.merge(matches.first)
           else
-            add_error("oneOf", "expected exactly one match, got #{matches.length}")
+            add_error("oneOf") { ErrorMessage.one_of(matches.length) }
           end
         end
 
         if schema.key?("not") && trial_at(node.child("not"), value, MISSING_SEGMENT, "not").valid?
-          add_error("not", "subschema matched")
+          add_error("not") { ErrorMessage.not }
         end
 
         if schema.key?("if")
@@ -516,14 +517,14 @@ module Schemurai
 
         divisor = decimal(schema["multipleOf"])
         valid = divisor.positive? && decimal(value).remainder(divisor).zero?
-        add_error("multipleOf", "number is not a multiple") unless valid
+        add_error("multipleOf") { ErrorMessage.multiple_of(schema["multipleOf"]) } unless valid
       end
 
       private def compare(schema, keyword, value)
         return unless schema.key?(keyword)
         return if yield(decimal(value), decimal(schema[keyword]))
 
-        add_error(keyword, "numeric limit was exceeded")
+        add_error(keyword) { ErrorMessage.numeric_limit(keyword, schema[keyword]) }
       end
 
       private def check_string(node, value)
@@ -534,14 +535,14 @@ module Schemurai
 
         if schema.key?("pattern")
           matched = ecma_regexp(schema["pattern"]).match?(value)
-          add_error("pattern", "string does not match pattern") unless matched
+          add_error("pattern") { ErrorMessage.pattern(schema["pattern"]) } unless matched
         end
         if format_asserted?(node)
-          add_error("format", "string is not a valid #{node.format.name}") unless node.format.call(value)
+          add_error("format") { ErrorMessage.format(node.format.name) } unless node.format.call(value)
         end
         check_content(schema, value) if @validate_content
       rescue RegexpError
-        add_error("pattern", "invalid regular expression")
+        add_error("pattern") { ErrorMessage.invalid_pattern(schema["pattern"]) }
       end
 
       private def format_asserted?(node)
@@ -558,7 +559,7 @@ module Schemurai
           duplicate = value.each_with_index.any? do |item, index|
             value[0...index].any? { |previous| json_equal?(previous, item) }
           end
-          add_error("uniqueItems", "array items are not unique") if duplicate
+          add_error("uniqueItems") { ErrorMessage.unique_items } if duplicate
         end
 
         prefix_items = schema["prefixItems"]
@@ -600,7 +601,7 @@ module Schemurai
           minimum = schema.fetch("minContains", 1)
           maximum = schema.fetch("maxContains", Float::INFINITY)
           unless matched.length.between?(minimum, maximum)
-            add_error("contains", "matched #{matched.length} array items")
+            add_error("contains") { ErrorMessage.contains(matched.length, minimum, maximum) }
           end
           evaluated.concat(matched)
         end
@@ -623,7 +624,7 @@ module Schemurai
         limit(schema, "minProperties", value.length) { |actual, expected| actual >= expected }
 
         Array(schema["required"]).each do |name|
-          add_error("required", "required property #{name.inspect} is missing") unless value.key?(name)
+          add_error("required") { ErrorMessage.required(name) } unless value.key?(name)
         end
 
         properties = schema.fetch("properties", {})
@@ -657,7 +658,7 @@ module Schemurai
           next unless value.key?(name)
           if dependency.is_a?(Array)
             dependency.each do |required_name|
-              add_error("dependencies", "property #{required_name.inspect} is required by #{name.inspect}") unless value.key?(required_name)
+              add_error("dependencies") { ErrorMessage.dependent_required(name, required_name) } unless value.key?(required_name)
             end
           else
             result = evaluate_at(node.child("dependencies", name), value, MISSING_SEGMENT, "dependencies", name)
@@ -669,7 +670,7 @@ module Schemurai
           next unless value.key?(name)
           required_names.each do |required_name|
             unless value.key?(required_name)
-              add_error("dependentRequired", "property #{required_name.inspect} is required by #{name.inspect}")
+              add_error("dependentRequired") { ErrorMessage.dependent_required(name, required_name) }
             end
           end
         end
@@ -707,7 +708,7 @@ module Schemurai
         return unless schema.key?(keyword)
         return if yield(actual, schema[keyword])
 
-        add_error(keyword, "size limit was exceeded")
+        add_error(keyword) { ErrorMessage.size(keyword, schema[keyword], actual) }
       end
 
       private def type?(value, type)
@@ -803,10 +804,12 @@ module Schemurai
         JSON.parse(decoded)
       rescue ArgumentError, JSON::ParserError
         keyword = (schema["contentEncoding"] == "base64") ? "contentEncoding" : "contentMediaType"
-        add_error(keyword, "string content is invalid")
+        add_error(keyword) do
+          (keyword == "contentEncoding") ? ErrorMessage.content_encoding : ErrorMessage.content_media_type
+        end
       end
 
-      private def add_error(keyword, message, append_keyword: true)
+      private def add_error(keyword, message = nil, append_keyword: true)
         @error_count += 1
         if @error_callback
           schema_keyword = append_keyword ? keyword : MISSING_SEGMENT
@@ -815,7 +818,7 @@ module Schemurai
               keyword: keyword,
               instance_path: pointer(@instance_path),
               schema_path: pointer(@schema_path, schema_keyword),
-              message: message
+              message: message || yield
             )
           )
         end

data/lib/schemurai/version.rb

@@ -2,5 +2,5 @@
 
 module Schemurai
   # The installed Schemurai version.
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

data/lib/schemurai/vm/evaluator.rb

@@ -3,6 +3,7 @@
 require "base64"
 require "json"
 require_relative "../evaluation"
+require_relative "../error_message"
 require_relative "compiler"
 
 module Schemurai
@@ -132,7 +133,7 @@ module Schemurai
           case opcode
           when :boolean
             if operand == false
-              add_error("falseSchema", "boolean schema is false", append_keyword: false)
+              add_error("falseSchema", append_keyword: false) { Internal::ErrorMessage.false_schema }
               evaluation = Evaluation.invalid
             end
           when :ref
@@ -142,25 +143,25 @@ module Schemurai
           when :dynamic_ref
             evaluation = evaluation.merge(evaluate_dynamic_ref(program, operand, instance))
           when :type_null
-            check_compiled_type("null", instance.nil?)
+            check_compiled_type("null", instance.nil?, instance)
           when :type_boolean
-            check_compiled_type("boolean", instance == true || instance == false)
+            check_compiled_type("boolean", instance == true || instance == false, instance)
           when :type_object
-            check_compiled_type("object", instance.is_a?(Hash))
+            check_compiled_type("object", instance.is_a?(Hash), instance)
           when :type_array
-            check_compiled_type("array", instance.is_a?(Array))
+            check_compiled_type("array", instance.is_a?(Array), instance)
           when :type_number
-            check_compiled_type("number", number?(instance))
+            check_compiled_type("number", number?(instance), instance)
           when :type_integer
-            check_compiled_type("integer", integer?(instance))
+            check_compiled_type("integer", integer?(instance), instance)
           when :type_string
-            check_compiled_type("string", instance.is_a?(String))
+            check_compiled_type("string", instance.is_a?(String), instance)
           when :types
             check_compiled_types(operand, instance)
           when :enum
-            add_error("enum", "value is not in enum") unless operand.any? { |candidate| json_equal?(candidate, instance) }
+            add_error("enum") { Internal::ErrorMessage.enum } unless operand.any? { |candidate| json_equal?(candidate, instance) }
           when :const
-            add_error("const", "value does not equal const") unless json_equal?(operand, instance)
+            add_error("const") { Internal::ErrorMessage.const } unless json_equal?(operand, instance)
           when :allOf, :anyOf, :oneOf, :not, :conditional
             evaluation = evaluation.merge(check_combiner(opcode, operand, instance))
           when :number
@@ -271,15 +272,15 @@ module Schemurai
         active[program.node.object_id] ||= {}
       end
 
-      private def check_compiled_type(name, valid)
-        add_error("type", "expected #{name}") unless valid
+      private def check_compiled_type(name, valid, value)
+        add_error("type") { Internal::ErrorMessage.type(name, value) } unless valid
       end
 
       private def check_compiled_types(rules, value)
         instance_mask = instance_type_mask(value, integer: (rules.mask & TYPE_INTEGER) != 0)
         return unless (rules.mask & instance_mask).zero?
 
-        add_error("type", "expected #{rules.names.join(" or ")}")
+        add_error("type") { Internal::ErrorMessage.type(rules.names, value) }
       end
 
       private def instance_type_mask(value, integer:)
@@ -314,22 +315,26 @@ module Schemurai
         mask = rules.mask
         actual = decimal(value)
         if (mask & MAXIMUM) != 0 && actual > rules.maximum
-          add_error("maximum", "numeric limit was exceeded")
+          add_error("maximum") { Internal::ErrorMessage.numeric_limit("maximum", rules.maximum) }
         end
         if (mask & MINIMUM) != 0 && actual < rules.minimum
-          add_error("minimum", "numeric limit was exceeded")
+          add_error("minimum") { Internal::ErrorMessage.numeric_limit("minimum", rules.minimum) }
         end
         if (mask & EXCLUSIVE_MAXIMUM) != 0 && actual >= rules.exclusive_maximum
-          add_error("exclusiveMaximum", "numeric limit was exceeded")
+          add_error("exclusiveMaximum") do
+            Internal::ErrorMessage.numeric_limit("exclusiveMaximum", rules.exclusive_maximum)
+          end
         end
         if (mask & EXCLUSIVE_MINIMUM) != 0 && actual <= rules.exclusive_minimum
-          add_error("exclusiveMinimum", "numeric limit was exceeded")
+          add_error("exclusiveMinimum") do
+            Internal::ErrorMessage.numeric_limit("exclusiveMinimum", rules.exclusive_minimum)
+          end
         end
         return if (mask & MULTIPLE_OF).zero?
 
         divisor = rules.multiple_of
         valid = divisor.positive? && actual.remainder(divisor).zero?
-        add_error("multipleOf", "number is not a multiple") unless valid
+        add_error("multipleOf") { Internal::ErrorMessage.multiple_of(divisor) } unless valid
       end
 
       private def valid_string?(rules, value)
@@ -350,20 +355,20 @@ module Schemurai
       private def check_string(rules, value)
         length = value.length
         if rules.has_max_length && length > rules.max_length
-          add_error("maxLength", "size limit was exceeded")
+          add_error("maxLength") { Internal::ErrorMessage.size("maxLength", rules.max_length, length) }
         end
         if rules.has_min_length && length < rules.min_length
-          add_error("minLength", "size limit was exceeded")
+          add_error("minLength") { Internal::ErrorMessage.size("minLength", rules.min_length, length) }
         end
         if rules.has_pattern && !ecma_regexp(rules.pattern).match?(value)
-          add_error("pattern", "string does not match pattern")
+          add_error("pattern") { Internal::ErrorMessage.pattern(rules.pattern) }
         end
         if format_asserted?(rules) && !rules.format.call(value)
-          add_error("format", "string is not a valid #{rules.format.name}")
+          add_error("format") { Internal::ErrorMessage.format(rules.format.name) }
         end
         check_content(rules, value) if @validate_content
       rescue RegexpError
-        add_error("pattern", "invalid regular expression")
+        add_error("pattern") { Internal::ErrorMessage.invalid_pattern(rules.pattern) }
       end
 
       private def format_asserted?(rules)
@@ -385,7 +390,9 @@ module Schemurai
         JSON.parse(decoded)
       rescue ArgumentError, JSON::ParserError
         keyword = rules.decode_base64 ? "contentEncoding" : "contentMediaType"
-        add_error(keyword, "string content is invalid")
+        add_error(keyword) do
+          (keyword == "contentEncoding") ? Internal::ErrorMessage.content_encoding : Internal::ErrorMessage.content_media_type
+        end
       end
 
       private def valid_array?(rules, value)
@@ -437,16 +444,16 @@ module Schemurai
       private def check_array(rules, value, prior_evaluation)
         evaluated = []
         if rules.has_max_items && value.length > rules.max_items
-          add_error("maxItems", "size limit was exceeded")
+          add_error("maxItems") { Internal::ErrorMessage.size("maxItems", rules.max_items, value.length) }
         end
         if rules.has_min_items && value.length < rules.min_items
-          add_error("minItems", "size limit was exceeded")
+          add_error("minItems") { Internal::ErrorMessage.size("minItems", rules.min_items, value.length) }
         end
         if rules.unique
           duplicate = value.each_with_index.any? do |item, index|
             value[0...index].any? { |previous| json_equal?(previous, item) }
           end
-          add_error("uniqueItems", "array items are not unique") if duplicate
+          add_error("uniqueItems") { Internal::ErrorMessage.unique_items } if duplicate
         end
 
         if (prefix_items = rules.prefix_items)
@@ -483,7 +490,9 @@ module Schemurai
             trial_at(contains, value[index], index, "contains").valid?
           end
           unless matched.length.between?(rules.min_contains, rules.max_contains)
-            add_error("contains", "matched #{matched.length} array items")
+            add_error("contains") do
+              Internal::ErrorMessage.contains(matched.length, rules.min_contains, rules.max_contains)
+            end
           end
           evaluated.concat(matched)
         end
@@ -548,14 +557,18 @@ module Schemurai
       private def check_object(rules, value, prior_evaluation)
         evaluated = []
         if rules.has_max_properties && value.length > rules.max_properties
-          add_error("maxProperties", "size limit was exceeded")
+          add_error("maxProperties") do
+            Internal::ErrorMessage.size("maxProperties", rules.max_properties, value.length)
+          end
         end
         if rules.has_min_properties && value.length < rules.min_properties
-          add_error("minProperties", "size limit was exceeded")
+          add_error("minProperties") do
+            Internal::ErrorMessage.size("minProperties", rules.min_properties, value.length)
+          end
         end
         if (required = rules.required)
           required.each do |name|
-            add_error("required", "required property #{name.inspect} is missing") unless value.key?(name)
+            add_error("required") { Internal::ErrorMessage.required(name) } unless value.key?(name)
           end
         end
 
@@ -588,7 +601,7 @@ module Schemurai
           if dependency.is_a?(Array)
             dependency.each do |required_name|
               unless value.key?(required_name)
-                add_error("dependencies", "property #{required_name.inspect} is required by #{name.inspect}")
+                add_error("dependencies") { Internal::ErrorMessage.dependent_required(name, required_name) }
               end
             end
           else
@@ -600,7 +613,7 @@ module Schemurai
           next unless value.key?(name)
           required_names.each do |required_name|
             unless value.key?(required_name)
-              add_error("dependentRequired", "property #{required_name.inspect} is required by #{name.inspect}")
+              add_error("dependentRequired") { Internal::ErrorMessage.dependent_required(name, required_name) }
             end
           end
         end
@@ -633,7 +646,7 @@ module Schemurai
             result if result.valid?
           end
           if matches.empty?
-            add_error("anyOf", "no subschema matched")
+            add_error("anyOf") { Internal::ErrorMessage.any_of }
           else
             matches.each { |result| evaluation = evaluation.merge(result) }
           end
@@ -645,10 +658,10 @@ module Schemurai
           if matches.length == 1
             evaluation = evaluation.merge(matches.first)
           else
-            add_error("oneOf", "expected exactly one match, got #{matches.length}")
+            add_error("oneOf") { Internal::ErrorMessage.one_of(matches.length) }
           end
         when :not
-          add_error("not", "subschema matched") if trial_at(operand, value, MISSING_SEGMENT, "not").valid?
+          add_error("not") { Internal::ErrorMessage.not } if trial_at(operand, value, MISSING_SEGMENT, "not").valid?
         when :conditional
           condition = trial_at(operand.condition, value, MISSING_SEGMENT, "if")
           evaluation = evaluation.merge(condition) if condition.valid?
@@ -694,7 +707,7 @@ module Schemurai
         @instance_path.pop unless instance_segment.equal?(MISSING_SEGMENT)
       end
 
-      private def add_error(keyword, message, append_keyword: true)
+      private def add_error(keyword, message = nil, append_keyword: true)
         @error_count += 1
         return false unless @errors
 
@@ -703,7 +716,7 @@ module Schemurai
           keyword: keyword,
           instance_path: pointer(@instance_path),
           schema_path: pointer(@schema_path, final_segment),
-          message: message
+          message: message || yield
         )
         false
       end

data/lib/schemurai.rb

@@ -34,10 +34,13 @@ module Schemurai
     end
   end
 
-  # Describes one failed JSON Schema assertion.
+  # Public value type describing one failed JSON Schema assertion.
   #
-  # +instance_path+ and +schema_path+ are JSON Pointers. An empty string points
-  # to the root instance or schema.
+  # +keyword+ identifies the failed keyword. +instance_path+ and +schema_path+
+  # are JSON Pointers; an empty string points to the root instance or schema.
+  # +message+ is a human-readable String. Its presence and type are public API,
+  # but its exact wording is not. Use +keyword+ and the paths for programmatic
+  # error handling.
   class ValidationError < Data.define(:keyword, :instance_path, :schema_path, :message)
     # Returns the error fields as a Hash.
     def to_h

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schemurai
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Kuya KOHARA (oakcask)
@@ -42,6 +42,7 @@ files:
 - lib/schemurai/dialects/draft2019_09.rb
 - lib/schemurai/dialects/draft2020_12.rb
 - lib/schemurai/dialects/draft7.rb
+- lib/schemurai/error_message.rb
 - lib/schemurai/evaluation.rb
 - lib/schemurai/evaluator.rb
 - lib/schemurai/formats.rb
@@ -61,7 +62,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/oakcask/schemurai
   source_code_uri: https://github.com/oakcask/schemurai/tree/main
-  documentation_uri: https://rubydoc.info/gems/schemurai/2.0.0
+  documentation_uri: https://rubydoc.info/gems/schemurai/2.1.0
   rubygems_mfa_required: 'true'
 rdoc_options:
 - "--main"