JSON, JavaScript Object Notation, is a string presentation of a JavaScript object so that JavaScript object can be saved in file or exchange among computers. Although is used in JavaScript, it can also be interpreted in other programming languages.
JSON Data Type Limitation
The data type used in JSON are null, number, string, boolean, list, and object. The object specified in JSON is only a "generic" object without speification of object class, it is a list of key-value pairs similar to a dictionary in other languages. Which make some common data type, like Datetime is difficult to specifiy.
Datetime in JavaScript is an object. Although one can specify a Datetime as an object. But the receiver cannot know an object is a Datetime object since there are no class specification in a JSON object.
So how can a receiver know a data is a date, without prior knowledge? A common solution is to send datetime as string. Then the receiver need to decode every string to datetime. If success, it is a date, time, or datetime. If not, it is a normal string.
Alternative, we can provide the object class name in a special attribute, say _cls. The receiver then look for this class attribute on each received object.
{
"_cls": "datetime",
"year": 2000, ...
}
Another common data type is binary data, which is commonly used for image. However, we can use the same solution for binary data.
String notation of datetime and binary.
The following is a string and object presentasion of DateTime and Binary data.
Object notation of datetime and binary.
The object presentation of datetime and binary data use a class specifier, _cls. The available _cls are
There are two other issues in JSON. The first issue is that it must be an object, that is the notation must start with a curly bracket.
Another issue in JSON is that object attributes can either be a number or a string. Thus attributes must be quoted if it is a string.
So iGarment extend the JSON notation in order to make the notation to include more data types, shorter, and easier to use. The extension should also be easy to implement, which is why the data type can be determine by the first character of the data.
The following is a list of data type in corresponding to the first (non-blank) character of a token.
Instead of writing a full specification, may be it is easier to understand with an example.
The following is an example of an XJSON object, or a key-value pair dictionary. Note that attribute (or dictionary key) does not needed to be quoted, although you can. You cannot use number as attribute. Attribute must be a single word without space in between.
{
feedback : 1,
changeset : {
tablename : "sygmatr_2",
primary : [
"MatrClass",
"MatrCode"
],
fields : [
"MatrClass",
"MatrCode",
],
},
lost: 2300.12-
seed: 0xa78b239
create_date: D2023-01-12T08:11:00
author: N,
locked: F,
icon: _HA09EFJKI===,
}
This is an example for a XJSON for a list instead of an object. It can also be a number or a string too.
[ 1, 2, "Red", DT12, ]
Notes on Boolean
Notes on Number
Notes on DateTime
Notes on String
Notes on Bytes
Notes on List and Dict