4.3.4.4. JSON

Introduction

JSON (JavaScript Object Notation) is a lightweight text-based open standard designed for human-readable data interchange. It is derived from the JavaScript scripting language for representing simple data structures and associative arrays, called objects. Despite its relationship to JavaScript, it is language-independent, with parsers available for many languages. JSON format is often used for serializing and transmitting structured data for web applications.

Below is a sample of JSON file:

{
    "first_name": "John",
    "last_name": "Smith",
    "is_alive": true,
    "age": 27,
    "address": {
         "street_address": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postal_code": "10021-3100"
    },
    "phone_numbers": [
        { "type": "home", "number": "212 555-1234" },
        { "type": "office", "number": "646 555-4567" }
    ],
    "children": [ "Catherine", "Thomas", "Trevor"],
    "spouse": null
}	

 

You can learn more about JSON on Wikipedia or on json.org.

Configure in Babelway

To create your JSON MessageDefinition in the Babelway platform, you just need to select the JSON format, and provide a sample of your format.

The system will automatically create the tree that reflects your message. For example, on the sample shown above, it would provide the following result.

As usual, you may always manipulate your MessageDefinition afterwards, like adding other fields that were not in your initial sample, adding validations, ...

Data typing

JSON supports 3 primitive data types : strings, numbers and booleans.

It is important for the system to know the expected type in the output JSONs, because strings must be enclosed with double quotes ("), while numbers and boolean may not be. See example below.

{
    "name": "John",
    "is_alive": true,
    "age": 27
} 

Babelway will rely on the validation type that you defined for the field to take this decision. It is therefore important to define this information properly.

Also, for structural nodes, Babelway will consider elements X as arrays if they only have sub-elements named XElement, and as normal Objects in all other cases. You may therefore not change the name for the array elements.

Legacy

All of the above information is related to the current version of JSON support in Babelway. You don't have to care with it, but you can check this by looking at the read-only version property, whose value should be 2.

If you are using Babelway since a long time, you could still have JSON MessageDefinitions related to the version 1 (version field will contain "1", or have no value).

The main difference between versions 1 and 2 is that version 1 was using many technical nodes in the tree definition to code the type information. These nodes were attributes named "class" or "type". All of these attributes were making the tree very difficult to read or manipulate. For example, here is what version 1 was creating for the same sample as shown above.

You can easily migrate to the V2 by clicking on the "Migrate to V2" action button.

We believe that V2 is much better and easier to use in all cases. Therefore, we highly recommend that you migrate on V2 when you work on some old JSON MessageDefinition.

Also, the migration should be safe and will preserve anything that you did related to this MessageDefinition : 

• Every tree manipulation (addition, renaming or deletion of nodes).
• The name and uids of every element.
• All the validations that you could have added.
• All the mappings that you have done with this MessageDefinition.

The only thing that will happen is that all of these type and class attributes will disappear. You could only have problems if you have made some special formulas using them (what is normally not done by anybody).

Also, it would be safe even in case of conflicting information. For example, it can happen if you add manually added a type validation on some field (ex: Integer), but that the type attribute was providing a contradictory information (ex: Boolean). In that case, the system will just mention the error, and refuse to do the migration, unless you fix the type.