jddf 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b488c9c91ad6f8eed43e3295b1a7bfbce20985d3aee9217eb2c9defc5f737e8c
-  data.tar.gz: 42676f592a08589204ccbb03aa68118714c60c10b0415a0a194cee9b65a7e228
+  metadata.gz: c72fdc3f849585ccb396ce421b3a786ac80b82e6bd655687663f990324422f65
+  data.tar.gz: 4569216d22965df94997de1934c3e978b558f566607d62e6175102871f1338a5
 SHA512:
-  metadata.gz: c9a69812ceae8889294f9b6adc0848d14b7f66511145156af42a34fe7e9f1de5aa678b684372249d8cef6a643b48f4b7cc3c9b8a341f3d960bb449593785cf4c
-  data.tar.gz: 0e04a88ceac3add797277390fcffed2256229abef37f68cb0515291f85096ff9475a27c6372ec9c267c90976aabef96768cc550afa81e945ebffb8e5f3cc843b
+  metadata.gz: 6bc424c05db14b6a242b7d4d0c1e407f1fb20b5667724eaff7c97c9f971f07a0aa332c85faa7badc7bbe28fdbb72897eaf0d9cbdde950a331341cfe1c0d11fff
+  data.tar.gz: df9ec4d23c0d91075a386482063b0bc22a1d6722e33b790603a9788d67141aac45d64142b1d0b8bcdcb706a6a2b679dbd30a5b64a523979d8b2b3a67b55a8135

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jddf (0.2.0)
+    jddf (0.2.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -31,10 +31,15 @@ gem 'jddf'
 
 The two most important classes offered by the `JDDF` module are:
 
-* `Schema`, which represents a JDDF schema,
-* `Validator`, which can validate a `Schema` against any parsed JSON data, and
-* `ValidationError`, which represents a single validation problem with the
-  input. `Validator#validate` returns an array of these.
+* [`Schema`][schema], which represents a JDDF schema,
+* [`Validator`][validator], which can validate a `Schema` against any parsed
+  JSON data, and
+* [`ValidationError`][validation-error], which represents a single validation
+  problem with the input. `Validator#validate` returns an array of these.
+
+[schema]: https://www.rubydoc.info/github/jddf/jddf-ruby/master/JDDF/Schema
+[validator]: https://www.rubydoc.info/github/jddf/jddf-ruby/master/JDDF/Validator
+[validation-error]: https://www.rubydoc.info/github/jddf/jddf-ruby/master/JDDF/ValidationError
 
 Here's a working example:
 

data/lib/jddf.rb

@@ -4,6 +4,6 @@ require 'jddf/schema'
 require 'jddf/validator'
 require 'jddf/version'
 
-# JDDF asdf
+# Provides support for JSON Data Defintion Format ("JDDF").
 module JDDF
 end

data/lib/jddf/schema.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module JDDF
+  # The keywords that may appear on a JDDF schema.
+  #
+  # Each of these values correspond to an attribute available on {Schema}.
   SCHEMA_KEYWORDS = %i[
     definitions
     ref
@@ -14,11 +17,18 @@ module JDDF
     discriminator
   ].freeze
 
+  # The keywords that may appear on a JDDF schema discriminator object.
+  #
+  # Each of these values correspond to an attribute available on
+  # {Discriminator}.
   DISCRIMINATOR_KEYWORDS = %i[
     tag
     mapping
   ].freeze
 
+  # The values the +type+ keyword may take on in a JDDF schema.
+  #
+  # The +type+ attribute of {Schema} has one of these values.
   TYPES = %i[
     boolean
     int8
@@ -33,7 +43,28 @@ module JDDF
     timestamp
   ].freeze
 
+  # A JDDF schema.
+  #
+  # This class is a +Struct+. Validate instances against it using
+  # {Validator#validate}.
+  #
+  # This class's attributes are in {SCHEMA_KEYWORDS}.
   Schema = Struct.new(*SCHEMA_KEYWORDS) do
+    # Construct a {Schema} from parsed JSON.
+    #
+    # This function performs type checks to ensure the data is well-typed, but
+    # does not perform all the checks necesary to ensure data is a correct JDDF
+    # schema. Using this function in combination with {verify} ensures that a
+    # JDDF schema is guaranteed to be correct according to the spec.
+    #
+    # +hash+ should be the result of calling +JSON#parse+.
+    #
+    # @param hash [Hash] a JSON object representing a JDDF schema
+    #
+    # @raise [ArgumentError, TypeError] if the inputted hash is not a valid
+    #   schema
+    #
+    # @return [Schema] the parsed schema
     def self.from_json(hash)
       raise TypeError.new, 'hash must be a Hash' unless hash.is_a?(Hash)
 
@@ -133,6 +164,12 @@ module JDDF
       schema
     end
 
+    # Determine which of the eight forms this schema takes on.
+    #
+    # This function is well-defined only if the schema is a correct schema --
+    # i.e., you have called {verify} and no errors were raised.
+    #
+    # @return [Symbol] the form of the schema
     def form
       return :ref if ref
       return :type if type
@@ -145,7 +182,20 @@ module JDDF
       :empty
     end
 
-    def verify(root = self)
+    # Check that the schema represents a correct JDDF schema.
+    #
+    # To make it convenient to construct and verify a schema, this function
+    # returns +self+ if the schema is correct.
+    #
+    # @raise [ArgumentError] if the schema is incorrect
+    #
+    # @return [Schema] self
+    def verify(root = self, is_root = true)
+      if definitions
+        raise ArgumentError, 'non-root definitions' unless is_root
+        definitions.values.each { |schema| schema.verify(root, false) }
+      end
+
       empty = true
 
       if ref
@@ -173,7 +223,7 @@ module JDDF
 
         empty = false
 
-        elements.verify(root)
+        elements.verify(root, false)
       end
 
       if properties || optional_properties
@@ -181,8 +231,8 @@ module JDDF
 
         empty = false
 
-        properties&.values&.each { |schema| schema.verify(root) }
-        optional_properties&.values&.each { |schema| schema.verify(root) }
+        properties&.values&.each { |schema| schema.verify(root, false) }
+        optional_properties&.values&.each { |schema| schema.verify(root, false) }
       end
 
       if values
@@ -190,7 +240,7 @@ module JDDF
 
         empty = false
 
-        values.verify(root)
+        values.verify(root, false)
       end
 
       if properties && optional_properties
@@ -203,7 +253,7 @@ module JDDF
         raise ArgumentError, 'invalid form' unless empty
 
         discriminator.mapping.values.each do |schema|
-          schema.verify(root)
+          schema.verify(root, false)
 
           unless schema.form == :properties
             raise ArgumentError, 'mapping value not of properties form'
@@ -220,7 +270,16 @@ module JDDF
     end
   end
 
+  # A JDDF schema discriminator object.
+  #
+  # This class is a +Struct+. It is primarily a helper sub-structure of
+  # {Schema}.
+  #
+  # The attributes of this struct are in {DISCRIMINATOR_KEYWORDS}.
   Discriminator = Struct.new(*DISCRIMINATOR_KEYWORDS) do
+    # Construct a {Discriminator} from parsed JSON.
+    #
+    # This is primarily meant to be a helper method to {Schema#from_json}.
     def self.from_json(hash)
       raise TypeError, 'tag not String' unless hash['tag'].is_a?(String)
       raise TypeError, 'mapping not Hash' unless hash['mapping'].is_a?(Hash)

data/lib/jddf/validator.rb

@@ -3,17 +3,29 @@
 require 'time'
 
 module JDDF
-  # ValidationError
+  # A single JDDF validation error.
+  #
+  # Instances of this class are returned from {Validator#validate}.
+  #
+  # The attributes of this class are both arrays of strings. They represent JSON
+  # Pointers.
+  #
+  # @attr [Array] instance_path an array of strings pointing to the rejected
+  #   part of the input ("instance")
+  #
+  # @attr [Array] schema_path an array of strings pointing to the part of the
+  #   schema which rejected the instance
   ValidationError = Struct.new(:instance_path, :schema_path)
 
-  # MaxDepthExceededError
+  # MaxDepthExceededError is raised when the maximum depth of a {Validator} is
+  # exceeded.
   class MaxDepthExceededError < StandardError
     def initialize(msg = 'max depth exceeded while validating')
       super
     end
   end
 
-  # Validator
+  # Validates JSON instances against JDDF schemas.
   class Validator
     # MaxErrorsError
     class MaxErrorsError < StandardError
@@ -248,9 +260,43 @@ module JDDF
 
     private_constant :VM
 
+    # The maximum stack depth of references to follow when running {validate}.
+    #
+    # If this maximum depth is exceeded, such as if a schema passed to
+    # {validate} is defined cyclically, then {validate} throws a
+    # {MaxDepthExceededError}.
+    #
+    # By default, no maximum depth is enforced. The validator may overflow the
+    # stack if a schema is defined cyclically.
+    #
+    # @return [Integer] the maximum depth of references to follow when validating
     attr_accessor :max_depth
+
+    # The maximum number of errors to return when running {validate}.
+    #
+    # If this value is set to a number, then it's guaranteed that {validate}
+    # will return an array of size no greater than the value of this attribute.
+    #
+    # By default, no maximum errors is enforced. All validation errors are
+    # returned.
+    #
+    # @return [Integer] the maximum errors to return when validating
     attr_accessor :max_errors
 
+    # Validate a JDDF schema against a JSON instance.
+    #
+    # The precise rules of validation for this method are defined formally by
+    # the JDDF specification, and this method follows those rules exactly,
+    # assuming that +instance+ is the result of calling +JSON#parse+ using the
+    # standard library's +JSON+ module.
+    #
+    # @param schema [Schema] the schema to validate against
+    #
+    # @param instance [Object] the input ("instance") to validate
+    #
+    # @raise [MaxDepthExceededError} if {max_depth} is exceeded.
+    #
+    # @return [Array] an array of {ValidationError}
     def validate(schema, instance)
       vm = VM.new
       vm.max_depth = max_depth

data/lib/jddf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JDDF
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jddf
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Ulysse Carion
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-16 00:00:00.000000000 Z
+date: 2019-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler