JSON

JSON

This node takes a JSON string and provides its content for further processing.

JSON (JavaScript Object Notation) is an open standard format that uses human-readable text to transmit data objects consisting of key:value pairs. It is used primarily to transmit data between a server and web application, as an alternative to XML. Many online services such as Twitter, Facebook, Yahoo or Google are using JSON as a simple data format for their information services.

The JSON Parser node can parse JSON objects, arrays of objects, single values or arrays of values. In contrast to XML, which only knows the string type, JSON can handle a few strongly typed values. Unfortunately JSON doesn't define any data size or precision of these types, so many incompatibilities can be expected when using JSON as data interchange format.

Examples

Single value:

"A simple string\nwith linefeeds and escaped \u0055nicode"

Array of values
```
[ 1, 2, 3, 4 ]
```

Single object (with nested object values and array)

{
    "firstName": "John",
    "lastName": "Smith",
    "age": 25,
    "address": {
        "streetAddress": "21 2nd Street",
        "city": "New York",
        "state": "NY",
        "postalCode": 10021
    },
    "phoneNumbers": [
        {
            "type": "home",
            "number": "212 555-1234"
        },
        {
            "type": "fax",
            "number": "646 555-4567"
        }
    ]
}

Array of objects

[
{
    "firstName": "John",
    "lastName": "Smith",
    "age": 25,
},
{
    "firstName": "Donald",
    "lastName": "Duck",
    "age": 5,
},
{
    "firstName": "John",
    "lastName": "Doe",
    "age": 178,
}
]

JSON Types

JSON natively supports the following data types:

string: "quoted text with\nC-style\tcharacter escaping"
boolean: true or false
numbers: (integers and or floating point numbers) 0, 561423, -104.199, 0.123e-6
null-value: null
objects: (see below)
arrays: elements can be a mixture of values, objects or arrays

JSON Objects

A JSON object is expressed in a list of named values, where each name is a quoted string followed by a colon :. The value is a choice of the supported types. A JSON object can be understood as a dictionary or a list key:value pairs. JSON is a very lazy format . Therefore some issues have to be in mind when using JSON:

JSON doesn't define that the name within an object must be unique. The value "user" could appear two times, for example.
the type of a named value may differ. A value named "city" could appear as a string in one JSON object and as a number in another one.
there are no naming rules, so some JSON objects may provide weird names, containing whitespaces, line feed or non-printable characters.
the actual text format is not defined. Usually text is transferred as UTF-8 or Unicode. If the transport is not clear, the 7-bit ASCII format with escaped Unicode should be the preferred choice.

Usually providers for JSON formatted data try to avoid the issues described above. If a JSON text with such issues has to be parsed by the Ventuz JSON Parser node you might face problems gathering the correct information from that object!

JSON Parser Node

The Ventuz JSON Parser node provides three properties. Access to the parsed data is provided by properties that are created by editing the custom model of the JSON Parser node.

Inputs:
- Json (JsonObject): Receives the JsonObject (or text) to be parsed.
- Index (integer): The current index of the parsed object that has to be transferred to the output properties.
Outputs:
- Count (integer): the number of elements in the parsed JSON object.
- ... (all types): Custom Model output properties

The type JsonObject is an internal Ventuz type. This type can be converted from and to string via binding. Any node that provides a string can be bound to the Json input. Any Json output can be bound to any node that accepts JsonObjects or strings.

These different types of JSON text can be parsed:

A single unnamed JSON value.
A single unnamed array of JSON values.
A single unnamed JSON object.
A single array of JSON objects.

The context menu of the JSON Parser node and the Property Editor show an Update verb, which automatically creates the desired custom model output properties based on the current JSON text assigned to the Json property. The common design workflow is to assign an example JSON text to the node and select Update and let Ventuz create the correct properties for you. If you prefer to create your own custom model you can use the Custom Model Editor.

The properties defined in the custom model are either the Value property (case 1 and 2) or the names of the first JSON object in cases 3 and 4. In cases 1 and 3 the Count property will provide a 1 value, because there's only one element in the parsed object. In cases 2 and 4, Count provides the number of elements available in the arrays.

If the parser was unable to parse the text, the Count property will be 0 and the icon of the Parser node turns red. All output properties will output the default value of their type (false, null, zero)

The automatic update of the custom model can also recognize arrays of values. Some rules apply:

If all elements of the array are of the same simple type (booleans, numbers or strings), a Ventuz array of its corresponding type is created.
null is interpreted as type string
If all numbers are without a decimal point (.) they are treated as integer
If an array of numbers is mixed (integers and floating point numbers) it is treated as float (single)

Ventuz only handles 32-bit IEEE float numbers (single precision) and 32-bit integer numbers. Some JSON objects may provide large integers or number with a higher precision (64-bit or 128-bit). These numbers won't be parsed correctly! Try to parse them as string instead.

Chains of Parser nodes

Multiple JSON Parser nodes can be chained to parse nested JSON objects. If the first parser provides an output property of type JsonObject (or string) a secondary parser node can receive that object and output its values.

Creating JSON text

If a conversion back to text is required, you can either simply bind the JsonObject output to a string input property or use the Convert To Text node. The Convert To Text allows you to specify a format for the JsonObject (like number formats #.###) which controls the conversion.

The string conversion of a JsonObject supports two formats:

a ASCII: all non-ASCII characters are escaped as unicode (ä = \u00E4)
c COMPACT: all whitespaces and linefeeds are stripped.

The format can be specified in the convert to text node:

{0}               normal formatted JSON (default)
{0:a}             all ASCII compatible
{0:c}             compact - one line
{0:ac} or {0:ca}  ascii-compact

The Value0 binding must be of type JsonObject. This type is provided either the Json input property or any Json-object output property of the Json Parser node.

If a complete JSON object has to be constructed, please see JSON section in the Convert To Text page.