JSON Guide

What is JSON?

JSON stands for JavaScript Object Notation. JSON is a 'data interchange language' that can be used to represent practically any data structure in a single string of text.

The purpose of JSON is to provide a simple, powerful and consistent scheme that can be used to transfer pretty much any data structure from one place to another as a single string of text.

What does it look like?

Let's have a quick look at a simple piece of JSON encoded data:

{"manufacturer":"Porcshe","model":"Boxter S","top_speed":169,"tiptronic":true}

It is not important if JSON is split over many lines, so let's rewrite the above code in a more friendly format:

{
  "manufacturer":"Porcshe",
  "model":"Boxter S",
  "top_speed":169,
  "tiptronic":true
}

So do we have here? First of all, we are defining an 'object'. An object is defined when we have the { ... } characters. Inside an object we can define 'attributes' (also called 'members'). In our case, we have defined four attributes: "manufacturer", "model", "top_speed" and "manual_shift". Each attribute must have a 'value'. Importantly after each attribute key/value pair and before the next one, we must use a ',' comma character. Note that the final attribute within an object does not have a trailing ',' character. The next section will explain more about the values these attributes may possess.

What types of data can be represented with JSON?

Text (Strings of arbitrary text)

To represent a string of text, the text must be enclosed in double quotes. If your text also includes double quotation marks, these must be 'escaped' using the '\' (backslash) character just before the quotation mark. The following code sample demonstrates this:

{"description":"A two seater German sports car made by the \"Porsche AG\" company."}

Numeric values

To represent a numeric value we omit the double-quotation used with strings. The following code sample demonstrates some representations of numbers:

{
  "my_age":31,
  "year_of_birth":1979,
  "PI":3.14159265,
  "speed_of_light_ms":+3E8
}

Boolean values (true and false)

To represent a Boolean value (a type of data that represents either 'true' of 'false') we simply use either the word 'true' or 'false' (but without any quotations). The following code sample demonstrate this:

{"batteries_included":false,"currently_in_stock":true}

Object values

We mentioned earlier that an 'object' can be defined with the { ... } syntax. However, wherever we can have a string or numeric value, we can also define an object. We can see in the following code sample that the value of the 'features' attribute is infact another object:

{
  "manufacturer":"Porsche",
  "model":"Boxster S",
  "features":{
               "satellite_navigation":true,
               "traction_control":true,
               "music_system":"CD/Radio Stereo",
               "paint_options":["metallic", "matte"]
             }
}

Array values (lists of items)

Strings, booleans and number are essential, but most real-world applications require the ability to represent a list of items. An array is defined by using the [ ... ] characters. The following code sample demonstrates some simple arrays:

{
  "hobbies":["fishing","golf","full contact poetry"],
  "good_wine_years":[2001,2003,2005],
  "combination":["foo", 123, false, ["an array within an array", "json is very powerful"] ]
}

A complete example

The code sample below demonstrates all structural features of JSON

{
  "name":"Toms Yo-Yo Shop",
  "address":{
              "street":"123 some road",
              "area":"sol",
              "city":"madrid",
              "country":"spain"
            },
  "products":[
               {"model":"#0001","no_in_stock":10, "on_offer":true, "desc":"a great starter round yoyo."},
               {"model":"#0002","no_in_stock":142, "on_offer":false, "desc":"perfect for practising."},
               {"model":"#0003","no_in_stock":0, "on_offer":false, "desc":"a competetion grade yoyo."}
             ]
}

JSON and LiveDirectory profiles

Hopefully you have learnt everything you need to know to design really good LiveDirectory data profiles. Of course, if you have any questions please feel free to contact us.