schemacop 3.0.0.rc1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5caf1b6b11b5c690dc05694cab67e34fb6ecc326381f9d7b63b9c016b5249d9c
-  data.tar.gz: 8b819ad6e32dd2329bd20c0869c216c677b766a5d7374a49f6a9c146d0e743d5
+  metadata.gz: eb25d83997e507cf7bf5e905143584e01b543c296f74e190eae487fe1a8bfdc0
+  data.tar.gz: 896f9bc4e14ac0e59831eacd83ae2e5a691a53e377f0b4895790b3686c24c2db
 SHA512:
-  metadata.gz: 5db8ca31cdf29cea9744529fec11af70dc1c534dc970639931e3a9c287f3005cc578e2d7e9b0525ceefdbcb17d5f01d46d42c0a5b5868b62cabafe2779464ccc
-  data.tar.gz: a12d18800342da6d1d9fdc39bffbec18877872c0cffb62c9b4a41cbd8954b0915c68afeb0b9e03c7e3bdd21f5803fa57daa7deb9cfd49a14363b67586e4e2fc0
+  metadata.gz: 461b762ba18edeac632010db52d368978ead449c6de8a88f6b6883d0109cfa3ff3e8b9bf4c8f2780023b60624bfc80f6456a421a8044fdf4ed7b565d8779db5c
+  data.tar.gz: 693beb806323f0695fce4183ad65d65670d5cab8b76692d74b4a467e396a52540bbb4fa9b9c03bef9940a35c1f62a32fcd0e51ea435f450bc134b502ca5839df

data/.releaser_config

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

data/CHANGELOG.md

@@ -10,7 +10,47 @@
 ### Changes
 -->
 
-## 3.0.0.rc0
+## 3.0.0 (2021-02-08)
+
+* Setup Zeitwerk ignores for Rails applications
+
+* Read previous `3.0.0.rcX` entries for all changes included
+  in this stable release
+
+## 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

@@ -118,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. [Introduction](#Introduction)
-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)
-
-## Introduction
-
-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:
+
+  ```ruby
+  schema = Schemacop::Schema3.new do
+    int! :foo
+  end
+
+  schema.validate!(foo: 'bar')
+  # => Schemacop::Exceptions::ValidationError: /foo: Invalid type, expected "integer".
+  ```
 
-`Schemacop::Exceptions::ValidationError`
-`Schemacop::Exceptions::InvalidSchemaError`
+* `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"
+```
 
-* enum
-* title
-* description
-* examples
+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"}
+```
+
+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.
@@ -309,11 +402,11 @@ It consists of one or multiple values, which can be validated using arbitrary no
 
 #### 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.
+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
+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
@@ -353,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:
 
@@ -448,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
@@ -461,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
@@ -492,13 +587,14 @@ It consists of key-value-pairs that can be validated using arbitrary nodes.
 
 * `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. See below for more informations.
+  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.
@@ -523,11 +619,116 @@ schema = Schemacop::Schema3.new :hash do
 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!({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}
+```
+
+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:
+
+```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
+schema = Schemacop::Schema3.new :hash do
+  int! :foo
+end
+
+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}
+```
+
+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
+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,
@@ -543,8 +744,8 @@ schema = Schemacop::Schema3.new :hash do
 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!({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".
 ```
 
@@ -562,7 +763,7 @@ enable all of them by enabling the option `additional_properties`:
 schema = Schemacop::Schema3.new :hash, additional_properties: true
 
 schema.validate!({}) # => {}
-schema.validate!({foo: :bar, baz: 42}) # => {:foo=>:bar, :baz=>42}
+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
@@ -578,8 +779,8 @@ Schemacop::Schema3.new :hash do
   add :string
 end
 
-schema.validate!({id: 1})             # => {:id=>1}
-schema.validate!({id: 1, foo: 'bar'}) # => {:foo=>"bar", :id=>1}
+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".
 ```
 
@@ -589,12 +790,12 @@ 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.
-schema = Schemacop::Schema3.new :hash, 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]+$".
+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.
@@ -603,7 +804,7 @@ schema = Schemacop::Schema3.new :hash, additional_properties: true, property_nam
 end
 
 schema.validate!({})                # => {}
-schema.validate!({foo: [1, 2, 3]})  # => {:foo=>[1, 2, 3]}
+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".
 ```
@@ -627,7 +828,7 @@ schema = Schemacop::Schema3.new :hash do
 end
 
 schema.validate!({}) # => Schemacop::Exceptions::ValidationError: /name: Value must be given.
