README_V3.md in schemacop-3.0.0.rc0 vs README_V3.md in schemacop-3.0.0.rc1

@@ -3,11 +3,11 @@
 Please note that Schemacop v3 is still a work in progress, especially the documentation.
 
 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)
 5. [Nodes](#nodes)
     1. [String](#string)
@@ -24,11 +24,11 @@
     12. [IsNot](#isNot)
     13. [Reference](#reference)
 6. [Context](#context)
 7. [External schemas](#external-schemas)
 
-## Introcution
+## Introduction
 
 TODO: Write short section about using schemacop V3
 
 ## Validation
 
@@ -305,10 +305,46 @@
 * `unique_items`
   This option specifies wether the items in the array must all be distinct from
   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.
 The array nodes support either list validation, or tuple validation, depending on
 how you specify your array contents.
@@ -435,35 +471,36 @@
   add :one_of do
     int
     str
   end
 end
+
+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.
 ```
 
-#### Contains
-
-TODO: Describe `cont` DSL method
-
 ### Hash
 
 Type: `:hash`\
 DSL: `hsh`
 
 The hash type represents a ruby `Hash` or an `object` in JSON schema language.
 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.
 
 * `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.
 
 * `max_properties`
@@ -478,206 +515,537 @@
 It supports all type nodes, but requires the suffix `?` or `!` for each
 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
 
 In addition to standard properties, you can allow the hash to contain
 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
 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
 
 Using the DSL method `dep`, you can specifiy (non-nested) property dependencies:
 
 ```ruby
 # 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
   str? :phone_number
 
   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
+If you set the `strict` option to `false`, the check is done using `is_a?` instead of
+`instance_of?`, which also allows subclasses
 
-Type: `:object`\
-DSL: `obj`
-
 ### 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!
+```
\ No newline at end of file