jtd 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f28bef81d86fe4efad4f6e1398ce5b1d7d462de7e99590297b14a7a92bf2b40d
-  data.tar.gz: 8f25271a45816681d57d13dcb1cd8436cfc93d5a16aeadfa7a1946b199bc489f
+  metadata.gz: 1f3aced7e341c436f9e352366f0ac22b94ec9ee09eba6df47b02f29655615f74
+  data.tar.gz: 1e1c8bd6c424d1e73e91adcee30edf4bcbc833d49fb3a31fbac8b23e5901658b
 SHA512:
-  metadata.gz: 0bcc179000832d0d22833fec826df648f1b40d2cbc8610d138a479144260fedae3c507a28aa986ef9392be6a777f871607bf27bb99bbaee8486ca6f5538d7e55
-  data.tar.gz: 8749c6e7e26072097069e4977b7b817210a2f70815f4a6706d728ae4b629169429856eaa0c24ec11dcee171e196b4effcc1ce2185c9ae028eb6da24a2d5df9d6
+  metadata.gz: 752673b1192607e90d5b22b7f9c49fec8551d6dc95533b768aef1d5bf9125d07a9aa8789fc4db2a53db97817d47b8c77e80272632cc6d370b469694e702b5ff4
+  data.tar.gz: 619dcb81c6b5346a14e95d3ca316e2560c409059f39adb5660a12a40d8ca5251606c83983a201fe270d8d7f89fb5be8f9ef3aea7ecbf6c1ed62918369ee1101f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jtd (0.1.2)
+    jtd (0.1.3)
 
 GEM
   remote: https://rubygems.org/

data/lib/jtd.rb

@@ -2,5 +2,6 @@ require 'jtd/schema'
 require 'jtd/validate'
 require 'jtd/version'
 
+# JTD is an implementation of JSON Type Definition validation for Ruby.
 module JTD
 end

data/lib/jtd/schema.rb

@@ -1,4 +1,5 @@
 module JTD
+  # Represents a JSON Type Definition schema.
   class Schema
     attr_accessor *%i[
       metadata
@@ -16,6 +17,17 @@ module JTD
       mapping
     ]
 
+    # Constructs a Schema from a Hash like the kind produced by JSON#parse.
+    #
+    # In other words, #from_hash is meant to be used to convert some parsed JSON
+    # into a Schema.
+    #
+    # If hash isn't a Hash or contains keys that are illegal for JSON Type
+    # Definition, then #from_hash will raise a TypeError.
+    #
+    # If the properties of hash are not of the correct type for a JSON Type
+    # Definition schema (for example, if the "elements" property of hash is
+    # non-nil, but not a hash), then #from_hash may raise a NoMethodError.
     def self.from_hash(hash)
       # Raising this error early makes for a much clearer error for the
       # relatively common case of something that was expected to be an object
@@ -74,6 +86,20 @@ module JTD
       s
     end
 
+    # Raises a TypeError or ArgumentError if the Schema is not correct according
+    # to the JSON Type Definition specification.
+    #
+    # See the JSON Type Definition specification for more details, but a high
+    # level #verify checks such things as:
+    #
+    # 1. Making sure each of the attributes of the Schema are of the right type,
+    # 2. The Schema uses a valid combination of JSON Type Definition keywords,
+    # 3. The Schema isn't ambiguous or unsatisfiable.
+    # 4. The Schema doesn't make references to nonexistent definitions.
+    #
+    # If root is specified, then that root is assumed to contain the schema
+    # being verified. By default, the Schema is considered its own root, which
+    # is usually the desired behavior.
     def verify(root = self)
       self.check_type('metadata', [Hash])
       self.check_type('nullable', [TrueClass, FalseClass])
@@ -173,6 +199,13 @@ module JTD
       self
     end
 
+    # Returns the form that the schema takes on.
+    #
+    # The return value will be one of :empty, :ref:, :type, :enum, :elements,
+    # :properties, :values, or :discriminator.
+    #
+    # If the schema is not well-formed, i.e. calling #verify on it raises an
+    # error, then the return value of #form is not well-defined.
     def form
       return :ref if ref
       return :type if type

data/lib/jtd/validate.rb

@@ -1,6 +1,26 @@
 require 'time'
 
 module JTD
