diff --git a/README.md b/README.md
index c624390ac1..d1e2b550b9 100644
--- a/README.md
+++ b/README.md
@@ -376,6 +376,23 @@ end
 Parameters can be nested using `group` or by calling `requires` or `optional` with a block.
 In the above example, this means `params[:media][:url]` is required along with `params[:id]`,
 and `params[:audio][:format]` is required only if `params[:audio]` is present.
+With a block, `group`, `requires` and `optional` accept an additional option `type` which can
+be either `Array` or `Hash`, and defaults to `Array`. Depending on the value, the nested
+parameters will be treated either as values of a hash or as values of hashes in an array.
+
+```ruby
+params do
+  optional :preferences, type: Array do
+    requires :key
+    requires :value
+  end
+
+  requires :name, type: Hash do
+    requires :first_name
+    requires :last_name
+  end
+end
+```
 
 ### Namespace Validation and Coercion
 
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000000..28a5ff7912
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,42 @@
+# Upgrading
+
+## upgrading to 0.6.2
+
+In grape <= 0.6.1, `group`, `optional` and `requires` with block accepted
+either an Array or a Hash.
+
+In grape 0.6.2, these have an additional `type` attribute which defaults
+to `Array`. This means that without a `type` attribute, these nested parameters
+will no longer accept a single hash, only an array (of hashes).
+
+```ruby
+params do
+  requires :id, type: Integer
+  group :name do
+    requires :first_name
+    requires :last_name
+  end
+end
+```
+
+Whereas in 0.6.1 this accepted the following json,
+
+```json
+  "id": 1,
+  "name": {
+    "first_name": "John",
+    "last_name" : "Doe"
+  }
+```
+
+it no longer does in 0.6.2. The params block should now read:
+
+```ruby
+params do
+  requires :id, type: Integer
+  requires :name, type: Hash do
+    requires :first_name
+    requires :last_name
+  end
+end
+```