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]

Prettifying

Whitespace is irrelevant outside of double-quotes (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, so:

{"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]}.

Is the same, from a machine standpoint, as the rather more human-readable:

{
   "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]
}

Which is only slightly less compact "on the wire" (by around 25 bytes).

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 function or procedure call, 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 the DataTypeToJson procedure.

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, so it has simply been omitted from the JSON. 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

External references

• DataFlex Learning Center - Working with JSON

• JSONLint the json validator

• Starzen JSON Library

• cJsonPath class - Mike Peat, 6th Feb 2020. Easily get either objects or values from deep inside pretty complex JSON data.

• JsonConfig.pkg - Mike Peat, 5th Feb 2020. A little singleton object-package which can read in a JSON configuration file and then allows you to read various settings out of it.