JSON Basics for Boomi


Overview

JSON stands for JavaScript Object Notation and is used as a data format. It is used to transmit data between a server and web application, as an alternative to XML.
 

Parts of the JSON data

Example of what it looks like:
{
  "firstName": "Jonathan",
  "lastName": "Freeman",
  "loginCount": 4,
  "isWriter": true,
  "worksWith": ["Spantree Technology Group", "InfoWorld"],
  "pets": [
    {
      "name": "Lilly",
      "type": "Raccoon"
    }
  ]
}


You'll notice it is only made up of mainly brackets, colons, commas, double quotes, and text. There is always the main { } around everything.

Keys and values - JSON is made up of keys and values, or key/value pairs. A key is always a string enclosed in quotation marks, usually describes what the value is. A value can be a string, number, boolean expression, array, or object. Keys are case sensitive. A key value pair follows a specific syntax, with the key followed by a colon followed by the value. Key/value pairs are comma separated. Let's take this example:

"height" : "64"

The key is "height" and the value is "64". In Boomi, height is the element's name and 64 is the element's value.
 
The value can be many things and they can be nested inside each other:
You can basically have any combination of values that you want. An array of objects where one of the object entry is an object with arrays in it, etc. 

Objects - an object is indicated by curly brackets. Everything inside of the curly brackets is part of the object. A value can be an object. So that means "person" and the corresponding object are a key/value pair,
{
  	"person" : {
  		"name" : "John",
        "birthday" : "1975-01-31",
        "height" : "67"
	}
}


The key/value pair "name" : "John" is nested inside the key/value pair "person" : { ... }. That's an example of a hierarchy in JSON data. An Object can have any combination of values inside of it, so it could have another object, string, number, etc as a value for a key/value pair. 

Arrays - the "worksWith" key has a square bracket to determine it is an array. The value is multiple strings this time. Each array element has to be the same thing. There can be an array of numbers, strings, objects, etc. 

{
  "firstName": "John",
  "lastName": "Doe",
  "loginCount": 7,
  "worksWith": ["Spantree Technology Group", "InfoWorld", "Test"]
}


Here is an example of an array of objects:

{
    "firstName": "John",
    "lastName": "Smith",
    "birthday": "1975-01-31",
    "spouse": {
        "firstName": "Mary",
        "lastName": "Smith"
    },
    "addresses": [
        {
            "description": "home",
            "street": "123 Peachtree Ln",
            "city": "Atlanta",
            "state": "GA",
            "postalCode": 30305
        },
        {
            "description": "work",
            "street": "456 Peachtree St",
            "city": "Atlanta",
            "state": "GA",
            "postalCode": 30305
        }
    ],
    "phoneNumbers": [
        {
            "description": "home",
            "number": "404-555-1234"
        },
        {
            "description": "mobile",
            "number": "678-555-1234"
        }
    ]
}


The key "addresses" is an array, denoted by the [ ] and inside are the objects denoted by { } and there are multiple objects, so they are separated by the comma. 
 

JSON Profiles

When building the JSON profile, there aren't many other options besides what kind of element type to choose. Your JSON profile can be as complicated or as simple as you'd like. The only other thing is a repeating array and absolute array. Repeating arrays repeat one kind of element and allow you to repeat once or unlimited times while absolute arrays allow for different kinds of elements but you have to define every instance and type of element in that absolute array in the same order the data is coming in. You only have to define the element(s) one time each in a repeating array. 

Repeating array of numbers: [1, 2, 3, 4]

Repeating array of objects: 

{
    "number": [{
            "upc": "123",
            "price": 1.99
        }, {
            "upc": "345",
            "price": 2.99

        }, {
            "upc": "456",
            "price": 5.99
        }
    ]
}


This is how the array of numbers would be defined in a profile, notice how there's only one simple element number. It is understood the repeating array has the same element so you only need to define it once. Which also means, if you are mapping to this array, your data needs to be in a repeating format too to map properly. 

User-added image

This is how the array of objects would look like defined in the profile,

User-added image
You shouldn't define the number object holding upc and price multiple times.

As for an absolute array, this is what one could look like 
Absolute array (contains different elements, number, string, object):
  
[
    1,
    “Orange Juice”, {
        "upc": 123,
        "price": 1.99
    },
    "name": "Alan"
]

They are in the array format but it's not a uniform type of value inside but made up of different value types. You might see these in legacy data that's been converted to JSON or these will always have a set number elements in the array in a specific order. The JSON profile would look like this,

User-added image
You will be allowed to add multiple Array Elements now for the glossary absolute array. 

You would need to define 3 array elements in the absolute array in the example above. If you wanted another string and object element to the absolute array, you'd have to define 5 separate array elements in the absolute array. If the profile is out of sync with the way the data has it, you will get errors related to element type. 

 

JSON Schemas

Like XML, JSON profiles can be created by import either of a direct JSON file or the Schema representing a JSON document.  More information on JSON Schemas can be found at the following site:

https://json-schema.org/