JSON: the fundamentals

Welcome to our JSON series! In the next few articles, we’ll cover all the useful things you need to know to be able to efficiently use JSON data (and to now be scared of that word ever again).

Overview

Whenever you work with data from different web applications, such as our integrations, you’ll hear the term JSON thrown about a lot. And trust us - we know at the beginning it might be scary and hard to understand. But over the few articles, we’re going to walk you through what JSON actually is, how to create it, and then how to use it!

Why do you need to know it? Well, every time you use one of our integration functions, the data you get back is JSON - so seriously, get a cup of tea :tea: and have a read :books: .

What is it?

JSON (you don’t really need to know what that stands for) is a standardized way for applications to communicate data across the web.

What does it look like?

At it’s most basic, JSON looks like this:

{ /*starts and ends with curly braces*/
    "key": "value", /*If it's not the final item, it ends with a comma */
    "anotherKey": "anotherValue" /* The final item doesn't need a comma */
}

What’s really important for you to remember here is this: JSON is made up of keys and values. You’ve actually used this structure a lot in your life - every single time you’ve used a dictionary.

The word you look up in the dictionary is the key.
The definition you get in the dictionary is the value.

Pretty easy right?

What data can we send?

Just have a look:


{
    "strings": "JSON is easy", /* Strings are pretty much anything that's not a number or a boolean. */
    "dates": "2020-01-01", /* Dates are just strings in JSON. */
    "numbers": 42,
    "booleans": true,
    "nothing": null,
    "objects": { "key": "value"}, /* We'll talk about objects in a moment */
    "arrays": [0,1,2,3,4,5] /* We'll cover arrays after objects */
}

Notice that the key is always surrounded by quotation marks, and if the value is a string (so that can be a word, a date, a URL - anything that’s not a number, boolean, object, or an array), it also needs to be in quotation marks. This is really important - make sure you note it down ;).

JSON Objects

Another things you’ll hear a lot is something called JSON objects. If we keep thinking about a physical dictionary, then the entire dictionary is an object (with the book covers being the curly braces).

{ /* Objects start an end with curly braces */
    "some_key": "I'm it's value!"
}

And yes - before you ask, the first example we showed you was actually a JSON object already!

Nested Objects

Sometimes (or rather, very often) you’ll see that keys have objects as their values (so, kind of like a chapter in a book). This is called a nested object. If you look at the example below, you’ll see that the value or address is another object.

{
    "company": "Apple",
    "domain": "apple.com",
    "address": {
                "street address": "1 Infinite Loop",
                "city": "Cupertino",
                "state": "California",
                "country": "United States"
              }
}

Nested objects are often used when we want to store more than one value in a key. In the example above, we want to store all the separate elements of an address separately in the address key (though, now it can also be called the address object because, well, the value of address is now an object).

:bulb: Parents and Children
Whenever you see nested objects, you’ll also hear people talking about parents and children. What does that mean?
Well it’s simple: address is the parent of street address, city, state, and country (its children).
Why do you need to know this? Well, when we use JsonPath to navigate through JSON to get certain data, we often use these terms - it’s just easier.

Counting things in JSON

OK, now something that we really have to cover is how counting works in JSON - and yes, this may shock you to your core: the first element of any object (or array) is actually zero. Why? Well, this comes from programming, and we just have to accept it.

{
    /* 0 */ "Company": "Apple",
    /* 1 */ "Domain": "apple.com",
    /* 2 */ "Address": {
                "street address": "1 Infinite Loop", /* 0 */
                "city": "Cupertino", /* 1 */
                "state": "California", /* 2 */
                "country": "United States" /* 3 */
              }
}

As you can see, as soon as we get into another object, the count starts again from zero.

JSON arrays

Now that we know a little about what objects and nested objects are (again, think of it as book covers and chapters), we need to cover one more thing: arrays.

{
  "company": "dashdash",
  "offices": "Berlin, Porto", /* Normal string */
  "employees": ["Hady", "Nadja", "Sourabh", "Dom"] 
   /* Employees is an array - we can tell because it has square brackets. */
  /* Each item in the array has to be separated with a comma. */
}

Arrays let you store more than one value in a key that you can actually access individually. If you look at the example above, you’ll see that we have two keys (offices and employees) that “technically” have more than one value stored.

However, for computers, offices only has one value, because well, it’s just one string "Berlin, Porto". If you wanted to get the first item in that list (remember, that would be 0 for Berlin), you can’t - you’d always get the entire string "Berlin, Porto".

Now arrays let the computer know that there are separate values stored. In other words, a computer understands that "Hady" and "Nadja" are separate values of employees. And thanks to this, we can actually get each item (employee )in that array (employees).

Arrays and objects

Arrays can store the same data as a JSON object, which includes other objects! Why? Well, say you have a list of companies in an array (Apple and dashdash), and for each of those companies, you want to store some information. Well, in that case, it makes sense that you have an array, and for each company in that array, you’d have an object that has all that information.
Have a look at the example below, and things will get a little clearer.

{
   "companies":[ /* The company key has an array of companies */
      {
         "Company":"Apple", /* The first item in the array*/
         "Domain":"apple.com",
         "Address":{
            "street address":"1 Infinite Loop",
            "city":"Cupertino",
            "state":"California",
            "country":"United States"
         }
      }, /* The comma separats the first item from the second one. */
      {
         "Company":"dashdash", 
         "Domain":"dashdash.com",
         "Address":{
            "street address":"Am Märchenbrunnen 5",
            "city":"Berlin",
            "state":"Berlin",
            "country":"Germany"
         }
      }
   ]
}

And don’t worry if at the moment this seems a little confusing or you can’t see the application of it. We’ll cover some real-world examples in an upcoming article. For now, it’s just important that you know that this is possible :slightly_smiling_face:.

Teaser Example

When will you use this? All the time! We’ll cover this in-depth in our next article, but to give you a little taste, let’s have a look at a simple table in dashdash:

The keys are the table headers, and the values are each individual cell in a row. In one of the cells we have an array (as you can see in the data explorer side panel).

Now, say we want to send all this data somewhere - we need to convert it into JSON. Luckily for us, that’s something that dashdash does out of the box. We simply use the RANGE2JSON() to convert our table into a JSON array:

As you can see, each object in the array automatically has the same keys (the table headers), and it’s just the values that change (the individual cells of a row).

Summary

Right, so after reading this part of the series, you know what JSON is, what data you can send, what are objects and nested objects, arrays, and how to count all these things.

In our next few articles, we’ll take your through:

  • how to construct your own JSON in dashdash
  • how to use the data explorer to navigate data
  • how to navigate data using JsonPath

And once again - just to reiterate: don’t worry if you’re a little lost still, you’ll soon be a JSON expert and wonder why it ever was a mystery!

Until next time, keep building :rocket: !

2 Likes