schemacop 3.0.0.rc0 → 3.0.0.rc5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5b9526bd5d67ae7a463ab9f5592fe0d23ae06090061b391f0e3f0e1cea5c6cd
-  data.tar.gz: d34ec2afccc0ddf874e4875babdbe3e733b5cd2b71cc85993920ca4d473e1e9c
+  metadata.gz: 7fdf2a714534a94acf7c83e028fe7ce1e4b62c76266cc3e01786cd408d5c17c9
+  data.tar.gz: 21ba336e330bf881d4f99cb63c4070dea7559813d7387faa0a2ee53c85fdbb1e
 SHA512:
-  metadata.gz: 8ebed3cb5eaf93f6f60f23231cfb3e88f49c00082641a3ba79531692c77802aa5e59eeb619a7f18c71cb23e8ea3438a5aef95c14769dd62dfd5f3b6d3fd50ec7
-  data.tar.gz: 184241911ffd97e75d4b9ecedc5d796b0b7269d63bff0b869e011011a382ab3f98ca75fbbdb25d507bab66dc9c0c56213df7212e49616210c15b94f1844f7cd7
+  metadata.gz: 3636130ba0c0ee471e97e3ef9e259cc86840eaaf6b6435466fcaa17dafdb17aaff406b052e7e3eeffbbbb6e0f1fe3283feb5dda4dfcd5a008d3d60ee8c01f5bf
+  data.tar.gz: 46fa1c3b015cfa725e9c624f74fc16f0bf07c6db64e74282e12136c17dc664ae02edb128fe3110516728fab47c2fd105068fb2d9b318f617db39f82dc6264b64

data/.releaser_config

@@ -1,4 +1,3 @@
 version_file: VERSION
 always_from_master: true
-yard_path: doc
 gem_style: github

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/CHANGELOG.md

@@ -10,7 +10,40 @@
 ### Changes
 -->
 
-## 3.0.0.rc0
+## 3.0.0.rc5 (2021-02-05)
+
+* Use `ruby2_keywords` for compatibility with ruby `2.6.2`
+
+## 3.0.0.rc4 (2021-02-02)
+
+* Fix some minor bugs
+
+* Improve documentation
+
+* `used_external_schemas` for the `ReferenceNode` is now applied
+  recursively
+
+## 3.0.0.rc3 (2021-01-28)
+
+* Add minor improvements to the documentation
+
+* Internal restructuring, no changes in API
+
+## 3.0.0.rc2 (2021-01-28)
+
+* Represent node names as strings internally
+
+* Update documentation
+
+## 3.0.0.rc1 (2021-01-22)
+
+* Add support for ruby `3.0.0`
+
+* Add `ruby-3.0.0` to travis testing
+
+* Document all `v3` nodes
+
+## 3.0.0.rc0 (2021-01-14)
 
 * Add `Schemacop::Schema3`
 

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.
@@ -108,4 +118,4 @@ To run tests:
 
 ## Copyright
 
-Copyright (c) 2020 Sitrox. See `LICENSE` for further details.
+Copyright © 2016 - 2021 Sitrox. See `LICENSE` for further details.

data/README_V3.md

@@ -1,15 +1,11 @@
 # Schemacop schema V3
 
-Please note that Schemacop v3 is still a work in progress, especially the documentation.
+## Table of Contents
 
