JavaScript Object Notation (JSON)

JSON is a data-interchange format for simple object structures. Inheritance is supported implicitly. Weak-typed collections are not supported. JSON supports named values, instances, collections and arrays, i.e. JSON files allow providing hierarchical object structures. Inheritance is supported implicitly. Not supported are weak- or untyped collections.

Since JSON files require names, only values to be imported or exported need to be defined, i.e. JSON files need not to be complete. When importing an JSON file, properties not defined in the file will not be updated. Passing null for a properties will delete property data (references/collection) or restore the initial value (attributes).

JSON files can be referenced in exportData() and importData() functions (Property and ObjectSpace) or when opening external files by Property::openExtern().

Limited access to JSON files is supported by defining JSON extents in the dictionary (access type AT_EXTERN or AT_JSON). In this case, the file path is expected in an option having the same name as the extent. No header and no external file description are supported for JSON extents. In case of using AT_EXTERN, the file extension must be json.

JSON definition

An ODABA JSON file always consists of an object (see BNF below) that contains one or more named_values. In case of a top-level (database) JSON file, each named_value provides data for an extent. When containing a single, the object contains instance properties. For an elementary value, the object contains a single named value, only.

name - A name for a named_value consists of ASCII characters (lower and upper case letters, digits, and/or underscore). Unless no data mapping has been defined, names are property names defined for the database.

number - A number is an integer, decimal or a float point number (see OSI language reference). It depends on context (property definition), which number types are allowed.

null - may be passed or returned for MEMO and BLOB properties and indicates no-data, which is slightly different from an empty string (""). null may also passed in order to indicate an empty collection. Storing null for a database property has different effects for attributes and references. For references (single and collections) all instances will be removed. For attributes, the initial value will be restored.

true, false - are the only values allowed for Boolean properties.

string - String values are always enclosed in quotation marks and must not contain special characters as newline or tab. Special characters have to be escaped as follows (see also JSON syntax):

\ ==> \\
line feed (10) ==> \n
carriage return (13) ==> \r
backspace (8) ==> \b
form feed (12) ==> \f
tab (9) == \t
" ==> \"

All string values exchanged via JSON are UTF8 encoded. Binary data (BLOB properties) is always passed as BASE64 string (which is UTF8 compatible),

// simple value

{ age: 45 }

// instance

{ name: "Müller", age: 45.5, comment: "\Höhen und \nTiefen", image: null }

// collection

{ Persons: [ { name: ... }, { ... } ] }

// database

{ Cars: [ ... ], ... Persons: [ ... ] }

Definition:

values := value | object | array

object := '{' named_value [ named_value_ext(*) ] '}'

named_value_ext := ',' named_value

named_value := name ':' value

array := '[' value [ value_ext(*) ] ']'

value_ext := ',' value

value := string_value | number | 'true' | 'false' | 'null'

string_value := '"' string '"'

to top Comment