JSchema

Introduction

The great virtue of JSON is that it is simple. Its grammar consists of only 15 productions, making it both easy to parse and produce.

A simple data format demands a simple description mechanism. JSchema satisfies this requirement:

It is only 8 productions beyond the original JSON grammar
It is flexible enough to specify most existing JSON content
It communicates the structure of the JSON document it describes visually
It is simple to convert a JSON document into its JSchema

Grammar

<type> ::=
  <core_types> |
  <array_type> |
  <enum_type> |
  <struct_type> |

<core_types> ::=
  '"@string"' |
  '"@boolean"' |
  '"@date"' |
  '"@uri"' |
  '"@int"' |
  '"@number"' |
  '"*"'

<array_type> ::=
  '[' <type> ']'

<enum_type> ::=
  '[' <string> ','
      <string> <strings> ']'

<strings> ::=
  '' |
  ',' <string> <strings>

<struct_type> ::=
  '{' <props> '}'

<props> ::=
  <prop> |
  <prop> ',' <props>

<prop> ::=
  <string> ':' <type>

Types

"@string"

A string may be a JSON string.

"@boolean"

A boolean may have a value of true or false.

"@date"

A date may be a JSON string in any format specified by the W3C NOTE-datetime.

"@uri"

A uri may be a JSON string that is a valid URI.

"@int"

An int may be a JSON int.

"@number"

A number may be a JSON number.

"*"

A wildcard may be any JSON value.

Array Type

An array may be a JSON Array with elements that conform to the type definition enclosed within the array.

Enum Type

An enum, defined in JSchema by an array of more than one JSON string in it, must have a JSON value from the domain of those strings.

Struct Type

A struct type defines a JSON object by a series of name/type pairs. For each name/type pair, a conforming JSON object, if a pair with the name is present, will have a value conforming to the type. If the name is not present, it is interpreted as being null. Additionally, pairs not mentioned in the Struct Type may be present and should be preserved.

Runtime Behavior

Nullability

All values in a JSON document described by a JSchema schema may have a null value. The interpretation of the null value is left to implementations, with the caveat that nulls should be preserved.

Schema File Suffix

JSchema files should end with the .jschema file suffix.

Malformed Schemas

To support backwards compatibility for future schemas, any unrecognized part of a JSchema file should be treated as a wildcard, with appropriate warnings.

Unspecified Pairs

JSchema gives a positive specification of a JSON document. Any additional JSON pairs not included in the schema should not cause serialization issues and should be preserved.

Examples

JSchema	Conforming JSON
{ "name" : "@string", "age" : "@int" }	{ "name" : "Joe", "age" : 42 }
[ { "name" : "@string", "age" : "@int"} ]	[ { "name" : "Joe", "age" : 42 } { "name" : "Paul", "age" : 28 } { "name" : "Mack", "age" : 55 } ]
[ { "name" : "@string" "age" : "@int", "eye_color" : ["brown", "blue", "green"] } ]	[ { "name" : "Joe", "age" : 42, "eye_color" : "brown" }, { "name" : "Paul", "age" : 28, "eye_color" : "brown" }, { "name" : "Mack", "age" : 55, "eye_color" : "blue" } ]

JSchema 1.0

The JSchema 1.0 specification is available here.

{} JSchemav2.0.1