JSONx Framework for JavaScript

JSON Schema for the enterprise

Abstract

The JSONx Framework is a collection of specifications and reference implementations that provide structural and functional patterns intended to help developers work with JSON. The JSONx Framework defines the JSON Schema Definition Language, which is a schema language designed in close resemblance to the XMLSchema^❐ specification.

This document introduces the JSONx Framework, and presents a directory of links to its constituent parts and related resources.

Note

The JSONx Framework for JavaScript is work in progress, and does not yet have a functional implementation. The JSONx Framework for Java, however, is fully implemented, offering a complete solution for the full spec of the JSON Schema Definition Language.

Table of Contents

  1 Introduction
    1.1 Conventions Used in This Document
  2 JSON Schema Definition Language
    2.1 Purpose
    2.2 Requirements
    2.3 Getting Started
    2.4 JSD vs JSDx
    2.5 Specification
  3 Document Validation
    3.1 Purpose
    3.2 Requirements
    3.3 Getting Started
    3.4 Specification
  4 Contributing
  5 Special Thanks
  6 License

1 Introduction

The JSONx Framework was created to help developers address common problems and use-cases when working with JSON. The JSONx Framework offers structural and functional patterns that systematically reduce errors and pain-points commonly encountered when developing software that interfaces with JSON. The structural patterns are defined in the JSON Schema Definition Language, which is a programming-language-agnostic schema language to describe constraints and document the meaning, usage and relationships of the constituent parts of JSON documents. The functional patterns are reference implementations (on the Java platform) of the specification of the schema language, providing utilities that address common use-cases for applications that use JSON in one way or another. Common use-cases include:

1. Definition of a normative contract between a producer and consumer of JSON documents.
2. Validation of JSON documents conforming to a respective schema document.
3. Java class binding capabilities for JSON documents conforming to a respective schema document.

1.1 Conventions Used in This Document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

2 JSON Schema Definition Language

Describes JSON documents using schema components to constrain and document the meaning, usage and relationships of their constituent parts: value types and their content.

2.1 Purpose

Provide a schema language to describe normative contracts between producer and consumer ends of a protocol exchanging JSON documents.

2.2 Requirements

1. The schema language MUST constrain and document the meaning, usage, constraints and relationships of the constituent parts of a JSON document.

2. The schema language MUST provide meaningful and useful constraint rules for the 5 JSON value types:

   boolean, number, string, object, array.

3. The schema language MUST support schema descriptions for any and all legal JSON documents, as specified by RFC2119.

4. The schema language MUST be free-of and agnostic-to patterns specific to any particular programming language.

5. The schema language MUST be able to describe itself.

2.3 Getting Started

The JSON Schema Definition Language can be expressed in 2 forms: JSD (Json Schema Document), and JSDx (JSD in XML semantics).

Create schema.jsd or schema.jsdx with the following content:

JSD

{
  "jx:ns": "http://www.jsonx.org/schema-0.3.jsd",
  "jx:schemaLocation": "http://www.jsonx.org/schema-0.3.jsd http://www.jsonx.org/schema.jsd",

  "myNumber": { "jx:type": "number", "range": "[-1,1)" },
  "myString": { "jx:type": "string", "pattern": "[a-z]+" },
  "myObject": {
    "jx:type": "object", "properties": {
      "myArray": {
        "jx:type": "array", "elements": [
          { "jx:type": "boolean" },
          { "jx:type": "reference", "type": "myNumber" },
          { "jx:type": "reference", "type": "myString" },
          { "jx:type": "array", "elements": [
            { "jx:type": "boolean" },
            { "jx:type": "number", "range": "[0,100]", "scale": 0 },
            { "jx:type": "string", "pattern": "[0-9]+" },
            { "jx:type": "any", "types": "myNumber myString" } ]},
        { "jx:type": "reference", "type": "myObject" },
        { "jx:type": "any", "types": "myString myObject" }]
      }
    }
  }
}

JSDx

<schema
  xmlns="http://www.jsonx.org/schema-0.3.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.jsonx.org/schema-0.3.xsd http://www.jsonx.org/schema.xsd">

  <number name="myNumber" range="[-1,1)"/>
  <string name="myString" pattern="[a-z]+"/>
  <object name="myObject">
    <property name="myArray" xsi:type="array">
      <boolean/>
      <reference type="myNumber"/>
      <reference type="myString"/>
      <array>
        <boolean/>
        <number range="[0,100]" scale="0"/>
        <string pattern="[0-9]+"/>
        <any types="myNumber myString"/>
      </array>
      <reference type="myObject"/>
      <any types="myString myObject"/>
    </property>
  </object>

</schema>

_{Note: You can use the Converter utility to automatically convert between JSD and JSDx.}

This example defines a schema with 3 types that express the following structure:

1. Type myNumber: A number between the range -1 (inclusive) and 1 (exclusive).
2. Type myString: A string with the regex patter "[a-z]+".
3. Type myObject: An object that has one property:
   1. "myArray": An array that defines a sequence of elements:
      1. boolean
      2. myNumber
      3. myString
      4. An array with the following elements:
         1. boolean
         2. An integer number between 0 and 100.
         3. A string of pattern "[0-9]+"
         4. Either myNumber or myString.
      5. myObject
      6. Either myString or myObject.

2.4 JSD vs JSDx

The JSDx format offers XML validation, and using an XML IDE like oXygen XML Editor^❐ offers edit-time XML validation, such as:

When using the JSDx format with the oXygen XML Editor^❐, the auto-completion features of the editor will guide you in writing the schema. With the JSDx format, the XML editor will also validate keys and keyrefs to ensure that declared types are referenced correctly.

2.5 Specification

For a detailed specification of the schema language, see JSON Schema Definition Language.

3 Document Validation

Provide a way for JSON documents whose structure is expressed in the JSON Schema Definition Language to be validated.

3.1 Purpose

Provide a Validator for the validation of JSON documents against a JSD or JSDx.

3.2 Requirements

1. The Validator MUST support the full scope of the JSON Schema Definition Language.

2. The Validator MUST produce clear and useful error messages that identify the exact location of the error when validation errors are encountered.

3. The Validator MUST be interoperable in Node.js and the browser.

4. The Validator MUST be straightforward, intuitive, and resilient to human error.

3.3 Getting Started

Coming soon.

3.4 Specification

Coming soon.

4 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

5 Special Thanks

_{Special thanks to EJ Technologies for providing their award winning Java Profiler (JProfiler) for development of the JSONx Framework.}

6 License

This project is licensed under the MIT License - see the LICENSE.txt file for details.