Home

This wiki is intended for people who want to understand JSON Editor's code structure in order to hack, contribute to, or customize the code. If you simply want to use JSON Editor as is, the README should suffice.

This document assumes basic knowledge of JSON Schema.

This document is a work in progress. More will be added soon.

you can see a live editable example at runnable.com Overall Structure

JSON Editor is built to be extremely modular. This section will go over each of the modular components and how they work together.

Intro and Outro (src/intro.js and src/outro.js)

These files wrap everything in a closure to keep things self contained.

In addition, intro.js has licence information in a comment at the top along with the current version number and date. JSON Editor uses Semantic Versioning and is in the pre-1.0 phase. Every single code commit should increment the patch version. Major new features or backwards compatibility breaks should increment the minor version.

Class Inheritance (src/class.js)

JSON Editor uses John Resig's Simple Javascript Inheritance model (http://ejohn.org/blog/simple-javascript-inheritance/). I don't recommend using this for complicated inheritance structures, but it fits JSON Editor's use case perfectly.

var MyParentClass = Class.extend({
  method1: function() {},
  method2: function() {}
});

var MyChildClass = MyParentClass.extend({
  method1: function() {
    this._super();
  },
  method3: function() {}
});

Every part of JSON Editor is a class. This makes it easy to extend parts as needed.

Utilities (src/utilities.js)

JSON Editor was originally built as a jQuery plugin. When the jQuery dependency was removed, a couple utility functions were added in it's place.

• $extend - Just like jQuery.extend, except it is recursive by default.
• $each - Identical behavior to jQuery.each
• $trigger - Trigger a native javascript event
• $triggerc - Trigger a custom javascript event

IE9 (src/ie9.js)

This file contains polyfills for old browsers. Currently, there are only 2 polyfills:

• requestAnimationFrame
• CustomEvent constructor

Validator (src/validator.js)

This JSON Validator is the only part of JSON Editor that looks at the entire provided schema. Everything else only works with bits and pieces at a time.

The Validator has 2 main purposes. The first is, as you might expect, to validate JSON against a schema and return a list of errors. The second purpose is to pre-process the schema to resolve any references.

Validation results are used a number of different places. The obvious ones are for displaying errors inline in the rendered form and powering the validate api call. Another not-so-obvious use of the validation results is to determine which oneOf schema to use when rendering part of the form. Consider the following JSON Schema:

{
  "type": "object",
  "oneOf": [
    {
      "properties": {
        "name": {"type": "string"}
      },
      "required": ["name"],
      "additionalProperties": false
    },
    {
      "properties": {
        "id": {"type": "integer"}
      },
      "required": ["id"],
      "additionalProperties": false
    }
  ]
}

When the value of the form is set programatically, JSON Editor validates the value against each of the schemas and uses the first one that passes to render the form. A similar thing is done for compound types (e.g. { "type": ["integer","string"] }).

The second purpose of the Validator is to pre-process the schema to resolve any $ref, allOf, and extends keywords. The Validator flattens these keywords by merging the referenced schema into the parent one.

This:

{
  "type": "string",
  "allOf": [
    { "minLength": 3 },
    { "maxLength": 10 }
  ]
}

is flattened to this:

{
  "type": "string",
  "minLength": 3,
  "maxLength": 10
}

This pre-processing step greatly reduces the complexity of the rest of the code, but has a couple downsides, most notably preventing support for recursive schemas.

It's also worth noting that the pre-processing step is the only asynchronous part of JSON Editor. This is to allow for loading $ref URLs via ajax.

The Validator code itself is very complex. It starts with the outermost schema and recursively descends to child schemas, validating along the way. All of the JSON Schema Draft 3 and Draft 4 keywords are supported.

If there is a validation error, a simple error object is added to an array. At the end of validation, this array of errors is returned. An empty array is returned if there are no validation errors. Each error object in the array has 3 properties, path, property, and message.

{
  "path": "root.person.first_name",
  "property": "minLength",
  "message": "Value must be at least 2 characters long"
}

At each step in the recursive descent, JSON Editor will also call any custom validation functions defined in JSONEditor.defaults.custom_validators.

IconLib (src/iconlib.js)

JSON Editor supports multiple icon libraries. These are used to add icons to buttons.

All icon libraries extend JSONEditor.AbstractIconLib. AbstractIconLib is set up to make it really easy to add new icon library support. Here's the code for FontAwesome4 support (src/iconlibs/fontawesome4.js):

JSONEditor.defaults.iconlibs.fontawesome4 = JSONEditor.AbstractIconLib.extend({
  mapping: {
    collapse: 'caret-square-o-down',
    expand: 'caret-square-o-right',
    delete: 'times',
    edit: 'pencil',
    add: 'plus',
    cancel: 'ban',
    save: 'save',
    moveup: 'arrow-up',
    movedown: 'arrow-down'
  },
  icon_prefix: 'fa fa-'
});

Calling getIcon("cancel") will return the DOM element <i class="fa fa-ban"></i>. If you want to add an icon library that doesn't conform to this style, you can override the getIcon method and handle the DOM creation yourself.

Theme (src/theme.js)

Documentation coming soon...

Template (src/template.js)

Documentation coming soon

Editor (src/editor.js)

Documentation coming soon

Core (src/core.js)

Documentation coming soon

Defaults (src/defaults.js)

Documentation coming soon

jQuery Wrapper (src/jquery.js)

Documentation coming soon