JSOND

Introduction

JSOND (JSON Definition) is a simple, yet powerful, definition language for JSON text.

The purpose of JSOND is to facilitate development and documentation of JSON text. JSOND is designed to be a minimal superset of JSON.

JSOND text have the same structure as the JSON text defined.

JSON Basics

Let's recap JSON basics. JSON is built on two structures:

In JSON, a value must be one of the following:

JSOND Basics

It's easy to start using JSOND. Simply write JSON as normal using objects and arrays. Instead of example values, use one of the following string literals:

Values

"boolean"

A JSOND value "boolean" defines that the corresponding JSON value must be either true or false.

"string"

A JSOND value "string" defines that the corresponding JSON value must be a string.

The string can be more specifically defined using a regular expression.

"[a-z]"

Defines that the JSON value can only consist of the characters a to z.

"number"

A JSOND value "number" defines that the corresponding JSON value must be a number.

The number can be more specifically defined with a mathematical set or interval.

"{1.5,2.4,4.8}"

Defines that the JSON value must be 1.5, 2.4, or 4.8.

"[1.0,4.0)"

Defines that the JSON value must be a number greater than or equal to 1.0, and less than 4.0.

"integer"

A JSOND value "integer" defines that the corresponding JSON value must be an integer,
i.e. a number without a decimal component.

The integer can be more specifically defined with a mathematical set or interval.

"{1,2,4}"

Defines that the JSON value must be 1, 2, or 4.

"[1,4)"

Defines that the JSON value must be an integer greater than or equal to 1, and less than 4.

References

JSOND text can be persisted as a .jsond file. A JSOND file can be referenced using the http scheme or a filepath as the JSOND value.

"http://jsond.org/utc.jsond"

Defines that the JSON value must be a string with the format "yyyy-mm-ddThh:mm:ssZ" with optional fractions of the second as defined in http://jsond.org/utc.jsond.

Optionals

A name/value pair may be marked as optional by appending a question mark to the name. Optional name/value pairs may have the value null. Optional name/value pairs are not required to be in the corresponding JSON text. 

"age?"

Defines that the JSON value may be null and that the JSON name/value pair may not be in the JSON text.

A. Examples

Example 1 defines a person with a required first and last name and a optional age that if given must have a value that is an integer larger than or equal to 18. 
{
    "firstName": "string",
     "lastName": "string",
         "age?": "[18,)"
}

EXAMPLE 1: PERSON

Example 2 defines a product with a required id, name and price that is larger than 0 and a optional array of strings named tags. 
{
       "id": "integer",
     "name": "string",
    "price": "(0.0,)",
    "tags?": [ "string" ]
}

EXAMPLE 2: PRODUCT

Example 3 defines a array of products. A product is defines with a required id, name and price, a optional array of strings named tags, a optional dimensions object and a optional warehouse location. The definition of a warehouse location is found in the referenced file coordinates.jsond. 
[
    {
           "id": "integer",
         "name": "string",
        "price": "(0.0,)",
        "tags?": [ "string" ],
        "dimensions?": {
             "length": "number",
              "width": "number",
             "height": "number"
        },
        "warehouseLocation?": "http://jsond.org/coordinates.jsond"
    }
]

EXAMPLE 3: ARRAY OF PRODUCTS

Example 4 defines coordinates.jsond references in Example 3. 
{
     "latitude": "number",
    "longitude": "number"
}

EXAMPLE 4: coordinates.jsond

B. Figures

FIGURE 1: VALUE

FIGURE 2: SET

FIGURE 3: INTERVAL

FIGURE 4: REFERENCE

FIGURE 5: OPTIONAL