iGarment Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== xjson ======

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.

  * The string presentation of datetime, date, time data is "YYYY-MM-DD HH:NN:SS". Either the date part or the time part is optional.

  * The object presentaion of binary data is "_%". where refer to either 64 (base64) or 85 (z85) encoding method. And data is the string encoding of the binary data of the correspnding encoding method.

==== Object notation of datetime and binary. ====

The object presentation of datetime and binary data use a class specifier, _cls. The available _cls are:

  * _cls: datetime, date, or time (datetime)

  * _cls: base64, or z85 (binary)

===== XJSON =====

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:

  * N: refer to Null

  * T/F: refer to boolean

  * a digit: refer to a number

  * D: refer to a Date

  * ": refer to a string (UTF8) and end with another "

  * _': refer to a bytes and end with another '

  * [: start of list and must end with ]

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 ====

T or True, or TT are the same since we first character already tell the type. Similar to F and False.

==== Notes on Number ====

  * The sign of a number is put at the end, eg. negative 123 is 123-

  * One can use exponential notation, eg. 1.234E4

  * Start a number 0x for hexidecimal.

==== Notes on DateTime ====

  * The full specification is D[YYYYMMDD][THHMMSS.ZZZ[+HHMM][+TZ]]

  * TZ refer to time zone, which is a number

  * To specify time. just omit the date but still need to start with 'D'. Eg. DT12 for 12:00:00

==== Notes on String ====

  *   String is UTF8 encoded.

  * You can escape a character with backslash, . The possible escaped characters are \0 \b, \n, \r, \t, \Z, \, ', and ".

==== Notes on Bytes ====

You shall put bytes data betwen pair of signle quote if you have space in bytes data. For example _'AJKIE JJAE'. Or you want to use different encoding method other than the default Base64. Eg, _z85'0JIU@-+' are binary data using Z85 encoding.

==== Notes on List and Dict ====

You can leave the last item in a List or Dict blank. Eg [ 1, 2, 3, ] is accepted. So is { a: 1, b: 2, }. But you cannot have an empty item in between. Eg [ 1,,3 ] or { a: , b: 2 }, error.