From a2b84b2dd84a76bcad431ef720d217c40bc5c222 Mon Sep 17 00:00:00 2001
From: jos <wjosdejong@gmail.com>
Date: Tue, 12 Jan 2016 12:40:23 +0100
Subject: [PATCH] Updated readme, docs, added example

---
 README.md                               |  10 ++-
 docs/api.md                             | 114 +++++++++++++++++-------
 examples/01_basic_usage.html            |   3 +-
 examples/07_json_schema_validation.html |  67 ++++++++++++++
 test/test_schema.html                   |   4 +-
 5 files changed, 159 insertions(+), 39 deletions(-)
 create mode 100644 examples/07_json_schema_validation.html

diff --git a/README.md b/README.md
index 8aa4792..039dd3e 100644
--- a/README.md
+++ b/README.md
@@ -26,13 +26,14 @@ Supported browsers: Chrome, Firefox, Safari, Opera, Internet Explorer 9+.
 - Change type of values.
 - Sort arrays and objects.
 - Colorized code.
-- Search & highlight text in the treeview.
+- Search & highlight text in the tree view.
 - Undo and redo all actions.
+- JSON schema validation (powered by [ajv](https://github.com/epoberezkin/ajv)).
 
 ### Code editor
 - Format and compact JSON.
-- Colorized code (powered by Ace).
-- Inspect JSON (powered by Ace).
+- Colorized code (powered by [Ace](https://ace.c9.io)).
+- Inspect JSON (powered by [Ace](https://ace.c9.io)).
 
 ### Text editor
 - Format and compact JSON.
@@ -85,7 +86,8 @@ There is a directive available for using JSONEditor in Angular.js:
     <script>
         // create the editor
         var container = document.getElementById("jsoneditor");
-        var editor = new JSONEditor(container);
+        var options = {};
+        var editor = new JSONEditor(container, options);
 
         // set json
         var json = {
diff --git a/docs/api.md b/docs/api.md
index 0455820..1ac2f46 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -11,47 +11,97 @@ Constructs a new JSONEditor.
 *Parameters:*
 
 - `{Element} container`  
+
   An HTML DIV element. The JSONEditor will be created inside this container element.
-- `{Object} options`  
-  Optional object with options. Available options:
 
-  - `{Object} ace`  
-    Provide a custom version of the [Ace editor](http://ace.c9.io/) and use this instead of the version that comes embedded with JSONEditor. Only applicable when `mode` is `code`.
-  - `{function} onChange`  
-    Set a callback function triggered when the contents of the JSONEditor change. Called without parameters. Will only be triggered on changes made by the user, not in case of programmatic changes via the functions `set` or `setText`.
-  - `{function} onEditable`  
-    Set a callback function  to determine whether individual nodes are editable or read-only. Only applicable when option `mode` is `tree`. The callback is invoked as `editable(node)`, where `node` is an object `{field: string, value: string, path: string[]}`. The function must either return a boolean value to set both the nodes field and value editable or read-only, or return an object `{field: boolean, value: boolean}`.
-  - `{function} onError`  
-    Set a callback function triggered when an error occurs. Invoked with the error as first argument. The callback is only invoked
-    for errors triggered by a users action, like switching from code mode to tree mode or clicking the Format button whilst the editor doesn't contain valid JSON.
-  - `{function} onModeChange(newMode, oldMode)`  
-    Set a callback function triggered right after the mode is changed by the user. Only applicable when 
-    the mode can be changed by the user (i.e. when option `modes` is set).
-  - `{boolean} escapeUnicode`  
-    If true, unicode characters are escaped and displayed as their hexadecimal code (like `\u260E`) instead of of the character itself (like `☎`). False by default.
-  - `{boolean} history`  
-    Enables history, adds a button Undo and Redo to the menu of the JSONEditor. True by default. Only applicable when `mode` is 'tree' or 'form'.
-  - `{String} mode`  
-    Set the editor mode. Available values: 'tree' (default), 'view', 'form', 'code', 'text'. In 'view' mode, the data and datastructure is read-only. In 'form' mode, only the value can be changed, the datastructure is read-only. Mode 'code' requires the Ace editor to be loaded on the page. Mode 'text' shows the data as plain text.
-  - `{String[]} modes`  
-    Create a box in the editor menu where the user can switch between the specified modes. Available values: see option `mode`.
-  - `{String} name`  
-    Initial field name for the root node, is undefined by default. Can also be set using `JSONEditor.setName(name)`. Only applicable when `mode` is 'tree', 'view', or 'form'.
-  - `{boolean} search`  
-    Enables a search box in the upper right corner of the JSONEditor. True by default. Only applicable when `mode` is 'tree', 'view', or 'form'.
-  - `{Number} indentation`  
-    Number of indentation spaces. 2 by default. Only applicable when `mode` is 'code' or 'text'.
-  - `{String} theme`  
-    Set the Ace editor theme, uses included 'ace/theme/jsoneditor' by default. Please note that only the default theme is included with jsoneditor, so if you specify another one you need to make sure it is loaded.
+- `{Object} options`
 
-- `{JSON} json`  
+  Optional object with options. The available options are described under
+  [Configuration options](#configuration-options).
+
+- `{JSON} json`
   Initial JSON data to be loaded into the JSONEditor. Alternatively, the method `JSONEditor.set(json)` can be used to load JSON data into the editor.
 
 *Returns:*
 
-- `{JSONEditor} editor`  
+- `{JSONEditor} editor`
   New instance of a JSONEditor.
 
+### Configuration options
+
+- `{Object} ace`
+
+  Provide a custom version of the [Ace editor](http://ace.c9.io/) and use this instead of the version that comes embedded with JSONEditor. Only applicable when `mode` is `code`.
+
+- `{function} ajv`
+
+  Provide a custom instance of [ajv](https://github.com/epoberezkin/ajv), the
+  library used for JSON schema validation. Example:
+
+  ```js
+  var options = {
+    ajv: Ajv({ allErrors: true })
+  }
+  ```
+
+- `{function} onChange`
+
+  Set a callback function triggered when the contents of the JSONEditor change. Called without parameters. Will only be triggered on changes made by the user, not in case of programmatic changes via the functions `set` or `setText`.
+
+- `{function} onEditable`
+
+  Set a callback function  to determine whether individual nodes are editable or read-only. Only applicable when option `mode` is `tree`. The callback is invoked as `editable(node)`, where `node` is an object `{field: string, value: string, path: string[]}`. The function must either return a boolean value to set both the nodes field and value editable or read-only, or return an object `{field: boolean, value: boolean}`.
+
+- `{function} onError`
+
+  Set a callback function triggered when an error occurs. Invoked with the error as first argument. The callback is only invoked
+  for errors triggered by a users action, like switching from code mode to tree mode or clicking the Format button whilst the editor doesn't contain valid JSON.
+
+- `{function} onModeChange(newMode, oldMode)`
+
+  Set a callback function triggered right after the mode is changed by the user. Only applicable when
+  the mode can be changed by the user (i.e. when option `modes` is set).
+
+- `{boolean} escapeUnicode`
+
+  If true, unicode characters are escaped and displayed as their hexadecimal code (like `\u260E`) instead of of the character itself (like `☎`). False by default.
+
+- `{boolean} history`
+
+  Enables history, adds a button Undo and Redo to the menu of the JSONEditor. True by default. Only applicable when `mode` is 'tree' or 'form'.
+
+- `{String} mode`
+
+  Set the editor mode. Available values: 'tree' (default), 'view', 'form', 'code', 'text'. In 'view' mode, the data and datastructure is read-only. In 'form' mode, only the value can be changed, the datastructure is read-only. Mode 'code' requires the Ace editor to be loaded on the page. Mode 'text' shows the data as plain text.
+
+- `{String[]} modes`
+
+  Create a box in the editor menu where the user can switch between the specified modes. Available values: see option `mode`.
+
+- `{String} name`
+
+  Initial field name for the root node, is undefined by default. Can also be set using `JSONEditor.setName(name)`. Only applicable when `mode` is 'tree', 'view', or 'form'.
+
+- `{Object} schema`
+
+  Validate the JSON object against a JSON schema. A JSON schema describes the
+  structure that a JSON object must have, like required properties or the type
+  that a value must have. Only applicable for modes `tree` and `form`.
+
+  See [http://json-schema.org/](http://json-schema.org/) for more information.
+
+- `{boolean} search`
+
+  Enables a search box in the upper right corner of the JSONEditor. True by default. Only applicable when `mode` is 'tree', 'view', or 'form'.
+
+- `{Number} indentation`
+
+  Number of indentation spaces. 2 by default. Only applicable when `mode` is 'code' or 'text'.
+
+- `{String} theme`
+
+  Set the Ace editor theme, uses included 'ace/theme/jsoneditor' by default. Please note that only the default theme is included with jsoneditor, so if you specify another one you need to make sure it is loaded.
+
 
 ### Methods
 
diff --git a/examples/01_basic_usage.html b/examples/01_basic_usage.html
index 6d43620..60545a1 100644
--- a/examples/01_basic_usage.html
+++ b/examples/01_basic_usage.html
@@ -23,7 +23,8 @@
 <script>
   // create the editor
   var container = document.getElementById('jsoneditor');
-  var editor = new JSONEditor(container);
+  var options = {};
+  var editor = new JSONEditor(container, options);
 
   // set json
   document.getElementById('setJSON').onclick = function () {
diff --git a/examples/07_json_schema_validation.html b/examples/07_json_schema_validation.html
new file mode 100644
index 0000000..720c178
--- /dev/null
+++ b/examples/07_json_schema_validation.html
@@ -0,0 +1,67 @@
+<!DOCTYPE HTML>
+<html>
+<head>
+  <title>JSONEditor | JSON schema validation</title>
+
+  <link href="../dist/jsoneditor.css" rel="stylesheet" type="text/css">
+  <script src="../dist/jsoneditor.js"></script>
+
+  <style type="text/css">
+    body {
+      width: 600px;
+      font: 11pt sans-serif;
+    }
+    #jsoneditor {
+      width: 100%;
+      height: 500px;
+    }
+
+  </style>
+</head>
+<body>
+<h1>JSON schema validation</h1>
+<p>
+  This example demonstrates JSON schema validation. The JSON object in this example must contain properties <code>firstName</code> and <code>lastName</code>, can can optionally have a property <code>age</code> which must be a positive integer.
+</p>
+<p>
+  See <a href="http://json-schema.org/" target="_blank">http://json-schema.org/</a> for more information.
+</p>
+
+<div id="jsoneditor"></div>
+
+<script>
+  var schema = {
+    "title": "Example Schema",
+    "type": "object",
+    "properties": {
+      "firstName": {
+        "type": "string"
+      },
+      "lastName": {
+        "type": "string"
+      },
+      "age": {
+        "description": "Age in years",
+        "type": "integer",
+        "minimum": 0
+      }
+    },
+    "required": ["firstName", "lastName"]
+  };
+
+  var json = {
+    firstName: 'John',
+    lastName: 'Doe',
+    age: 28.5
+  };
+
+  var options = {
+    schema: schema
+  };
+
+  // create the editor
+  var container = document.getElementById('jsoneditor');
+  var editor = new JSONEditor(container, options, json);
+</script>
+</body>
+</html>
diff --git a/test/test_schema.html b/test/test_schema.html
index cfa80af..a8d95b9 100644
--- a/test/test_schema.html
+++ b/test/test_schema.html
@@ -64,8 +64,8 @@
   };
 
   var options = {
-    mode: 'tree',
-    modes: ['form', 'tree', 'view'], // allowed modes
+    mode: 'text',
+    modes: ['text', 'form', 'tree', 'view'], // allowed modes
     onError: function (err) {
       console.error(err);
     },