-Use at your own discretion.
-
-# Table of Contents
-1. [Introcution](#Introcution)
-2. [Validation](#validation)
-3. [Exceptions](#exceptions)
-4. [Generic Keywords](#generic-keywords)
-5. [Nodes](#nodes)
+1. [Validation](#validation)
+2. [Exceptions](#exceptions)
+3. [Generic Keywords](#generic-keywords)
+4. [Nodes](#nodes)
     1. [String](#string)
     2. [Integer](#integer)
     3. [Number](#number)
@@ -23,16 +19,12 @@ Use at your own discretion.
     11. [OneOf](#oneOf)
     12. [IsNot](#isNot)
     13. [Reference](#reference)
-6. [Context](#context)
-7. [External schemas](#external-schemas)
-
-## Introcution
-
-TODO: Write short section about using schemacop V3
+5. [Context](#context)
+6. [External schemas](#external-schemas)
 
 ## Validation
 
-Using schemacop, you can either choose to validate the data either using the
+Using Schemacop, you can either choose to validate your data either using the
 graceful `validate` method, or the bang variant, `validate!`.
 
 The `validate` method on a schema with some supplied data will return a
@@ -74,19 +66,120 @@ schema.validate!('Foo')         # => Schemacop::Exceptions::ValidationError: /:
 
 ## Exceptions
 
-TODO: Describe the exceptions raised by schemacop
+Schemacop can raise the following exceptions:
+
+* `Schemacop::Exceptions::ValidationError`: This exception is raised when the
+  `validate!` method is used, and the data that was passed in is invalid. The
+  exception message contains additional information why the validation failed.
+
+  Example:
 
-`Schemacop::Exceptions::ValidationError`
-`Schemacop::Exceptions::InvalidSchemaError`
+  ```ruby
+  schema = Schemacop::Schema3.new do
+    int! :foo
+  end
+
+  schema.validate!(foo: 'bar')
+  # => Schemacop::Exceptions::ValidationError: /foo: Invalid type, expected "integer".
+  ```
+
+* `Schemacop::Exceptions::InvalidSchemaError`: This exception is raised when the
+  schema itself is not valid. The exception message contains additional
+  information why the validation failed.
+
+  Example:
+
+  ```ruby
+  Schemacop::Schema3.new :hash do
+    int!
+  end
+
+  # => Schemacop::Exceptions::InvalidSchemaError: Child nodes must have a name.
+  ```
 
 ## Generic Keywords
 
-TODO: Complete this
+The nodes in Schemacop v3 also support generic keywords, similar to JSON schema:
+
+* `title`: Short string, should be self-explanatory
+* `description`: Description of the schema
+* `examples`: Here, you can provide examples which will be valid for the schema
+* `enum`: Here, you may enumerate values which will be valid, if the provided
+  value is not in the array, the validation will fail
+* `default`: You may provide a default value for items that will be set if the
+  value is not given
+
+The three keywords `title`, `description` and `examples` aren't used for validation,
+but can be used to document the schema. They will be included in the JSON output
+when you use the `as_json` method:
+
+```ruby
+schema = Schemacop::Schema3.new :hash do
+  str! :name, title: 'Name', description: 'Holds the name of the user', examples: ['Joe', 'Anna']
+end
+
+schema.as_json
+
+# => {"properties"=>{"name"=>{"type"=>"string", "title"=>"Name", "examples"=>["Joe", "Anna"], "description"=>"Holds the name of the user"}}, "additionalProperties"=>false, "required"=>["name"], "type"=>"object"}
+```
+
+The `enum` keyword can be used to only allow a subset of values:
+
+```ruby
+schema = Schemacop::Schema3.new :string, enum: ['foo', 'bar']
+
+schema.validate!('foo') # => "foo"
+schema.validate!('bar') # => "bar"
+schema.validate!('baz') # => Schemacop::Exceptions::ValidationError: /: Value not included in enum ["foo", "bar"].
+```
+
+Please note that you can also specify values in the enum that are not valid for
+the schema. This means that the validation will still fail:
+
+```ruby
+schema = Schemacop::Schema3.new :string, enum: ['foo', 'bar', 42]
+
+schema.validate!('foo') # => "foo"
+schema.validate!('bar') # => "bar"
+schema.validate!(42)    # => Schemacop::Exceptions::ValidationError: /: Invalid type, expected "string".
+```
+
+The enum will also be provided in the json output:
+
+```ruby
+schema = Schemacop::Schema3.new :string, enum: ['foo', 'bar']
+
+schema.as_json
+# => {"type"=>"string", "enum"=>["foo", "bar", 42]}
+```
+
+And finally, the `default` keyword lets you set a default value to use when no
+value is provided:
+
+```ruby
+schema = Schemacop::Schema3.new :string, default: 'Schemacop'
+
+schema.validate!('foo') # => "foo"
+schema.validate!(nil)   # => "Schemacop"
+```
+
+The default value will also be provided in the json output:
+
+```ruby
+schema = Schemacop::Schema3.new :string, default: 'Schemacop'
+
+schema.as_json
+# => {"type"=>"string", "default"=>"Schemacop"}
+```
 
-* enum
-* title
-* description
-* examples
+Note that the default value you use is also validated against the schema:
+
+```ruby
+schema = Schemacop::Schema3.new :string, default: 42
+
+schema.validate!('foo') # => "foo"
+schema.validate!(nil)   # => Schemacop::Exceptions::ValidationError: /: Invalid type, expected "string".
+```
 
 ## Nodes
 
@@ -102,9 +195,9 @@ transformed into various types.
 #### Options
 
 * `min_length`
-  Defines the minimum required string length
+  Defines the (inclusive) minimum required string length
 * `max_length`
-  Defines the maximum required string length
+  Defines the (inclusive) maximum required string length
 * `pattern`
   Defines a (ruby) regex pattern the value will be matched against. Must be a
   string and should generally start with `^` and end with `$` so as to evaluate
@@ -136,7 +229,7 @@ transformed into various types.
 
 * `boolean`
   The string must be either `true` or `false`. This value will be casted to
-  ruby's `TrueClass` or `FalseClass`.
+  Ruby's `TrueClass` or `FalseClass`.
 
 * `binary`
   The string is expected to contain binary contents. No casting or additional
@@ -287,7 +380,7 @@ schema.validate!(1234)    # => Schemacop::Exceptions::ValidationError: /: Invali
 ### Array
 
 Type: `:array`\
-DSL: `arr`
+DSL: `ary`
 
 The array type represents a ruby `Array`.
 It consists of one or multiple values, which can be validated using arbitrary nodes.
@@ -307,6 +400,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 use case 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.
@@ -317,9 +446,10 @@ how you specify your array contents.
 
 List validation validates a sequence of arbitrary length where each item matches
 the same schema. Unless you specify a `min_items` count on the array node, an
-empty array will also validate. To specify a list validation, use the `list`
-DSL method, and specify the type you want to validate against. Here, you need
-to specify the type of the element using the long `type` name (e.g. `integer` and not `int`).
+empty array will also suffice. To specify a list validation, use the `list` DSL
+method, and specify the type you want to validate against. Here, you need to
+specify the type of the element using the long `type` name (e.g. `integer` and
+not `int`).
 
 For example, you can specify that you want an array with only integers between 1 and 5:
 
@@ -412,8 +542,8 @@ schema.validate!([1, 'foo', 'bar']) # => Schemacop::Exceptions::ValidationError:
 schema.validate!([1, 'foo', 2, 3])  # => [1, "foo", 2, 3]
 ```
 
-Please note, that you cannot use multiple `add` in the same array schema, this will result in
-an exception:
+Please note that you cannot use multiple `add` in the same array schema, this
+will result in an exception:
 
 ```ruby
 schema = Schemacop::Schema3.new :array do
@@ -425,9 +555,10 @@ end
 # => Schemacop::Exceptions::InvalidSchemaError: You can only use "add" once to specify additional items.
 ```
 
-If you want to specify that your schema accept multiple additional types, use the `one_of`
-type (see below for more infos). The correct way to specify that you want to allow additional
-items, which may be an integer or a string is as follows:
+If you want to specify that your schema accept multiple additional types, use
+the `one_of` type (see below for more infos). The correct way to specify that
+you want to allow additional items, which may be an integer or a string is as
+follows:
 
 ```ruby
 schema = Schemacop::Schema3.new :array do
@@ -437,11 +568,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,15 +585,16 @@ 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.
+  (`true`) or not (`false`). By default, this is `false`, i.e. you need to
+  explicitly set it to `true` if you want to allow arbitrary additional properties,
+  or use the `add` DSL method (see below) to specify additional properties.
 
 * `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 information.
 
 * `min_properties`
   Specifies the (inclusive) minimum number of properties a hash must contain.
@@ -480,28 +613,140 @@ 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.
+```
+
+The name of the properties may either be a string or a symbol, and you can pass
+in the property either identified by a symbol or a string:
+
+The following two schemas are equal:
+
+```ruby
+schema = Schemacop::Schema3.new :hash do
+  int! :foo
+end
+
+schema.validate!(foo: 42)     # => {"foo"=>42}
+schema.validate!('foo' => 42) # => {"foo"=>42}
+
+schema = Schemacop::Schema3.new :hash do
+  int! 'foo'
+end
+
+schema.validate!(foo: 42)     # => {"foo"=>42}
+schema.validate!('foo' => 42) # => {"foo"=>42}
 ```
 
-##### Pattern properties
+The result in both cases will be a
+[HashWithIndifferentAccess](https://api.rubyonrails.org/classes/ActiveSupport/HashWithIndifferentAccess.html),
+which means that you can access the data in the hash with the symbol as well as
+the string representation:
 
-In addition to symbols, property keys can also be a regular expression:
+```ruby
+schema = Schemacop::Schema3.new :hash do
+  int! :foo
+end
+
+result = schema.validate!(foo: 42)
+
+result.class  # => ActiveSupport::HashWithIndifferentAccess
+result[:foo]  # => 42
+result['foo'] # 42
+```
+
+Please note that if you specify the value twice in the data you want to
+validate, once with the key being a symbol and once being a string, Schemacop
+will raise an error:
 
 ```ruby
-Schemacop::Schema3.new do
-  str! :name
+schema = Schemacop::Schema3.new :hash do
+  int! :foo
+end
 
-  # The following statement allows any number of integer properties of which the
-  # name starts with `id_`.
-  int! /^id_.*$/
+schema.validate!(foo: 42, 'foo' => 43) # => Schemacop::Exceptions::ValidationError: /: Has 1 ambiguous properties: [:foo].
+```
+
+In addition to the normal node options (which vary from type to type, check
+the respective nodes for details), properties also support the `as` option.
+
+With this, you can "rename" properties in the output:
+
+```ruby
+schema = Schemacop::Schema3.new :hash do
+  int! :foo, as: :bar
+end
+
+schema.validate!({foo: 42}) # => {"bar"=>42}
+```
+
+Please note that if you specify a node with the same property name multiple
+times, or use the `as` option to rename a node to the same name of another
+node, the last specified node will be used:
+
+```ruby
+schema = Schemacop::Schema3.new :hash do
+  int? :foo
+  str? :foo
+end
+
+schema.validate!({foo: 1})      # => Schemacop::Exceptions::ValidationError: /foo: Invalid type, expected "string".
+schema.validate!({foo: 'bar'})  # => {"foo"=>"bar"}
+```
+
+As well as:
+
+```ruby
+schema = Schemacop::Schema3.new :hash do
+  int? :foo
+  int? :bar, as: :foo
 end
+
+schema.validate!({foo: 1})          # => {"foo"=>1}
+schema.validate!({foo: 1, bar: 2})  # => {"foo"=>2}
+schema.validate!({bar: 2})          # => {"foo"=>2}
 ```
 
-For example, the above example would successfully validate the following hash:
+If you want to specify a node which may be one of multiple types, use the `one_of`
+node (see further down for more details):
 
 ```ruby
-{ name: 'John Doe', id_a: 42, id_b: 42 }
+schema = Schemacop::Schema3.new :hash do
+  one_of! :foo do
+    int
+    str
+  end
+end
+
+schema.validate!({foo: 1})      # => {"foo"=>1}
+schema.validate!({foo: 'bar'})  # => {"foo"=>"bar"}
+```
+
+##### Pattern properties
+
+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
+schema = Schemacop::Schema3.new :hash do
+  # The following statement allows any number of integer properties of which the
+  # name starts with `id_`.
+  int? /^id_.*$/
+end
+
+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 +756,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
+# 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 do
+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'}) # => {"id"=>1, "foo"=>"bar"}
+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 +790,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 +817,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 +826,428 @@ 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 a 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 `all_of` 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 `any_of` 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 `all_of` node, you can specify multiple schemas, for which the
+given value needs to validate against 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 `is_not` 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 `is_not` 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 also 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 schema.
+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 possibility to specify schemas in seperate
+files.  This is especially useful is you have schemas in your application which
+are used multiple times throughout the application.
+
+For each schema, you define the schema in a separate 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!
+```