diff --git a/README.md b/README.md
index 8364b5627b79d0e792eb98827c3955901fe364a3..7b64ec68254164b360a446165b6d41f5d94e725f 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,102 @@
-[![Build Status](https://travis-ci.org/pateketrueke/json-schema-faker.png?branch=master)](https://travis-ci.org/pateketrueke/json-schema-faker) [![Coverage Status](https://coveralls.io/repos/pateketrueke/json-schema-faker/badge.png?branch=master)](https://coveralls.io/r/pateketrueke/json-schema-faker?branch=master)
+Fake your schemas!
+==================
+
+[![Build Status](https://travis-ci.org/pateketrueke/json-schema-faker.png?branch=master)](https://travis-ci.org/pateketrueke/json-schema-faker) [![NPM version](https://badge.fury.io/js/json-schema-faker.png)](http://badge.fury.io/js/json-schema-faker)  [![Coverage Status](https://coveralls.io/repos/pateketrueke/json-schema-faker/badge.png?branch=master)](https://coveralls.io/r/pateketrueke/json-schema-faker?branch=master)
+
+```javascript
+var jsf = require('json-schema-faker');
+
+var schema = {
+  type: 'object',
+  properties: {
+    user: {
+      type: 'object',
+      properties: {
+        id: {
+          $ref: '#/definitions/positiveInt'
+        },
+        name: {
+          type: 'string',
+          faker: 'name.findName'
+        },
+        email: {
+          type: 'string',
+          format: 'email',
+          faker: 'internet.email'
+        }
+      },
+      required: ['id', 'name', 'email']
+    }
+  },
+  required: ['user'],
+  definitions: {
+    positiveInt: {
+      type: 'integer',
+      minimum: 0,
+      minimumExclusive: true
+    }
+  }
+};
+
+var sample = jsf(schema);
+
+console.log(sample.user.name);
+// output: John Doe
+```
+
+Supported keywords
+------------------
+
+- **$ref** — Resolve internal references only, and/or external if provided.
+- **required** — All required properties are guaranteed, if not can be omitted.
+- **pattern**
+- **format** — Core formats only: date-time, email, hostname, ipv4, ipv6 and uri.
+- **enum** — Returns any of these enumerated values.
+- **minLength/maxLength** — Applies length constraints to string values.
+- **minimum/maximum** — Applies constraints to numeric values.
+- **exclusiveMinimum/exclusiveMaximum** — Adds exclusivity for numeric values.
+- **multipleOf** — Multiply constraints for numeric values.
+- **items** — Support for subschema and fixed item values.
+- **minItems/maxItems** — Adds length constraints for array items.
+- **uniqueItems** — Applies uniqueness constraints for array items.
+- **additionalItems** — Partially supported (?)
+- **allOf/oneOf/anyOf** — Subschema combinators.
+- **properties** — Object properties to be generated.
+- **minProperties/maxProperties** — Adds length constraints for object properties.
+- **patternProperties** — RegExp-based object properties.
+- **additionalProperties** — Partially supported (?)
+- **dependencies** — Not supported yet (?)
+
+Faking values
+-------------
+
+In order to get human-friendly samples you can use the **faker** property on each subschema:
+
+```json
+{
+  "type": "string",
+  "faker": "internet.email"
+}
+```
+
+The above schema will invoke:
+
+```javascript
+require('faker').internet.email();
+```
+
+Not that **faker** property has higher precedence than **format**.
+
+Great, Why?
+-----------
+
+Actually, I've found some projects or services:
+
+- http://www.json-generator.com/
+- https://github.com/jonahkagan/schematic-ipsum
+- https://www.npmjs.org/package/json-schema-mock
+- https://github.com/thaume/json-schema-processor
+- https://github.com/andreineculau/json-schema-random
+- https://github.com/murgatroid99/json-schema-random-instance
+
+But are incomplete or has limited support for some keywords, so I decided to code this library.