+  # Validates +instance+ against +schema+ according to the JSON Type Definition
+  # specification.
+  #
+  # Returns a list of ValidationError. If there are no validation errors, then
+  # the returned list will be empty.
+  #
+  # By default, all errors are returned, and an unlimited number of references
+  # will be followed. If you are running #validate against schemas that may
+  # return a lot of errors, or which may contain circular references, then this
+  # can cause performance issues or stack overflows.
+  #
+  # To mitigate this risk, consider using +options+, which must be an instance
+  # of ValidationOptions, to limit the number of errors returned or references
+  # followed.
+  #
+  # If ValidationOptions#max_depth is reached, then #validate will raise a
+  # MaxDepthExceededError.
+  #
+  # The return value of #validate is not well-defined if the schema is not
+  # valid, i.e. Schema#verify raises an error.
   def self.validate(schema, instance, options = ValidationOptions.new)
     state = ValidationState.new
     state.options = options
@@ -19,16 +39,64 @@ module JTD
     state.errors
   end
 
+  # Options you can pass to JTD::validate.
   class ValidationOptions
-    attr_accessor :max_depth, :max_errors
-
+    # The maximum number of references to follow before aborting validation. You
+    # can use this to prevent a stack overflow when validating schemas that
+    # potentially have infinite loops, such as this one:
+    #
+    #   {
+    #     "definitions": {
+    #       "loop": { "ref": "loop" }
+    #     },
+    #     "ref": "loop"
+    #   }
+    #
+    # The default value for +max_depth+ is 0, which indicates that no max depth
+    # should be imposed at all.
+    attr_accessor :max_depth
+
+    # The maximum number of errors to return. You can use this to have
+    # JTD::validate have better performance if you don't have any use for errors
+    # beyond a certain count.
+    #
+    # For instance, if all you care about is whether or not there are any
+    # validation errors at all, you can set +max_errors+ to 1. If you're
+    # presenting validation errors in an interface that can't show more than 5
+    # errors, set +max_errors+ to 5.
+    #
+    # The default value for +max_errors+ is 0, which indicates that all errors
+    # will be returned.
+    attr_accessor :max_errors
+
+    # Construct a new set of ValidationOptions with the given +max_depth+ and
+    # +max_errors+.
+    #
+    # See the documentation for +max_depth+ and +max_errors+ for what their
+    # default values of 0 mean.
     def initialize(max_depth: 0, max_errors: 0)
       @max_depth = max_depth
       @max_errors = max_errors
     end
   end
 
+  # Represents a single JSON Type Definition validation error.
+  #
+  # ValidationError does not extend StandardError; it is not a Ruby exception.
+  # It is a plain old Ruby object.
+  #
+  # Every ValidationError has two attributes:
+  #
+  # * +instance_path+ is an array of strings. It represents the path to the part
+  #   of the +instance+ passed to JTD::validate that was rejected.
+  #
+  # * +schema_path+ is an array of strings. It represents the path to the part
+  #   of the +schema+ passed to JTD::validate that rejected the instance at
+  #   +instance_path+.
   class ValidationError < Struct.new(:instance_path, :schema_path)
+
+    # Constructs a new ValidationError from the standard JSON representation of
+    # a validation error in JSON Type Definition.
     def self.from_hash(hash)
       instance_path = hash['instancePath']
       schema_path = hash['schemaPath']
@@ -37,7 +105,10 @@ module JTD
     end
   end
 
+  # Error raised from JTD::validate if the number of references followed exceeds
+  # ValidationOptions#max_depth.
   class MaxDepthExceededError < StandardError
+    # Constructs a new MaxDepthExceededError.
     def initialize(msg = 'max depth exceeded during JTD::validate')
       super
     end
@@ -45,7 +116,7 @@ module JTD
 
   private
 
-  class ValidationState
+  class ValidationState # :nodoc:
     attr_accessor :options, :root_schema, :instance_tokens, :schema_tokens, :errors
 
     def push_instance_token(token)
@@ -73,7 +144,7 @@ module JTD
 
   private_constant :ValidationState
 
-  class MaxErrorsReachedError < StandardError
+  class MaxErrorsReachedError < StandardError # :nodoc:
   end
 
   private_constant :MaxErrorsReachedError

data/lib/jtd/version.rb

@@ -1,3 +1,4 @@
 module JTD
-  VERSION = "0.1.2"
+  # The version of the +jtd+ gem you are using.
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jtd
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Ulysse Carion
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-09-19 00:00:00.000000000 Z
+date: 2020-09-20 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: