JSON
JSON stands for JavaScript Object Notation and is a format used for data exchange that has some similarities to XML.
It is a format that is often used in RESTful webservices and as such it is important to be able to use it from within DataFlex.
JSON Format
JSON is a very simple format, derived from JavaScript's Object Literal notation, consisting of a series of name/value pairs with arbitrarily deep nesting.
The names are quoted with double-quote characters: "name".
How values are written depends on the data-type (see below).
Names are separated from values by colons: "name":value.
The pairs are separated from each other with commas: "name1":value1, "name2":value2, "name3":value3... (the last pair in such a series should not be followed by a comma however).
Special characters may be "escaped" in string values (or indeed names) with a backslash: \
- \\ represents \ (backslash)
- \/ represents / (forward slash)
- \" represents " (double-quote)
- \b represents backspace (ASCII 8)
- \f represents formfeed (ASCII 12)
- \n represents newline (ASCII 10)
- \r represents carriage-return (ASCII 13)
- \t represents tab (ASCII 9)
Unicode characters (up to FFFF: 65,535, which covers the basic multilingual plane) may be represented by \uHHHH, where "H" is a hexadecimal-digit (0-F).
JSON Data Types
JSON values can be one of six data-types - four "primitive" and two "compound":
Primitive:
- Strings, which, like names, must be quoted with double-quote characters: "value"
- Numbers, which can be simple integers, or decimal values, or exponentiated (using either "e" or "E") and may be negative:
- 6
- 13429064
- -9645
- 23.657685
- -29.41
- 1.23456e7 (indicating 12,345,600)
- -456.789E5 (indicating -45,678,900)
- 6.281e-6 (indicating 0.000006281)
- Boolean, which can have the value of either true or false (unquoted)
- Null, which is simply represented by null (unquoted)
Compound:
- Objects, which are enclosed in { ... } characters and generally contain additional name/value pairs: {"surname":"Peat", "forename":"Mike", "age":21, "is male":true, "salary":null}
- Arrays, which are enclosed in [ ... ] characters and are made up of values separated by commas: [5, "Mike", false, 14.70912, null, -5.34108e9]
Whitespace is irrelevant outside of quotations (although both names and string values may contain whitespace). Because of this, JSON may be formatted for easier human-readability (prettified) with spaces and line breaks:
{
"first name": "Mike",
"last name": "Peat",
"age": 21,
"is male": true,
"salary": null,
"address": {
"house": 22,
"street": "Acacia Avenue",
"town": "Dullsville",
"county": "Midhamptonshire"
},
"test scores": [56, 87, 19, 11, 70, 64]
}
JSON in DataFlex
Before DataFlex 19.0 you had to resort to external libraries in order to use JSON, see for example JSON Parsing ... the beginnings of an alternative approach
As of DataFlex 19.0 we have native support for JSON objects and can access and directly work with these data structures. This functionality is offered via the cJsonObject
One of the great features in that class is that you can move all your data from JSON into a struct with just one command and vice versa. In order to transfer your data from JSON to a struct you would use the JsonToDataType function and if you have to convert data from a struct to JSON then you can use DataTypeToJson.
When migrating data from JSON to a struct sometimes a member might be missing from the JSON data. For example because the element you are looking for is empty. In that case the runtime will trigger a runtime error. You can disable that by setting the pbRequireAllMembers property of the DataFlex Json object to false.
If you need to deal with JSON which uses DataFlex reserved words in its member names (or other invalid values, such as those containing spaces in the example above: e.g "first name") then, since DataFlex 19.1, you can now use a valid name in your struct and assign a different name for the conversion via meta-data tags. This is sometimes referred to as the altName member
