schemacop 3.0.0.rc0 → 3.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5b9526bd5d67ae7a463ab9f5592fe0d23ae06090061b391f0e3f0e1cea5c6cd
-  data.tar.gz: d34ec2afccc0ddf874e4875babdbe3e733b5cd2b71cc85993920ca4d473e1e9c
+  metadata.gz: 5caf1b6b11b5c690dc05694cab67e34fb6ecc326381f9d7b63b9c016b5249d9c
+  data.tar.gz: 8b819ad6e32dd2329bd20c0869c216c677b766a5d7374a49f6a9c146d0e743d5
 SHA512:
-  metadata.gz: 8ebed3cb5eaf93f6f60f23231cfb3e88f49c00082641a3ba79531692c77802aa5e59eeb619a7f18c71cb23e8ea3438a5aef95c14769dd62dfd5f3b6d3fd50ec7
-  data.tar.gz: 184241911ffd97e75d4b9ecedc5d796b0b7269d63bff0b869e011011a382ab3f98ca75fbbdb25d507bab66dc9c0c56213df7212e49616210c15b94f1844f7cd7
+  metadata.gz: 5db8ca31cdf29cea9744529fec11af70dc1c534dc970639931e3a9c287f3005cc578e2d7e9b0525ceefdbcb17d5f01d46d42c0a5b5868b62cabafe2779464ccc
+  data.tar.gz: a12d18800342da6d1d9fdc39bffbec18877872c0cffb62c9b4a41cbd8954b0915c68afeb0b9e03c7e3bdd21f5803fa57daa7deb9cfd49a14363b67586e4e2fc0

data/.travis.yml

@@ -2,6 +2,7 @@ language: ruby
 rvm:
  - 2.6.2
  - 2.7.1
+ - 3.0.0
 script:
  - bundle install
  - bundle exec rake test

data/README.md

