elasticgraph-json_schema 0.18.0.4 → 0.18.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa5e24cb6adf6b25fc3ab3e27a715bdce089285056501efec8f7bb040d94a60a
-  data.tar.gz: b6660a98fcb18e49a167d38a4de9da3b40eee99a5ac1d95e4beef1fc03c126a0
+  metadata.gz: 75d827eef96aa25f4944df19b2c6b23df331104ade84a814283735ffe14a93a1
+  data.tar.gz: b0faf506b264d67129755d90fbf637c545cf0b681f794480e69dfb0c39768a9e
 SHA512:
-  metadata.gz: 87b39fb428e2ae601e992953378e318d5ef058594ab9c4e688d39f34e8986190220e13ee0f11f6fb800319203f13241f2aed7979cc38d3ffcc414b34e7f2954d
-  data.tar.gz: 1c94607203e598b563598dbc8aa7f56c2b55e4c24bc71ba2586bec33c1b4777ac522d95b4f2f161a9577e111cb79d67b05d828da7a44b5d7c24f296391d624f3
+  metadata.gz: b3e92ed760e08cc9c2e5b4a117110c8ff65725f711aa7a6c76920adbf5e7064e4fea04f58c106921e61abda5cf97ba50c76ce36cc051c9354233e032dee8f105
+  data.tar.gz: 8431eaa5c6d7080c6dfb6f7f1e8446642ea4cbcb5324911fef8377936f16bc38b0c21213abe5cd83a35d8f313b22b388ad352c1357e2fe0f73f75d872a61eea4

data/lib/elastic_graph/json_schema/meta_schema_validator.rb

@@ -12,14 +12,23 @@ require "elastic_graph/support/hash_util"
 require "json"
 
 module ElasticGraph
+  # Provides [JSON Schema](https://json-schema.org/) validation for ElasticGraph.
   module JSONSchema
-    # Provides a strict validator based on the JSON schema spec that a JSON schema document is valid.
+    # Provides a validator to validate a JSON schema definitions according to the JSON schema meta schema.
+    # The validator is configured to validate strictly, so that non-standard JSON schema properties are disallowed.
+    #
+    # @return [Validator]
+    # @see .elastic_graph_internal_meta_schema_validator
     def self.strict_meta_schema_validator
       @strict_meta_schema_validator ||= MetaSchemaLoader.load_strict_validator
     end
 
-    # Provides a validator that allows additional ElasticGraph metadata to be embedded
-    # in JSON schema for internal ElasticGraph use.
+    # Provides a validator to validate a JSON schema definition according to the JSON schema meta schema.
+    # The validator is configured to validate strictly, so that non-standard JSON schema properties are disallowed,
+    # except for internal ElasticGraph metadata properties.
+    #
+    # @return [Validator]
+    # @see .strict_meta_schema_validator
     def self.elastic_graph_internal_meta_schema_validator
       @elastic_graph_internal_meta_schema_validator ||= MetaSchemaLoader.load_strict_validator({
         "properties" => {
@@ -35,7 +44,11 @@ module ElasticGraph
       })
     end
 
+    # Responsible for building {Validator}s that can validate JSON schema definitions.
     module MetaSchemaLoader
+      # Builds a validator to validate a JSON schema definition according to the JSON schema meta schema.
+      #
+      # @param overrides [Hash<String, Object>] meta schema overrides
       def self.load_strict_validator(overrides = {})
         # Downloaded from: https://json-schema.org/draft-07/schema
         schema = ::JSON.parse(::File.read(::File.expand_path("../json_schema_draft_7_schema.json", __FILE__)))

data/lib/elastic_graph/json_schema/validator.rb

@@ -10,11 +10,32 @@ require "json"
 
 module ElasticGraph
   module JSONSchema
+    # Responsible for validating JSON data against the ElasticGraph JSON schema for a particular type.
+    #
+    # @!attribute [r] schema
+    #   @return [Hash<String, Object>] a JSON schema
+    # @!attribute [r] sanitize_pii
+    #   @return [Boolean] whether to omit data that may contain PII from error messages
     class Validator < ::Data.define(:schema, :sanitize_pii)
+      # Validates the given data against the JSON schema, returning true if the data is valid.
+      #
+      # @param data [Object] JSON data to validate
+      # @return [Boolean] true if the data is valid; false if it is invalid
+      #
+      # @see #validate
+      # @see #validate_with_error_message
       def valid?(data)
         schema.valid?(data)
       end
 
+      # Validates the given data against the JSON schema, returning an array of error objects for
+      # any validation errors.
+      #
+      # @param data [Object] JSON data to validate
+      # @return [Array<Hash<String, Object>>] validation errors; will be empty if `data` is valid
+      #
+      # @see #valid?
+      # @see #validate_with_error_message
       def validate(data)
         schema.validate(data).map do |error|
           # The schemas can be very large and make the output very noisy, hiding what matters. So we remove them here.
@@ -24,9 +45,16 @@ module ElasticGraph
         end
       end
 
-      # Validates the given data against the schema, returning an error message if it is invalid.
-      # The error message is suitable for throwing or logging, as we take care to ensure it contains
-      # no PII.
+      # Validates the given data against the JSON schema, returning an error message string if it is invalid.
+      # The error message is intended to be usable to include in a log message or a raised error.
+      #
+      # @param data [Object] JSON data to validate
+      # @return [nil, String] a validation error message, if the data is invalid
+      #
+      # @note The returned error message may contain PII unless {#sanitize_pii} has not been set.
+      #
+      # @see #valid?
+      # @see #validate
       def validate_with_error_message(data)
         errors = validate(data)
         return if errors.empty?

data/lib/elastic_graph/json_schema/validator_factory.rb

@@ -11,10 +11,14 @@ require "json_schemer"
 
 module ElasticGraph
   module JSONSchema
+    # Factory class responsible for creating {Validator}s for particular ElasticGraph types.
     class ValidatorFactory
       # @dynamic root_schema
+      # @private
       attr_reader :root_schema
 
+      # @param schema [Hash<String, Object>] the JSON schema for an entire ElasticGraph schema
+      # @param sanitize_pii [Boolean] whether to omit data that may contain PII from error messages
       def initialize(schema:, sanitize_pii:)
         @raw_schema = schema
         @root_schema = ::JSONSchemer.schema(
@@ -39,9 +43,6 @@ module ElasticGraph
 
         @sanitize_pii = sanitize_pii
         @validators_by_type_name = ::Hash.new do |hash, key|
-          # Create a copy of the schema with a ref to the type merged at the root.
-          # This ensures that any relative $ref paths will correctly resolve, while
-          # specifying the type we want to validate against using $ref.
           hash[key] = Validator.new(
             schema: root_schema.ref("#/$defs/#{key}"),
             sanitize_pii: sanitize_pii
@@ -49,12 +50,21 @@ module ElasticGraph
         end
       end
 
+      # Gets the {Validator} for a particular ElasticGraph type.
+      #
+      # @param type_name [String] name of an ElasticGraph type
+      # @return [Validator]
       def validator_for(type_name)
         @validators_by_type_name[type_name]
       end
 
-      # Changes the matcher to disallow additional properties. Property paths specified in
-      # `except` will be allowed.
+      # Returns a new factory configured to disallow unknown properties. By default, JSON schema
+      # allows unknown properties (they'll simply be ignored when validating a JSON document). It
+      # can be useful to validate more strictly, so that a document with properties not defined in
+      # the JSON schema gets validation errors.
+      #
+      # @param except [Array<String>] paths under which unknown properties should still be allowed
+      # @return [ValidatorFactory]
       def with_unknown_properties_disallowed(except: [])
         allow_paths = except.map { |p| p.split(".") }
         schema_copy = ::Marshal.load(::Marshal.dump(@raw_schema)) # deep copy so our mutations don't affect caller

metadata

@@ -1,14 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: elasticgraph-json_schema
 version: !ruby/object:Gem::Version
-  version: 0.18.0.4
+  version: 0.18.0.5
 platform: ruby
 authors:
 - Myron Marston
+- Ben VandenBos
+- Square Engineering
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-09-06 00:00:00.000000000 Z
+date: 2024-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop-factory_bot
@@ -176,14 +178,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.4
+        version: 0.18.0.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.4
+        version: 0.18.0.5
 - !ruby/object:Gem::Dependency
   name: json_schemer
   requirement: !ruby/object:Gem::Requirement