diff --git a/tutorials/8.2.x-to-3.x.md b/tutorials/8.2.x-to-3.x.md
new file mode 100644
index 0000000..2a95ae9
--- /dev/null
+++ b/tutorials/8.2.x-to-3.x.md
@@ -0,0 +1,78 @@
+The main reason behind the new major release is shift to `json-schema` model definitions as described by [json schema specification](http://json-schema.org/)  
+The `json-schema` support is provided by [Ajv](https://github.com/epoberezkin/ajv) library which comes with other features like extended validation support, dynamic defaults etc.. see `ajv` API for more details.  
+
+**Why?**  
+It allows model schemas to be further integrated with your REST APIs. Unified schema definitions throughout your service implementations make it easier for interfaces to be implemented and documentation to be auto-generated.  
+It reduces the complexity of your code by getting rid of the proprietary and somewhat limited schema format.  
+
+
+------------------------------------------------------------------------------------------------------------------------
+
+Note that in the time of `v3` release, `v3` includes numerous bugfixes which have not been backported to `v2`.  
+For full list of changes, please see the [CHANGELOG](https://github.com/fogine/couchbase-odm/blob/master/CHANGELOG.md)  
+
+The following is description of breaking changes:  
+
+
+All models` schemas must be update
+-----------------------
+From:
+
+```javascript
+{
+    type: DataType.HASH_TABLE,
+    schema: {
+        username: {
+            type: DataType.STRING,
+            allowEmptyValue: true
+        },
+        email: {
+            type: DataType.STRING
+        },
+        age: {
+            type: DataType.INT
+        },
+        apps: {
+            type: DataType.ARRAY,
+            allowEmptyValue: true,
+            schema: {
+                type: DataType.STRING
+            }
+        }
+    }
+}
+```
+
+To:
+
+```javascript
+{
+    type: 'object',
+    required: ['email', 'age'],
+    additionalProperties: false,
+    properties: {
+        username: {type: 'string'},
+        email: {
+            type: 'string',
+            format: 'email'
+        },
+        age: {type: 'integer'},
+        apps: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        }
+    }
+}
+```
+
+`modelInstance.update` method:
+------------------------------------
+The method behaves as one would expect, that is, its syntax sugar for `instance.setData()` followed by `instance.save()` ... with addition that when the operation fails, the instance data are restored to the previous state.  
+This also fixes the method design issue of `v2.x` which broke `beforeUpdate` & `afterUpdate` hooks for the `update` method.
+
+
+`modelInstance.sanitize` method:
+------------------------------------
+does not accept any options
diff --git a/tutorials/8.upgrade-guides.md b/tutorials/8.upgrade-guides.md
index 1bb8e89..f4e4a2e 100644
--- a/tutorials/8.upgrade-guides.md
+++ b/tutorials/8.upgrade-guides.md
@@ -1,4 +1,4 @@
 
 * {@tutorial 8.1.0-to-2.0}  
-
+* {@tutorial 8.2.x-to-3.x}  
 
diff --git a/tutorials/schema.json b/tutorials/schema.json
index 165d328..1361c6c 100644
--- a/tutorials/schema.json
+++ b/tutorials/schema.json
@@ -39,6 +39,9 @@
         "children": {
             "8.1.0-to-2.0": {
                 "title": "Upgrading from 1.0 to 2.0"
+            },
+            "8.2.x-to-3.x": {
+                "title": "Upgrading from 2.x to 3.x"
             }
         }
     }