@@ -8,6 +8,16 @@ against schema definitions described by a simple DSL. It is also able to
 generate [JSON Schema](https://json-schema.org) compliant JSON output, i.e. for
 use in conjunction with [OpenAPI](https://swagger.io/specification/).
 
+## Compatibility
+
+Schemacop is tested with the following ruby versions:
+
+* 2.6.2
+* 2.7.1
+* 3.0.0
+
+For these versions, the automated CI tests are ran on travis. Other ruby versions might work, but stick to these versions for best results.
+
 ## Basic example
 
 ```ruby
@@ -84,11 +94,11 @@ actual JSON string.
 
 Schemacop will throw one of the following checked exceptions:
 
-* {Schemacop::Exceptions::InvalidSchemaError}
+* `Schemacop::Exceptions::InvalidSchemaError`
 
   This exception is thrown when the given schema definition format is invalid.
 
-* {Schemacop::Exceptions::ValidationError}
+* `Schemacop::Exceptions::ValidationError`
 
   This exception is thrown when the given data does not comply with the given
   schema definition.

data/README_V3.md

@@ -5,7 +5,7 @@ Please note that Schemacop v3 is still a work in progress, especially the docume
 Use at your own discretion.
 
 # Table of Contents
-1. [Introcution](#Introcution)
+1. [Introduction](#Introduction)
 2. [Validation](#validation)
 3. [Exceptions](#exceptions)
 4. [Generic Keywords](#generic-keywords)
@@ -26,7 +26,7 @@ Use at your own discretion.
 6. [Context](#context)
 7. [External schemas](#external-schemas)
 
-## Introcution
+## Introduction
 
 TODO: Write short section about using schemacop V3
 
@@ -307,6 +307,42 @@ It consists of one or multiple values, which can be validated using arbitrary no
   each other, or if there may be duplicate values. By default, this is false,
   i.e. duplicate values are allowed
 
+#### Contains
+
+The `array` node features the contains node, which you can use with the DSL
+method `cont`. With that DSL method, you can specify a schema which at least
+one item in the array needs to validate against.
+
+One usecase for example could be that you want an array of integers, from which
+at least one must be 5 or larger:
+
+```ruby
+schema = Schemacop::Schema3.new :array do
+  list :integer
+  cont :integer, minimum: 5
+end
+
+schema.validate!([])      # => Schemacop::Exceptions::ValidationError: /: At least one entry must match schema {"type"=>"integer", "minimum"=>5}.
+schema.validate!([1, 5])  # => [1, 5]
+schema.validate!(['foo']) # => Schemacop::Exceptions::ValidationError: /[0]: Invalid type, expected "integer". /: At least one entry must match schema {"type"=>"integer", "minimum"=>5}
+```
+
+You can also use it with the tuple validation (see below), e.g. if you want
+an array of 3 integers, from which at least one needs to be 5 or larger:
+
+```ruby
+schema = Schemacop::Schema3.new :array do
+  int
+  int
+  int
+  cont :integer, minimum: 5
+end
+
+schema.validate!([])        # => /: Array has 0 items but must have exactly 3. /: At least one entry must match schema {"type"=>"integer", "minimum"=>5}.
+schema.validate!([1, 2, 3]) # => Schemacop::Exceptions::ValidationError: /: At least one entry must match schema {"type"=>"integer", "minimum"=>5}.
+schema.validate!([1, 3, 5]) # => [1, 3, 5]
+```
+
 #### Specifying properties
 
 Array nodes support a block in which you can specify the required array contents.
@@ -437,11 +473,12 @@ schema = Schemacop::Schema3.new :array do
     str
   end
 end
-```
-
-#### Contains
 
-TODO: Describe `cont` DSL method
+schema.validate!([])          # => Schemacop::Exceptions::ValidationError: /: Array has 0 items but must have exactly 1.
+schema.validate!([1, 2])      # => [1, 2]
+schema.validate!([1, 'foo'])  # => [1, "foo"]
+schema.validate!([1, :bar])   # => Schemacop::Exceptions::ValidationError: /[1]: Matches 0 definitions but should match exactly 1.
+```
 
 ### Hash
 
@@ -453,7 +490,7 @@ It consists of key-value-pairs that can be validated using arbitrary nodes.
 
 #### Options
 
-* `additional_properties` TODO: Check this
+* `additional_properties`
   This option specifies whether additional, unspecified properties are allowed
   (`true`) or not (`false`). By default, this is `true` if no properties are
   specified and `false` if you have specified at least one property.
@@ -461,7 +498,7 @@ It consists of key-value-pairs that can be validated using arbitrary nodes.
 * `property_names`
   This option allows to specify a regexp pattern (as string) which validates the
   keys of any properties that are not specified in the hash. This option only
-  makes sense if `additional_properties` is enabled.
+  makes sense if `additional_properties` is enabled. See below for more informations.
 
 * `min_properties`
   Specifies the (inclusive) minimum number of properties a hash must contain.
@@ -480,28 +517,35 @@ property, which specifies whether a property is required (`!`) or optional
 (`?`).
 
 ```ruby
-str! :my_required_property
-int! :my_optional_property
+schema = Schemacop::Schema3.new :hash do
+  str! :foo # Is a required property
+  int? :bar # Is an optional property
+end
+
+schema.validate!({})                    # => Schemacop::Exceptions::ValidationError: /foo: Value must be given.
+schema.validate!({foo: 'str'})          # => {:foo=>"str"}
+schema.validate!({foo: 'str', bar: 42}) # => {:foo=>"str", :bar=>42}
+schema.validate!({bar: 42})             # => Schemacop::Exceptions::ValidationError: /foo: Value must be given.
 ```
 
 ##### Pattern properties
 
-In addition to symbols, property keys can also be a regular expression:
+In addition to symbols, property keys can also be a regular expression. Here,
+you may only use the optional `?` suffix for the property. This allows any
+property, which matches the type and the name of the property matches the
+regular expression.
 
 ```ruby
-Schemacop::Schema3.new do
-  str! :name
-
+schema = Schemacop::Schema3.new :hash do
   # The following statement allows any number of integer properties of which the
   # name starts with `id_`.
-  int! /^id_.*$/
+  int? /^id_.*$/
 end
-```
 
-For example, the above example would successfully validate the following hash:
-
-```ruby
-{ name: 'John Doe', id_a: 42, id_b: 42 }
+schema.validate!({})                      # => {}
+schema.validate!({id_foo: 1})             # => {:id_foo=>1}
+schema.validate!({id_foo: 1, id_bar: 2})  # => {:id_foo=>1, :id_bar=>2}
+schema.validate!({foo: 3})                # => Schemacop::Exceptions::ValidationError: /: Obsolete property "foo".
 ```
 
 ##### Additional properties & property names
@@ -511,19 +555,32 @@ additional, unspecified properties. By default, this is turned off if you have
 defined at least one standard property.
 
 When it comes to additional properties, you have the choice to either just
-enable all of them by enabling the option `additional_properties`. Using the DSL
-method `add` in the hash-node's body however, you can specify an additional
-schema to which additional properties must adhere:
+enable all of them by enabling the option `additional_properties`:
 
 ```ruby
-Schemacop::Schema3.new do
+# This schema will accept any additional properties
+schema = Schemacop::Schema3.new :hash, additional_properties: true
+
+schema.validate!({}) # => {}
+schema.validate!({foo: :bar, baz: 42}) # => {:foo=>:bar, :baz=>42}
+```
+
+Using the DSL method `add` in the hash-node's body however, you can specify
+an additional schema to which additional properties must adhere:
+
+
+```ruby
+Schemacop::Schema3.new :hash do
   int! :id
 
   # Allow any additional properties besides `id`, but their value must be a
-  # string. Note that using the `add` node, the option `additional_properties`
-  # is automatically enabled.
-  add :str
+  # string.
+  add :string
 end
+
+schema.validate!({id: 1})             # => {:id=>1}
+schema.validate!({id: 1, foo: 'bar'}) # => {:foo=>"bar", :id=>1}
+schema.validate!({id: 1, foo: 42})    # => Schemacop::Exceptions::ValidationError: /foo: Invalid type, expected "string".
 ```
 
 Using the option `property_names`, you can additionaly specify a pattern that
@@ -532,13 +589,23 @@ any additional property **keys** must adhere to:
 ```ruby
 # The following schema allows any number of properties, but all keys must
 # consist of downcase letters from a-z.
-Schemacop::Schema3.new additional_properties: :true, property_names: '^[a-z]+$'
+schema = Schemacop::Schema3.new :hash, additional_properties: :true, property_names: '^[a-z]+$'
+
+
+schema.validate!({})            # => {}
+schema.validate!({foo: 123})    # => {:foo=>123}
+schema.validate!({Foo: 'bar'})  # => Schemacop::Exceptions::ValidationError: /: Property name :Foo does not match "^[a-z]+$".
 
 # The following schema allows any number of properties, but all keys must
 # consist of downcase letters from a-z AND the properties must be arrays.
-Schemacop::Schema3.new additional_properties: :true, property_names: '^[a-z]+$' do
+schema = Schemacop::Schema3.new :hash, additional_properties: true, property_names: '^[a-z]+$' do
   add :array
 end
+
+schema.validate!({})                # => {}
+schema.validate!({foo: [1, 2, 3]})  # => {:foo=>[1, 2, 3]}
+schema.validate!({foo: :bar})       # => Schemacop::Exceptions::ValidationError: /foo: Invalid type, expected "array".
+schema.validate!({Foo: :bar})       # => Schemacop::Exceptions::ValidationError: /: Property name :Foo does not match "^[a-z]+$". /Foo: Invalid type, expected "array".
 ```
 
 ##### Dependencies
@@ -549,7 +616,7 @@ Using the DSL method `dep`, you can specifiy (non-nested) property dependencies:
 # In this example, `billing_address` and `phone_number` are required if
 # `credit_card` is given, and `credit_card` is required if `billing_address` is
 # given.
-Schemacop::Schema3.new do
+schema = Schemacop::Schema3.new :hash do
   str! :name
   str? :credit_card
   str? :billing_address
@@ -558,126 +625,427 @@ Schemacop::Schema3.new do
   dep :credit_card, :billing_address, :phone_number
   dep :billing_address, :credit_card
 end
+
+schema.validate!({}) # => Schemacop::Exceptions::ValidationError: /name: Value must be given.
+schema.validate!({name: 'Joe Doe'}) # => {:name=>"Joe Doe"}
+schema.validate!({
+  name: 'Joe Doe',
+  billing_address: 'Street 42'
+})
+# => Schemacop::Exceptions::ValidationError: /: Missing property "credit_card" because "billing_address" is given.
+
+schema.validate!({
+  name: 'Joe Doe',
+  credit_card: 'XXXX XXXX XXXX XXXX X'
+})
+# => Schemacop::Exceptions::ValidationError: /: Missing property "billing_address" because "credit_card" is given. /: Missing property "phone_number" because "credit_card" is given.
+
+schema.validate!({
+  name: 'Joe Doe',
+  billing_address: 'Street 42',
+  phone_number: '000-000-00-00',
+  credit_card: 'XXXX XXXX XXXX XXXX X'
+})
+# => {:name=>"Joe Doe", :credit_card=>"XXXX XXXX XXXX XXXX X", :billing_address=>"Street 42", :phone_number=>"000-000-00-00"}
 ```
 
-#### Examples
-```ruby
-schema = Schemacop::Schema3.new do
-  # Define built-in schema 'address' for re-use
-  scm :address do
-    str! :street
-    int! :number
-    str! :zip
-  end
+### Object
 
-  int? :id
-  str! :name
+Type: `:object`\
+DSL: `obj`
 
-  # Reference above defined schema 'address' and use it for key 'address'
-  ref! :address, :address
+The object type represents a ruby `Object`. Please note that the `as_json?  method
+on nodes of this type will just return `{}` (an empty JSON object), as there isn't
+a useful way to represent a ruby object without conflicting with the `Hash` type.
+If you want to represent an JSON object, you should use the `Hash` node.
 
-  # Reference above defined schema 'address' and use it as contents for array
-  # in key `additional_addresses`
-  ary! :additional_addresses, default: [] do
-    ref :address
-  end
-  ary? :comments, :array, default: [] { str }
+In the most basic form, this node will accept anything:
 
-  # Define a hash with key `jobs` that needs at least one property, and all
-  # properties must be valid integers and their values must be strings.
-  hsh! :jobs, min_properties: 1 do
-    str? /^[0-9]+$/
-  end
-end
+```ruby
+schema = Schemacop::Schema3.new :object
 
-schema.valid?(
-  id:      42,
-  name:    'John Doe',
-  address: {
-    street: 'Silver Street',
-    number: 4,
-    zip:    '38234C'
-  },
-  additional_addresses: [
-    { street: 'Example street', number: 42, zip: '8048' }
-  ],
-  comments: [
-    'This is a comment'
-  ],
-  jobs: {
-    2020 => 'Software Engineer'
-  }
-) # => true
+schema.validate!(nil)         # => nil
+schema.validate!(true)        # => true
+schema.validate!(false)       # => false
+schema.validate!(Object.new)  # => #<Object:0x0000556ab4f58dd0>
+schema.validate!('foo')       # => "foo"
 ```
 
+If you want to limit the allowed classes, you can so so by specifying an array
+of allowed classes:
+
 ```ruby
-# The following schema supports exactly the properties defined below, `options`
-# being a nested hash.
-Schemacop::Schema3.new do
-  int? :id         # Optional integer with key 'id'
-  str! :name       # Required string with name 'name'
-  hsh! :options do # Required hash with name `options`
-    boo! :enabled  # Required boolean with name `enabled`
-  end
-end
+schema = Schemacop::Schema3.new :object, classes: [String]
 
-# Allow any hash with any contents.
-Schemacop::Schema3.new(additional_properties: true)
+schema.validate!(nil)             # => nil
+schema.validate!(true)            # => Schemacop::Exceptions::ValidationError: /: Invalid type, expected "String".
+schema.validate!(Object.new)      # => Schemacop::Exceptions::ValidationError: /: Invalid type, expected "String".
+schema.validate!('foo')           # => "foo"
+schema.validate!('foo'.html_safe) # => Schemacop::Exceptions::ValidationError: /: Invalid type, expected "String".
+```
 
-# Allow a hash where `id` is given, but any additional properties of any name
-# and any type are supported as well.
-Schemacop::Schema3.new(additional_properties: true) do
-  int! :id
-end
+Here, the node checks if the given value is an instance of any of the given
+classes with `instance_of?`, i.e. the exact class and not a subclass.
 
-# Allow a hash where `id` is given, but any additional properties of which the
-# key starts with `k_` and of any value type are allowed.
-Schemacop::Schema3.new(additional_properties: true, property_names: '^k_.*$') do
-  int! :id
-end
+If you want to allow subclasses, you can specify this by using the `strict` option:
 
-# Allow a hash where `id` is given, but any additional properties of which the
-# key starts with `k_` and the additional value is a string are allowed.
-Schemacop::Schema3.new(additional_properties: true, property_names: '^k_.*$') do
-  int! :id
-  add :string
-end
+```ruby
+schema = Schemacop::Schema3.new :object, classes: [String], strict: false
 
-# Allow a hash where `id` is given, and any additional string properties that start
-# with `k_` are allowed. At least one string with key `k_*` must be given though
-# as this property is required.
-Schemacop::Schema3.new(property_names: '^k_.*$') do
-  int! :id
-  str! /^k_.*$/
-end
+schema.validate!(nil)             # => nil
+schema.validate!(true)            # => Schemacop::Exceptions::ValidationError: /: Invalid type, expected "String".
+schema.validate!(Object.new)      # => Schemacop::Exceptions::ValidationError: /: Invalid type, expected "String".
+schema.validate!('foo')           # => "foo"
+schema.validate!('foo'.html_safe) # => "foo"
 ```
 
-### Object
-
-Type: `:object`\
-DSL: `obj`
+If you set the `strict` option to `false`, the check is done using `is_a?` instead of
+`instance_of?`, which also allows subclasses
 
 ### AllOf
 
 Type: `:all_of`\
 DSL: `all_of`
 
+With the AllOf node you can specify multiple schemas, for which the given value
+needs to validate against every one:
+
+```ruby
+schema = Schemacop::Schema3.new :all_of do
+  str min_length: 2
+  str max_length: 4
+end
+
+schema.validate!('foo')   # => "foo"
+schema.validate!('foooo') # => Schemacop::Exceptions::ValidationError: /: Does not match all allOf conditions.
+```
+
+Please note that it's possible to create nonsensical schemas with this node, as
+you can combine multiple schemas which contradict each other:
+
+```ruby
+schema = Schemacop::Schema3.new :all_of do
+  str min_length: 4
+  str max_length: 1
+end
+
+schema.validate!('foo')   # => Schemacop::Exceptions::ValidationError: /: Does not match all allOf conditions.
+schema.validate!('foooo') # => Schemacop::Exceptions::ValidationError: /: Does not match all allOf conditions.
+```
+
 ### AnyOf
 
 Type: `:any_of`\
 DSL: `any_of`
 
+Similar to the AllOf node, you can specify multiple schemas, for which the
+given value needs to validate against at least one of the schemas.
+
+For example, your value needs to be either a string which is at least 2
+characters long, or an integer:
+
+```ruby
+schema = Schemacop::Schema3.new :any_of do
+  str min_length: 2
+  int
+end
+
+schema.validate!('f')   # => Schemacop::Exceptions::ValidationError: /: Does not match any anyOf condition.
+schema.validate!('foo') # => "foo"
+schema.validate!(42)    # => 42
+```
+
+Please note that you need to specify at least one item in the AllOf node:
+
+```ruby
+Schemacop::Schema3.new :any_of # => Schemacop::Exceptions::InvalidSchemaError: Node "any_of" makes only sense with at least 1 item.
+```
+
 ### OneOf
 
 Type: `:one_of`\
 DSL: `one_of`
 
+Similar to the AllOf node, you can specify multiple schemas, for which the
+given value needs to validate against at exaclty one of the schemas. If the
+given value validates against multiple schemas, the value is invalid.
+
+For example, if you want an integer which is either a multiple of 2 or 3,
+but not both (i.e. no multiple of 6), you could do it as follows:
+
+```ruby
+schema = Schemacop::Schema3.new :one_of do
+  int multiple_of: 2
+  int multiple_of: 3
+end
+
+schema.validate!(2) # => 2
+schema.validate!(3) # => 3
+schema.validate!(4) # => 4
+schema.validate!(5) # => Schemacop::Exceptions::ValidationError: /: Matches 0 definitions but should match exactly 1.
+schema.validate!(6) # => Schemacop::Exceptions::ValidationError: /: Matches 2 definitions but should match exactly 1.
+```
+
+Again, as previously with the AllOf node, you're allowed to create schemas
+which will not work for any input, e.g. by specifying the same schema twice:
+
+```ruby
+schema = Schemacop::Schema3.new :one_of do
+  int multiple_of: 2
+  int multiple_of: 2
+end
+
+schema.validate!(2) # => Schemacop::Exceptions::ValidationError: /: Matches 2 definitions but should match exactly 1.
+schema.validate!(3) # => Schemacop::Exceptions::ValidationError: /: Matches 0 definitions but should match exactly 1.
+schema.validate!(4) # => Schemacop::Exceptions::ValidationError: /: Matches 2 definitions but should match exactly 1.
+schema.validate!(5) # => Schemacop::Exceptions::ValidationError: /: Matches 0 definitions but should match exactly 1.
+schema.validate!(6) # => Schemacop::Exceptions::ValidationError: /: Matches 2 definitions but should match exactly 1.
+```
+
 ### IsNot
 
 Type: `:is_not`\
 DSL: `is_not`
 
+With the IsNot node, you can specify a schema which the given value must not
+validate against, i.e. every value which matches the schema will make this node
+invalid.
+
+For example, you want anything but the numbers between 3 and 5:
+
+```ruby
+schema = Schemacop::Schema3.new :is_not do
+  int minimum: 3, maximum: 5
+end
+
+schema.validate!(nil)   # => nil
+schema.validate!(1)     # => 1
+schema.validate!(2)     # => 2
+schema.validate!(3)     # => Schemacop::Exceptions::ValidationError: /: Must not match schema: {"type"=>"integer", "minimum"=>3, "maximum"=>5}.
+schema.validate!('foo') # => "foo"
+```
+
+Note that a IsNot node needs exactly one item:
+
+```ruby
+schema = Schemacop::Schema3.new :is_not # => Schemacop::Exceptions::InvalidSchemaError: Node "is_not" only allows exactly one item.
+```
+
 ### Reference
 
-DSL: `ref`
+**Referencing**
+DSL: `ref`\
+Type: `reference`
+
+**Definition**
+DSL: `scm`
+
+Finally, with the Reference node, you can define schemas and then later reference
+them for usage, e.g. when you have a rather long schema which you need at multiple
+places.
+
+#### Examples
+
+For example, let's define an object with an schema called `Address`, which we'll
+reference multiple times:
+
+```ruby
+schema = Schemacop::Schema3.new :hash do
+  scm :Address do
+    str! :street
+    str! :zip_code
+    str! :location
+    str! :country
+  end
+
+  ref! :shipping_address, :Address
+  ref! :billing_address, :Address
+end
+
+schema.validate!({}) # => Schemacop::Exceptions::ValidationError: /shipping_address: Value must be given. /billing_address: Value must be given.
+schema.validate!({
+  shipping_address: 'foo',
+  billing_address: 42
+})
+# => Schemacop::Exceptions::ValidationError: /shipping_address: Invalid type, expected "object". /billing_address: Invalid type, expected "object".
+
+schema.validate!({
+  shipping_address: {
+    street:   'Example Street 42',
+    zip_code: '12345',
+    location: 'London',
+    country:  'United Kingdom'
+  },
+  billing_address: {
+    street:   'Main St.',
+    zip_code: '54321',
+    location: 'Washington DC',
+    country:  'USA'
+  }
+})
+
+# => {:shipping_address=>{:street=>"Example Street 42", :zip_code=>"12345", :location=>"London", :country=>"United Kingdom"}, :billing_address=>{:street=>"Main St.", :zip_code=>"54321", :location=>"Washington DC", :country=>"USA"}}
+```
+
+Note that if you use the reference node with the long type name `reference`,
+e.g. in an array, you need to specify the "name" of the schema in the
+`path` option:
+
+```ruby
+schema = Schemacop::Schema3.new :array do
+  scm :User do
+    str! :first_name
+    str! :last_name
+  end
+
+  list :reference, path: :User
+end
+
+schema.validate!([])                                      # => []
+schema.validate!([{first_name: 'Joe', last_name: 'Doe'}]) # => [{:first_name=>"Joe", :last_name=>"Doe"}]
+schema.validate!([id: 42, first_name: 'Joe'])             # => Schemacop::Exceptions::ValidationError: /[0]/last_name: Value must be given. /[0]: Obsolete property "id".
+```
+
+## Context
+
+Schemacop als features the concept of a `Context`. You can define schemas in a
+context, and then reference them in other schemas in that context. This is e.g.
+useful if you need a part of the schema to be different depending on the
+business action.
+
+Examples:
+
+```ruby
+# Define a new context
+context = Schemacop::V3::Context.new
+
+# Define the :Person schema in that context
+context.schema :Person do
+  str! :first_name
+  str! :last_name
+  ref? :info, :PersonInfo
+end
+
+# And also define the :PersonInfo schema in that context
+context.schema :PersonInfo do
+  str! :born_at, format: :date
+end
+
+# Now we can define our general schema, where we reference the :Person schema.
+# Note that at this point, we don't know what's in the :Person sche,a
+schema = Schemacop::Schema3.new :reference, path: :Person
+
+# Validate the data in the context we defined before, where we need the first_name
+# and last_name of a person, as well as an optional info hash with the born_at date
+# of the person.
+Schemacop.with_context context do
+  schema.validate!({first_name: 'Joe', last_name: 'Doe', info: { born_at: '1980-01-01'} })
+  # => {:first_name=>"Joe", :last_name=>"Doe", :info=>{:born_at=>Tue, 01 Jan 1980}}
+end
+
+# Now we might want another context, where the person is more anonymous, and as
+# such, we need another schema
+other_context = Schemacop::V3::Context.new
+
+# Here, we only want the nickname of the person
+other_context.schema :Person do
+  str! :nickname
+end
+
+# Finally, validate the data in the new context. We do not want the real name or
+# birth date of the person, instead only the nickname is allowed
+Schemacop.with_context other_context do
+  schema.validate!({first_name: 'Joe', last_name: 'Doe', info: { born_at: '1980-01-01'} })
+  # => Schemacop::Exceptions::ValidationError: /nickname: Value must be given.
+  #    /: Obsolete property "first_name".
+  #    /: Obsolete property "last_name".
+  #    /: Obsolete property "info".
+
+  schema.validate!({nickname: 'J.'}) # => {:nickname=>"J."}
+end
+```
+
+As one can see, we validated the data against the same schema, but because we
+defined the referenced schemas differently in the two contexts, we were able
+to use other data in the second context than in the first.
+
+## External schemas
+
+Finally, schemacop features the possibilit to specify schemas in seperate files.
+This is especially useful is you have schemas in your application which are used
+multiple times through the application.
+
+For each schema, you define the schema in a single file, and after loading the
+schemas, you can reference them in other schemas.
+
+The default load path is `'app/schemas'`, but this can be configured by setting
+the value of the `load_paths` attribute of the `Schemacop` module.
+
+Please note that the following predescence order is used for the schemas:
+
+```
+local schemas > context schemas > global schemas
+```
+
+Where:
+
+* local schemas: Defined by using the DSL method? `scm`
+* context schemas: Defined in the current context using `context.schema`
+* global schemas: Defined in a ruby file in the load path
+
+### Rails applications
 
+In Rails applications, your schemas are automatically eager-laoded from the load
+path `'app/schemas'` when your application is started.
+
+After starting your application, you can reference them like normally defined
+reference schemas, with the name being relative to the load path.
+
+Example:
+
+You defined the following two schemas in the `'app/schemas'` directory:
+
+```ruby
+# app/schemas/user.rb
+schema :hash do
+  str! :first_name
+  str! :last_name
+  ary? :groups do
+    list :reference, path: 'nested/group'
+  end
+end
+```
+
+```ruby
+# app/schemas/nested/user.rb
+schema :hash do
+  str! :name
+end
+```
+
+To use the schema, you then can simply reference the schema as with normal
+reference schemas:
+
+```ruby
+schema = Schemacop::Schema3.new :hash do
+  ref! :usr, :user
+end
+
+schema.validate!({usr: {first_name: 'Joe', last_name: 'Doe'}})
+  # => {:usr=>{:first_name=>"Joe", :last_name=>"Doe"}}
+
+schema.validate!({usr: {first_name: 'Joe', last_name: 'Doe', groups: []}})
+  # => {:usr=>{:first_name=>"Joe", :last_name=>"Doe", :groups=>[]}}
+
+schema.validate!({usr: {first_name: 'Joe', last_name: 'Doe', groups: [{name: 'foo'}, {name: 'bar'}]}})
+  # => {:usr=>{:first_name=>"Joe", :last_name=>"Doe", :groups=>[{:name=>"foo"}, {:name=>"bar"}]}}
+```
+
+### Non-Rails applications
+
+Usage in non-Rails applications is the same as with usage in Rails applications,
+however you need to eager load the schemas yourself:
+
+```ruby
+Schemacop::V3::GlobalContext.eager_load!
+```

data/VERSION

@@ -1 +1 @@
-3.0.0.rc0
+3.0.0.rc1

data/lib/schemacop/schema2.rb

@@ -1,9 +1,9 @@
 module Schemacop
   class Schema2 < BaseSchema
-    def initialize(*args, &block)
+    def initialize(*args, **kwargs, &block)
       super()
       @root = V2::HashValidator.new do
-        req :root, *args, &block
+        req :root, *args, **kwargs, &block
       end
     end
 

data/lib/schemacop/scoped_env.rb

@@ -7,14 +7,14 @@ module Schemacop
       @prefix = prefix
     end
 
-    def method_missing(symbol, *args, &block)
+    def method_missing(symbol, *args, **kwargs, &block)
       symbol = :"#{@prefix}#{symbol}" if @prefix
 
       if @methods.include?(symbol)
         if @delegation_object.respond_to?(symbol)
-          @delegation_object.send(symbol, *args, &block)
+          @delegation_object.send(symbol, *args, **kwargs, &block)
         elsif @backup_binding.respond_to?(symbol)
-          @backup_binding.send(symbol, *args, &block)
+          @backup_binding.send(symbol, *args, **kwargs, &block)
         else
           super
         end

data/lib/schemacop/v2/node_supporting_field.rb

@@ -15,36 +15,50 @@ module Schemacop::V2
       exec_block(&block)
     end
 
-    def req?(*args, &block)
-      field(*args, required: true, allow_nil: true, &block)
+    def req?(*args, **kwargs, &block)
+      kwargs ||= {}
+      kwargs[:required] = true
+      kwargs[:allow_nil] = true
+      field(*args, **kwargs, &block)
     end
 
-    def req!(*args, &block)
-      field(*args, required: true, allow_nil: false, &block)
+    def req!(*args, **kwargs, &block)
+      kwargs ||= {}
+      kwargs[:required] = true
+      kwargs[:allow_nil] = false
+      field(*args, **kwargs, &block)
     end
 
     alias req req!
 
-    def opt?(*args, &block)
-      field(*args, required: false, allow_nil: true, &block)
+    def opt?(*args, **kwargs, &block)
+      kwargs ||= {}
+      kwargs[:required] = false
+      kwargs[:allow_nil] = true
+      field(*args, **kwargs, &block)
     end
 
-    def opt!(*args, &block)
-      field(*args, required: false, allow_nil: false, &block)
+    def opt!(*args, **kwargs, &block)
+      kwargs ||= {}
+      kwargs[:required] = false
+      kwargs[:allow_nil] = false
+      field(*args, **kwargs, &block)
     end
 
     alias opt opt?
 
     protected
 
-    def field(*args, required:, allow_nil:, &block)
+    def field(*args, **kwargs, &block)
       name = args.shift
+      required = kwargs.delete(:required)
+      allow_nil = kwargs.delete(:allow_nil)
 
       if @fields[name]
-        @fields[name].type(*args, &block)
+        @fields[name].type(*args, **kwargs, &block)
       elsif args.any?
         @fields[name] = FieldNode.new(name, required) do
-          type(*args, &block)
+          type(*args, **kwargs, &block)
         end
       else
         @fields[name] = FieldNode.new(name, required, &block)

data/lib/schemacop/v2/node_supporting_type.rb

@@ -33,7 +33,7 @@ module Schemacop::V2
       super
     rescue NoMethodError
       @types = []
-      type :hash, {}, &block
+      type :hash, &block
     end
 
     # required signature:
@@ -73,7 +73,7 @@ module Schemacop::V2
           end
 
           child = klass.new do
-            self.type(*subtypes, options, &block)
+            self.type(*subtypes, **options, &block)
           end
 
           # child = klass.build(options)

data/lib/schemacop/v3/hash_node.rb

@@ -35,7 +35,7 @@ module Schemacop
         @options[:additional_properties] = create(type, **options, &block)
       end
 
-      def dsl_dep(source, *targets)
+      def dsl_dep(source, *targets, **_kwargs)
         @options[:dependencies] ||= {}
         @options[:dependencies][source] = targets
       end
@@ -165,8 +165,14 @@ module Schemacop
         data ||= default
         return nil if data.nil?
 
-        # TODO: How to handle regex / etc.?
+        property_patterns = {}
+
         @properties.each_value do |prop|
+          if prop.name.is_a?(Regexp)
+            property_patterns[prop.name] = prop
+            next
+          end
+
           result[prop.name] = prop.cast(data[prop.name])
 
           if result[prop.name].nil? && !data.include?(prop.name)
@@ -174,6 +180,18 @@ module Schemacop
           end
         end
 
+        # Handle regex properties
+        specified_properties = @properties.keys.to_set
+        additional_properties = data.reject { |k, _v| specified_properties.include?(k.to_s.to_sym) }
+
+        if additional_properties.any? && property_patterns.any?
+          additional_properties.each do |name, additional_property|
+            match_key = property_patterns.keys.find { |p| p.match?(name.to_s) }
+            match = property_patterns[match_key]
+            result[name] = match.cast(additional_property)
+          end
+        end
+
         # Handle additional properties
         if options[:additional_properties] == true
           result = data.merge(result)
@@ -197,6 +215,9 @@ module Schemacop
       def init
         @properties = {}
         @options[:type] = :object
+        unless @options[:additional_properties].nil? || @options[:additional_properties].is_a?(TrueClass) || @options[:additional_properties].is_a?(FalseClass)
+          fail Schemacop::Exceptions::InvalidSchemaError, 'Option "additional_properties" must be a boolean value'
+        end
       end
 
       def validate_self

data/lib/schemacop/v3/node.rb

@@ -117,7 +117,7 @@ module Schemacop
         @schemas[name] = create(type, **options, &block)
       end
 
-      def dsl_node(node)
+      def dsl_node(node, *_args, **_kwargs)
         add_child node
       end
 

data/schemacop.gemspec

@@ -1,14 +1,14 @@
 # -*- encoding: utf-8 -*-
-# stub: schemacop 3.0.0.rc0 ruby lib
+# stub: schemacop 3.0.0.rc1 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "schemacop".freeze
-  s.version = "3.0.0.rc0"
+  s.version = "3.0.0.rc1"
 
   s.required_rubygems_version = Gem::Requirement.new("> 1.3.1".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Sitrox".freeze]
-  s.date = "2021-01-14"
+  s.date = "2021-01-22"
   s.files = [".gitignore".freeze, ".releaser_config".freeze, ".rubocop.yml".freeze, ".travis.yml".freeze, ".yardopts".freeze, "CHANGELOG.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "README_V2.md".freeze, "README_V3.md".freeze, "RUBY_VERSION".freeze, "Rakefile".freeze, "VERSION".freeze, "lib/schemacop.rb".freeze, "lib/schemacop/base_schema.rb".freeze, "lib/schemacop/exceptions.rb".freeze, "lib/schemacop/railtie.rb".freeze, "lib/schemacop/schema.rb".freeze, "lib/schemacop/schema2.rb".freeze, "lib/schemacop/schema3.rb".freeze, "lib/schemacop/scoped_env.rb".freeze, "lib/schemacop/v2.rb".freeze, "lib/schemacop/v2/caster.rb".freeze, "lib/schemacop/v2/collector.rb".freeze, "lib/schemacop/v2/dupper.rb".freeze, "lib/schemacop/v2/field_node.rb".freeze, "lib/schemacop/v2/node.rb".freeze, "lib/schemacop/v2/node_resolver.rb".freeze, "lib/schemacop/v2/node_supporting_field.rb".freeze, "lib/schemacop/v2/node_supporting_type.rb".freeze, "lib/schemacop/v2/node_with_block.rb".freeze, "lib/schemacop/v2/root_node.rb".freeze, "lib/schemacop/v2/validator/array_validator.rb".freeze, "lib/schemacop/v2/validator/boolean_validator.rb".freeze, "lib/schemacop/v2/validator/float_validator.rb".freeze, "lib/schemacop/v2/validator/hash_validator.rb".freeze, "lib/schemacop/v2/validator/integer_validator.rb".freeze, "lib/schemacop/v2/validator/nil_validator.rb".freeze, "lib/schemacop/v2/validator/number_validator.rb".freeze, "lib/schemacop/v2/validator/object_validator.rb".freeze, "lib/schemacop/v2/validator/string_validator.rb".freeze, "lib/schemacop/v2/validator/symbol_validator.rb".freeze, "lib/schemacop/v3.rb".freeze, "lib/schemacop/v3/all_of_node.rb".freeze, "lib/schemacop/v3/any_of_node.rb".freeze, "lib/schemacop/v3/array_node.rb".freeze, "lib/schemacop/v3/boolean_node.rb".freeze, "lib/schemacop/v3/combination_node.rb".freeze, "lib/schemacop/v3/context.rb".freeze, "lib/schemacop/v3/dsl_scope.rb".freeze, "lib/schemacop/v3/global_context.rb".freeze, "lib/schemacop/v3/hash_node.rb".freeze, "lib/schemacop/v3/integer_node.rb".freeze, "lib/schemacop/v3/is_not_node.rb".freeze, "lib/schemacop/v3/node.rb".freeze, "lib/schemacop/v3/node_registry.rb".freeze, "lib/schemacop/v3/number_node.rb".freeze, "lib/schemacop/v3/numeric_node.rb".freeze, "lib/schemacop/v3/object_node.rb".freeze, "lib/schemacop/v3/one_of_node.rb".freeze, "lib/schemacop/v3/reference_node.rb".freeze, "lib/schemacop/v3/result.rb".freeze, "lib/schemacop/v3/string_node.rb".freeze, "lib/schemacop/v3/symbol_node.rb".freeze, "schemacop.gemspec".freeze, "test/lib/test_helper.rb".freeze, "test/schemas/nested/group.rb".freeze, "test/schemas/user.rb".freeze, "test/unit/schemacop/v2/casting_test.rb".freeze, "test/unit/schemacop/v2/collector_test.rb".freeze, "test/unit/schemacop/v2/custom_check_test.rb".freeze, "test/unit/schemacop/v2/custom_if_test.rb".freeze, "test/unit/schemacop/v2/defaults_test.rb".freeze, "test/unit/schemacop/v2/empty_test.rb".freeze, "test/unit/schemacop/v2/nil_dis_allow_test.rb".freeze, "test/unit/schemacop/v2/node_resolver_test.rb".freeze, "test/unit/schemacop/v2/short_forms_test.rb".freeze, "test/unit/schemacop/v2/types_test.rb".freeze, "test/unit/schemacop/v2/validator_array_test.rb".freeze, "test/unit/schemacop/v2/validator_boolean_test.rb".freeze, "test/unit/schemacop/v2/validator_float_test.rb".freeze, "test/unit/schemacop/v2/validator_hash_test.rb".freeze, "test/unit/schemacop/v2/validator_integer_test.rb".freeze, "test/unit/schemacop/v2/validator_nil_test.rb".freeze, "test/unit/schemacop/v2/validator_number_test.rb".freeze, "test/unit/schemacop/v2/validator_object_test.rb".freeze, "test/unit/schemacop/v2/validator_string_test.rb".freeze, "test/unit/schemacop/v2/validator_symbol_test.rb".freeze, "test/unit/schemacop/v3/all_of_node_test.rb".freeze, "test/unit/schemacop/v3/any_of_node_test.rb".freeze, "test/unit/schemacop/v3/array_node_test.rb".freeze, "test/unit/schemacop/v3/boolean_node_test.rb".freeze, "test/unit/schemacop/v3/global_context_test.rb".freeze, "test/unit/schemacop/v3/hash_node_test.rb".freeze, "test/unit/schemacop/v3/integer_node_test.rb".freeze, "test/unit/schemacop/v3/is_not_node_test.rb".freeze, "test/unit/schemacop/v3/node_test.rb".freeze, "test/unit/schemacop/v3/number_node_test.rb".freeze, "test/unit/schemacop/v3/object_node_test.rb".freeze, "test/unit/schemacop/v3/one_of_node_test.rb".freeze, "test/unit/schemacop/v3/reference_node_test.rb".freeze, "test/unit/schemacop/v3/string_node_test.rb".freeze, "test/unit/schemacop/v3/symbol_node_test.rb".freeze]
   s.homepage = "https://github.com/sitrox/schemacop".freeze
   s.licenses = ["MIT".freeze]

data/test/unit/schemacop/v3/hash_node_test.rb

@@ -61,6 +61,7 @@ module Schemacop
         assert_validation({})
         assert_validation(foo: :bar)
         assert_validation('foo' => 'bar')
+        assert_validation(Foo: :bar)
         assert_validation('_foo39sjfdoi 345893(%' => 'bar', 'foo' => 'bar') do
           error '/', 'Property name "_foo39sjfdoi 345893(%" does not match "^[a-zA-Z0-9]+$".'
         end
@@ -70,6 +71,24 @@ module Schemacop
           additionalProperties: true,
           propertyNames:        '^[a-zA-Z0-9]+$'
         )
+
+        assert_cast({ foo: 123 }, { foo: 123 })
+        assert_cast({ Foo: 123 }, { Foo: 123 })
+
+        # New schema
+        schema :hash, additional_properties: true, property_names: '^[a-z]+$'
+
+        assert_validation({})
+        assert_validation(foo: :bar)
+        assert_validation('foo' => 'bar')
+        assert_validation(Foo: :bar) do
+          error '/', 'Property name :Foo does not match "^[a-z]+$".'
+        end
+        assert_validation('_foo39sjfdoi 345893(%' => 'bar', 'foo' => 'bar') do
+          error '/', 'Property name "_foo39sjfdoi 345893(%" does not match "^[a-z]+$".'
+        end
+
+        assert_cast({ foo: 123 }, { foo: 123 })
       end
 
       def test_required
@@ -254,6 +273,31 @@ module Schemacop
         )
       end
 
+      def test_pattern_properties_casting
+        schema do
+          int?(/^id_.*$/)
+          int?(/^val.*$/)
+        end
+
+        assert_json({
+                      type:                 :object,
+                      patternProperties:    {
+                        '^id_.*$': { type: :integer },
+                        '^val.*$': { type: :integer }
+                      },
+                      additionalProperties: false
+                    })
+
+        assert_validation({})
+        assert_validation({ id_foo: 1 })
+        assert_validation({ id_foo: 1, id_bar: 2 })
+        assert_validation({ id_foo: 1, id_bar: 2, value: 4 })
+
+        assert_cast({ id_foo: 1 }, { id_foo: 1 })
+        assert_cast({ id_foo: 1, id_bar: 2 }, { id_foo: 1, id_bar: 2 })
+        assert_cast({ id_foo: 1, id_bar: 2, value: 4 }, { id_foo: 1, id_bar: 2, value: 4 })
+      end
+
       def test_defaults
         schema do
           str? :first_name, default: 'John'
@@ -425,6 +469,13 @@ module Schemacop
         validate_self_should_error((4 + 6i))
         validate_self_should_error('13')
         validate_self_should_error('Lorem ipsum')
+
+        # rubocop:disable Lint/BooleanSymbol
+        assert_raises_with_message Exceptions::InvalidSchemaError,
+                                   'Option "additional_properties" must be a boolean value' do
+          schema :hash, additional_properties: :true
+        end
+        # rubocop:enable Lint/BooleanSymbol
       end
 
       def test_doc_example

data/test/unit/schemacop/v3/reference_node_test.rb

@@ -286,66 +286,66 @@ module Schemacop
         end
       end
 
-      # def test_external_schemas
-      #   context = Context.new
+      def test_external_schemas
+        context = Context.new
 
-      #   context.schema :Person do
-      #     str! :first_name
-      #     str! :last_name
-      #     ref? :info, :PersonInfo
-      #   end
+        context.schema :Person do
+          str! :first_name
+          str! :last_name
+          ref? :info, :PersonInfo
+        end
 
-      #   context.schema :PersonInfo do
-      #     str! :born_at, format: :date
-      #   end
+        context.schema :PersonInfo do
+          str! :born_at, format: :date
+        end
 
-      #   schema :reference, path: :Person
+        schema :reference, path: :Person
 
-      #   with_context context do
-      #     assert_validation(first_name: 'John', last_name: 'Doe')
-      #     assert_validation(first_name: 'John', last_name: 42) do
-      #       error '/last_name', 'Invalid type, expected "string".'
-      #     end
-      #   end
+        with_context context do
+          assert_validation(first_name: 'John', last_name: 'Doe')
+          assert_validation(first_name: 'John', last_name: 42) do
+            error '/last_name', 'Invalid type, expected "string".'
+          end
+        end
 
-      #   with_context context do
-      #     schema do
-      #       ref! :person, :Person
-      #     end
+        with_context context do
+          schema do
+            ref! :person, :Person
+          end
 
-      #     assert_validation(person: { first_name: 'John', last_name: 'Doe' })
-      #     assert_validation(person: { first_name: 'John', last_name: 'Doe', info: { born_at: '1990-01-13' } })
-      #     assert_validation(person: { first_name_x: 'John', last_name: 'Doe' }) do
-      #       error '/person', 'Obsolete property "first_name_x".'
-      #       error '/person/first_name', 'Value must be given.'
-      #     end
-      #     assert_validation(person: { first_name: 'John', last_name: 'Doe', info: { born_at: 'never' } }) do
-      #       error '/person/info/born_at', 'String does not match format "date".'
-      #     end
-      #   end
-      # end
+          assert_validation(person: { first_name: 'John', last_name: 'Doe' })
+          assert_validation(person: { first_name: 'John', last_name: 'Doe', info: { born_at: '1990-01-13' } })
+          assert_validation(person: { first_name_x: 'John', last_name: 'Doe' }) do
+            error '/person', 'Obsolete property "first_name_x".'
+            error '/person/first_name', 'Value must be given.'
+          end
+          assert_validation(person: { first_name: 'John', last_name: 'Doe', info: { born_at: 'never' } }) do
+            error '/person/info/born_at', 'String does not match format "date".'
+          end
+        end
+      end
 
-      # def test_defaults
-      #   schema do
-      #     scm :Person do
-      #       str? :foo, default: 'bar'
-      #     end
-      #     ref? :person, :Person, default: {}
-      #   end
+      def test_defaults
+        schema do
+          scm :Person do
+            str? :foo, default: 'bar'
+          end
+          ref? :person, :Person, default: {}
+        end
 
-      #   assert_cast({}, person: { foo: 'bar' })
-      # end
+        assert_cast({}, person: { foo: 'bar' })
+      end
 
-      # def test_casting
-      #   schema do
-      #     scm :Person do
-      #       str! :born_at, format: :date
-      #     end
-      #     ref? :person, :Person, default: {}
-      #   end
+      def test_casting
+        schema do
+          scm :Person do
+            str! :born_at, format: :date
+          end
+          ref? :person, :Person, default: {}
+        end
 
-      #   assert_cast({ person: { born_at: '1990-01-13' } }, person: { born_at: Date.new(1990, 1, 13) })
-      # end
+        assert_cast({ person: { born_at: '1990-01-13' } }, person: { born_at: Date.new(1990, 1, 13) })
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: schemacop
 version: !ruby/object:Gem::Version
-  version: 3.0.0.rc0
+  version: 3.0.0.rc1
 platform: ruby
 authors:
 - Sitrox
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-01-14 00:00:00.000000000 Z
+date: 2021-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport