JSONR

Regular JavaScript Object Notation

Applications

Regular JSON (or JSONR) is a simple protocol to specify practical patterns for network object models.

JSONR can be applied in a web browser to generate interactive HTML input forms from an object model instead of an an-hoc program. In a web controller JSONR is usefull to validate network input against the application's model instead of an ad-hoc program.

Implementations are available for both use case respectively in JavaScript (jsonr.js), Java (org.less4j.JSONR) and Python (jsonr.py).

Specification

JSONR is a simple application of JSON to express patterns of the most common object models for programming languages: null, true or false, integer, double and decimal, irregular and regular strings, numeric ranges around and from zero, collections, relations, dictionnaries and namespaces.

By design, JSONR patterns are constrained to relevance, forced to describe object models with only optional nested scopes, where null is the only valid expression for the absence of data and for which irregular strings are allways optional.

Duck typing

If it quaks like a duck and walks like a duck then it must be a duck:

`null`	any value
`true`	a boolean, true by default
`false`	also a boolean, false by default
`""`	any text string
`0`	any number

JSONR implementation may infer numeric application types from formats as follow: if it prints like an zero integer, double or decimal, then it is an integer, a double or a decimal.

`0`	an integer value
`0e+`	a double value
`0.0`	a decimal value

Most JSON implementation - most notably JavaScript - support only one numeric type and can therefore not distinguish between the different formats of zero.

Numeric Ranges

JSONR agents must interpret numeric values different than zero a simple numeric ranges between zero and N if N is positive or between N and -N if N is negative.

`12`	a non-negative integer lower than or equal 12
`-100`	an integer between -100 and 100

They also may distinguish numeric types. In this case they must differentiate integer and float or decimal ranges from the absence of decimal fractions. Also, decimal ranges must be interpreted as strictly between zero and N:

`50e-2`	a non-negative double value lower than or equal 0.50
`10.01`	any two digit decimal between 0.01 and 10.00
`-50e-2`	any double between -0.50 and +0.50
`-10.01`	a two digit decimal between -10.00 and +10.00

Functional numeric constraints that are not positive or absolute ranges belong to the application process and are usually best expressed in the application's own programming language.

Named Patterns

Some application demand specialized data types, usually defined by network protocols and computer programs as extension of the string type. JSONR provides an opportunity for extensions: string values that match the name of a protocol extension should be interpreted likewise.

JSONR agents should implement two named patterns: the common JavaScript datetime format and the new Public Names protocol for meaningfull resource identifiers.

`"yyyy-MM-ddTHH:mm:ss"`	a valid date and type value formated alike, as the defacto standard serialization of a date and time instance.
`"6:Names,5:Public,"`	a valid Public Names, a simple protocol to name network resources in a meaningfull way for human and a practical way for computer applications.

Note that JSONR agents must not use those two names for anything else than JavaScript datetime and Public Names.

Regular String

JSONR interprets non-empty string as either the name of an extension type or a Perl regular expression.

For instance:

`"^..........$"`	exactly ten UNICODE characters
`"^[A-Z0-9]*$"`	a string of zero or more uppercase roman alphanumerics
`"[\\x20-\\x7E]+"`	any string made of at least one printable 7-bit ASCII character

Perl regular expressions are enough to define practical limits on most network application object model strings and are available on virtually all development plateform.

Collections

An array with one element must be interpreted by JSONR applications as either null or a collection of one or more of its single regular value:

`[null]`	one or more values of any type
`[12]`	a list of at least one integer between 1 and 12
`[-10.01]`	one or more two digit decimal between -10.00 and +10.00
`[1.0e-1]`	an non-empty collection of doubles between 0 and 0.1
`[""]`	a list of at least one irregular strings
`["[a-z]*"]`	one or more strings matching this regular expression

Note that [] is not a valid JSONR pattern.

Relations

An array with more than one element must interpreted as a regular relation, an ordered set of more than one JSONR expression. For instance,

[".+", 800, 600, true]

defines an ordered relation between: a non-empty string, an integer between 0 and 800, an integer between 0 and 600 and a boolean.

Combining collection and relation JSONR can define the most common relational model of tables.

For instance:

[[".+", 800, 600, true]]

validates the data following data:

[
   ["A", 270, 420, true],
   ["B", 24, 24, true],
   ["C", 768, 240, true],
   ["D", 799, 599, false]
   ]

Note that this makes JSONR a practical modeling language for network database applications.

Dictionnary

An object with a single property must be interpreted as a dictionnary of regular key strings and values.

For instance:

{"[a-zA-Z]{4,35}": "yyyy-MM-ddTHH:mm:ss"}

is the model for a mapping of short cased alphabetic names to JavaScript dates and times.

Note how JSONR simplicity prevents the definition of irrelevant namespaces made of only one name: an object with a single property would be a redundant data structure, so such singleton must be interpreted differently.

Namespaces

JSONR agents must interpret all nulls, arrays, objects and irregular strings as optional in their namespace. All other named properties must be present in a matching object and names not present in a JSONR model are invalid.

For instance, in this namespace:

{
  "publicNames": "5:Names,6:Public,", 
  "title": ".+",
  "firstName": ".+",
  "middleName": ".+",
  "lastName": ".+",
  "online": false,
  "mailto": "[\\x20-\\x7E]+@[\\x20-\\x7E]+",
  "href": "https?:\\/\\/.+(\\/.+)?",
  "contactPersons": ["5:Names,6:Public,"],
  "courses": [["[a-zA-Z]{4,35}", 52, 7, 8]],
  "vcard": "",
  "extensions": {".+$": null}
  }

the properties contactPersons, courses, vcard and extensions are optional.

The protocol is specifically intended to favour flat, unambiguous and practically possible models everywhere JSON is available (virtually everywhere). Deeply nested and ambiguous models are still possible, but their applications will require more boilerplate code to manage data and structure.

To enable simple application extensions, JSONR implementation must add all names declared to the map of named patterns maintained for the model interpreted.

For instance:

{
  "point": {"x": 0e+1, "y": 0e+1, "z": 0e+1}, 
  "directions": [{"a": "point", "b": "point"}]
  }

is a valid expression to declare the point model and then use it to model a collection of directions.

Finally, note that {} is not a valid JSONR pattern.