-schema.validate!({name: 'Joe Doe'}) # => {:name=>"Joe Doe"}
+schema.validate!({name: 'Joe Doe'}) # => {"name"=>"Joe Doe"}
 schema.validate!({
   name: 'Joe Doe',
   billing_address: 'Street 42'
@@ -646,7 +847,7 @@ schema.validate!({
   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"}
+# => {"name"=>"Joe Doe", "credit_card"=>"XXXX XXXX XXXX XXXX X", "billing_address"=>"Street 42", "phone_number"=>"000-000-00-00"}
 ```
 
 ### Object
@@ -654,10 +855,11 @@ schema.validate!({
 Type: `:object`\
 DSL: `obj`
 
-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.
+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.
 
 In the most basic form, this node will accept anything:
 
@@ -738,7 +940,7 @@ schema.validate!('foooo') # => Schemacop::Exceptions::ValidationError: /: Does n
 Type: `:any_of`\
 DSL: `any_of`
 
-Similar to the AllOf node, you can specify multiple schemas, for which the
+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
@@ -755,7 +957,7 @@ schema.validate!('foo') # => "foo"
 schema.validate!(42)    # => 42
 ```
 
-Please note that you need to specify at least one item in the AllOf node:
+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.
@@ -766,9 +968,9 @@ Schemacop::Schema3.new :any_of # => Schemacop::Exceptions::InvalidSchemaError: N
 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.
+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:
@@ -807,7 +1009,7 @@ schema.validate!(6) # => Schemacop::Exceptions::ValidationError: /: Matches 2 de
 Type: `:is_not`\
 DSL: `is_not`
 
-With the IsNot node, you can specify a schema which the given value must 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.
 
@@ -825,7 +1027,7 @@ schema.validate!(3)     # => Schemacop::Exceptions::ValidationError: /: Must not
 schema.validate!('foo') # => "foo"
 ```
 
-Note that a IsNot node needs exactly one item:
+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.
@@ -840,7 +1042,7 @@ Type: `reference`
 **Definition**
 DSL: `scm`
 
-Finally, with the Reference node, you can define schemas and then later reference
+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.
 
@@ -884,7 +1086,7 @@ 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`,
@@ -902,13 +1104,13 @@ schema = Schemacop::Schema3.new :array do
 end
 
 schema.validate!([])                                      # => []
-schema.validate!([{first_name: 'Joe', last_name: 'Doe'}]) # => [{:first_name=>"Joe", :last_name=>"Doe"}]
+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
+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.
@@ -932,7 +1134,7 @@ context.schema :PersonInfo do
 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
+# 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
@@ -940,7 +1142,7 @@ schema = Schemacop::Schema3.new :reference, path: :Person
 # 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}}
+  # => {"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
@@ -953,7 +1155,7 @@ other_context.schema :Person do
 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
+# 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.
@@ -961,7 +1163,7 @@ Schemacop.with_context other_context do
   #    /: Obsolete property "last_name".
   #    /: Obsolete property "info".
 
-  schema.validate!({nickname: 'J.'}) # => {:nickname=>"J."}
+  schema.validate!({nickname: 'J.'}) # => {"nickname"=>"J."}
 end
 ```
 
@@ -971,11 +1173,11 @@ 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.
+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 single file, and after loading the
+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
@@ -989,14 +1191,17 @@ local schemas > context schemas > global schemas
 
 Where:
 
-* local schemas: Defined by using the DSL method? `scm`
+* 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.
+In Rails applications, your schemas are automatically eager-loaded from the load
+path `'app/schemas'` when your application is started, unless your application
+is running in the `DEVELOPMENT` environment. In the `DEVELOPMENT` environment,
+schemas are loaded each time when they are used, and as such you can make changes
+to your external schemas without having to restart the server each time.
 
 After starting your application, you can reference them like normally defined
 reference schemas, with the name being relative to the load path.
@@ -1032,20 +1237,24 @@ schema = Schemacop::Schema3.new :hash do
 end
 
 schema.validate!({usr: {first_name: 'Joe', last_name: 'Doe'}})
-  # => {: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=>[]}}
+  # => {"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"}]}}
+  # => {"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:
+however you might need to eager load the schemas yourself:
 
 ```ruby
 Schemacop::V3::GlobalContext.eager_load!
-```
+```
+
+As mentioned before, you can also use the external schemas without having to
+eager-load them, but if you use the schemas multiple times, it might be better
+to eager-load them on start of your application / script.