Advertisement
Tools

Understanding JSON

by

JSON (JavaScript Object Notation, which I pronounce "Jason" and you can pronounce however you like) is a text-based data format that's designed to be human-readable, lightweight, and easy to transmit between a server and a web client. Its syntax is derived from JavaScript -- hence the name -- but it can be used in most languages, including AS3 and C#.


Arrays

If you've done much programming, you'll have come across arrays before: collections of items, each assigned to a specific integer.

In JSON, an array of the first six letters of the alphabet would be represented like this:

["a", "b", "c", "d", "e", "f"]

AS3 and JavaScript coders will find the above listing very familiar. It's similar to the C# way of defining an array, too.

As you can probably guess, the square brackets say "this is an array", and commas are used to separate different elements (note that there's no comma after the final element). Assuming the language in which you parse the JSON uses zero-based arrays (and how many languages don't, these days?), element 0 will be "a", 1 will be "b", 2 will be "c", and so on.

To make arrays easier to read, we'll often write them with extra newlines and indentation:

[
	"a", 
	"b", 
	"c", 
	"d", 
	"e", 
	"f"
]

Note that there's still no comma after the final element, so it now looks a bit odd.

We don't have to use strings as the elements of a JSON array; we can also use numbers, true, false, and null. There's no strict typing, which means you can mix the types of values you use in any given array. For instance, this is perfectly valid:

[
	"apple", 
	3, 
	912, 
	null,
	-7.2222202, 
	"#", 
	true,
	false
]

Note that you must use double quotes (") to surround all your strings; single quotes (') are not allowed. Yes, this is the case, even though JavaScript allows you to enclose strings in either type of quote. If you want to use double quotes inside JSON strings, use \" instead.


Objects

An array is a collection of items where each is assigned to a specific integer. An object is a collection of items where each is assigned to a specific string. The items are called values, and the strings used to identify them are called keys. Some programming languages call this kind of data structure a hash table or hash map.

We could represent people's ages in an object like so:

{ "Alan": 44, "John": 58, "Brian": 19, "Eliza": 4, "Jessie": 58 }

Curly braces say "this is an object", and -- as with arrays -- commas separate different elements. However, the elements are given in pairs, this time. It's easier to see if we add some newlines and indentation:

{ 
	"Alan": 44, 
	"John": 58, 
	"Brian": 19, 
	"Eliza": 4, 
	"Jessie": 58 
}

In each pair, a colon separates the key (which is a string) from the value (which, in this case, is a number). When we were making an array, we didn't need to specify which integer each element was assigned to (i.e. we only needed to specify the values and not the keys), because they were assigned based on the order in which they were written in the array.

Rather than request the second or fifth element, as you would when accessing an array, with an object you'll request the "Alan"th or "Eliza"th element.

To make things more confusing, objects also allow you to use strings as the values -- not just the keys. So you could have an object like this:

{ 
	"Activetuts+": "http://active.tutsplus.com/", 
	"Psdtuts+": "http://psd.tutsplus.com/", 
	"Nettuts+": "http://net.tutsplus.com/", 
	"Aetuts+": "http://ae.tutsplus.com/", 
	"Vectortuts+": "http://vector.tutsplus.com/", 
	"Audiotuts+": "http://audio.tutsplus.com/", 
	"Cgtuts+": "http://cg.tutsplus.com/", 
	"Phototuts+": "http://photo.tutsplus.com/", 
	"Webdesigntuts+": "http://webdesign.tutsplus.com/", 
	"Mobiletuts+": "http://mobile.tutsplus.com/"
}

This way, to retrieve the URL for a given Tuts+ site, you can request it using the name of the site as a key. However, the reverse isn't true -- you can't use "http://cg.tutsplus.com/" to retrieve "Cgtuts+".

The same rules about different types of quotes apply to objects as to arrays. Objects can also use strings, numbers, true, false, and null as values (but only strings as keys).


Nesting

Objects and arrays can also store other objects and arrays. This lets us create nested data structures; for example:

{ 
	"Activetuts+": { "url": "http://active.tutsplus.com/", "hasPremium": true },
	"Psdtuts+": { "url": "http://psd.tutsplus.com/", "hasPremium": true },
	"Nettuts+": { "url": "http://net.tutsplus.com/", "hasPremium": true },
	"Aetuts+": { "url": "http://ae.tutsplus.com/", "hasPremium": true },
	"Vectortuts+": { "url": "http://vector.tutsplus.com/", "hasPremium": true },
	"Audiotuts+": { "url": "http://audio.tutsplus.com/", "hasPremium": true },
	"Cgtuts+": { "url": "http://cg.tutsplus.com/", "hasPremium": true },
	"Phototuts+": { "url": "http://photo.tutsplus.com/", "hasPremium": true },
	"Webdesigntuts+": { "url": "http://webdesign.tutsplus.com/", "hasPremium": false },
	"Mobiletuts+": { "url": "http://mobile.tutsplus.com/", "hasPremium": false }
}

Let's see that with a little more whitespace:

{ 
	"Activetuts+": 
	{ 
		"url": "http://active.tutsplus.com/", 
		"hasPremium": true 
	},
	"Psdtuts+": 
	{ 
		"url": "http://psd.tutsplus.com/", 
		"hasPremium": true 
	},
	"Nettuts+": 
	{ 
		"url": "http://net.tutsplus.com/", 
		"hasPremium": true 
	},
	"Aetuts+": 
	{ 
		"url": "http://ae.tutsplus.com/", 
		"hasPremium": true 
	},
	"Vectortuts+": 
	{ 
		"url": "http://vector.tutsplus.com/", 
		"hasPremium": true 
	},
	"Audiotuts+": 
	{ 
		"url": "http://audio.tutsplus.com/", 
		"hasPremium": true 
	},
	"Cgtuts+": 
	{ 
		"url": "http://cg.tutsplus.com/", 
		"hasPremium": true 
	},
	"Phototuts+": 
	{ 
		"url": "http://photo.tutsplus.com/", 
		"hasPremium": true 
	},
	"Webdesigntuts+": 
	{ 
		"url": "http://webdesign.tutsplus.com/", 
		"hasPremium": false 
	},
	"Mobiletuts+": 
	{ 
		"url": "http://mobile.tutsplus.com/", 
		"hasPremium": false
	}
}

Each object contains two fields: one with the key "url" whose value is a string containing the URL of the site, and one with the key hasPremium whose value is a Boolean that's true if the site has a Premium section.

We're not restricted to having the exact same structure for each object in the JSON, though. For example, we could add an extra URL that points to the Premium program URL, but only for those sites who have one:

{ 
	"Activetuts+": 
	{ 
		"url": "http://active.tutsplus.com/", 
		"hasPremium": true,
		"premiumUrl": "http://tutsplus.com/Premium-program/active-Premium/"
	},
	"Psdtuts+": 
	{ 
		"url": "http://psd.tutsplus.com/", 
		"hasPremium": true,
		"premiumUrl": "http://tutsplus.com/Premium-program/psd-Premium/"
	},
	"Nettuts+": 
	{ 
		"url": "http://net.tutsplus.com/", 
		"hasPremium": true,
		"premiumUrl": "http://tutsplus.com/Premium-program/net-Premium/"
	},
	"Aetuts+": 
	{ 
		"url": "http://ae.tutsplus.com/", 
		"hasPremium": true,
		"premiumUrl": "http://tutsplus.com/Premium-program/ae-Premium/"
	},
	"Vectortuts+": 
	{ 
		"url": "http://vector.tutsplus.com/", 
		"hasPremium": true,
		"premiumUrl": "http://tutsplus.com/Premium-program/vector-Premium/"
	},
	"Audiotuts+": 
	{ 
		"url": "http://audio.tutsplus.com/", 
		"hasPremium": true,
		"premiumUrl": "http://tutsplus.com/Premium-program/audio-Premium/"
	},
	"Cgtuts+": 
	{ 
		"url": "http://cg.tutsplus.com/", 
		"hasPremium": true,
		"premiumUrl": "http://tutsplus.com/Premium-program/cg-Premium/"
	},
	"Phototuts+": 
	{ 
		"url": "http://photo.tutsplus.com/", 
		"hasPremium": true,
		"premiumUrl": "http://tutsplus.com/Premium-program/photo-Premium/"
	},
	"Webdesigntuts+": 
	{ 
		"url": "http://webdesign.tutsplus.com/", 
		"hasPremium": false 
	},
	"Mobiletuts+": 
	{ 
		"url": "http://mobile.tutsplus.com/", 
		"hasPremium": false
	}
}

We could even include an array of all the latest Premium tutorials for a given site (I'll just show Activetuts+ here, and limit it to a few Premiums, to save space):

{ 
	"Activetuts+": 
	{ 
		"url": "http://active.tutsplus.com/", 
		"hasPremium": true,
		"premiumUrl": "http://tutsplus.com/Premium-program/active-Premium/"
		"previousPremiums":
		[
			"http://tutsplus.com/join/",
			"http://active.tutsplus.com/tutorials/games/create-a-space-shooter-game-in-flash-using-as3http://tutsplus.com/join/",
			"http://active.tutsplus.com/tutorials/games/obscuring-and-revealing-scenes-with-as3http://tutsplus.com/join/",
			"http://active.tutsplus.com/tutorials/games/building-a-dynamic-shadow-casting-engine-in-as3http://tutsplus.com/join/",
			"http://tutsplus.com/join/"
		]
	},
	
	/** SNIP! **/
	
	"Mobiletuts+": 
	{ 
		"url": "http://mobile.tutsplus.com/", 
		"hasPremium": false
	}
}

An array makes sense for listing the Premiums, because I'm working under the assumption that any app which actually reads this data is just going to display a list of Premium tutorials, rather than needing to access them according to their name -- so we don't need to assign them each a string key.

We could take this even further:

{ 
	"Activetuts+": 
	{ 
		"url": "http://active.tutsplus.com/", 
		"premium":
		{
			"hasPremium": true,
			"premiumUrl": "http://tutsplus.com/Premium-program/active-Premium/",
			"previousPremiums":
			[
				{
					"title": "Create a Customizable Flash Quiz Application",
					"url": "http://tutsplus.com/join/",
				},
				{
					"title": "Create a Space Shooter Game in Flash Using AS3",
					"url": "http://active.tutsplus.com/tutorials/games/create-a-space-shooter-game-in-flash-using-as3http://tutsplus.com/join/",
				},
				{
					"title": "Obscuring and Revealing Scenes with AS3",
					"url": "http://active.tutsplus.com/tutorials/games/obscuring-and-revealing-scenes-with-as3http://tutsplus.com/join/",
				},
				{
					"title": "Building a Dynamic Shadow Casting Engine in AS3",
					"url": "http://active.tutsplus.com/tutorials/games/building-a-dynamic-shadow-casting-engine-in-as3http://tutsplus.com/join/",
				},
				{
					"title": "Animating the Envato Community Podcast",
					"url": "http://tutsplus.com/join/"
				}
			]
	},
	
	/** SNIP! **/
	
	"Mobiletuts+": 
	{ 
		"url": "http://mobile.tutsplus.com/", 
		"premium":
		{
			"hasPremium": false
		}
	}
}

Phew! If we wanted we could create objects that contain the names and profile URLs of each author of each Premium tutorial -- can you figure out the best way to do that?

Keeping arrays within arrays can be useful, too; particularly for gaming. This could be the current layout of a Tic-Tac-Toe board:

[
	[
		1,
		2,
		0
	],
	[
		0, 
		1,
		0
	]
	[
		0,
		2,
		1
	]
]

Not seeing it? Try removing some whitespace:

[
	[1,2,0],
	[0,1,0],
	[0,2,1]
]

1 is a nought, 2 is a cross and 0 is an empty space. Noughts win! And I'm sure you can see how something similar could be used for Battleships or Connect 4 or Minesweeper. For more info on nested arrays, check out my previous tutorial.


Using JSON with Different Platforms

Since JSON is so popular, there are parsers (tools and libraries that decode one programming language so that another can understand it) and generators (tools and libraries that do the opposite; encode one programming language into another) available for most programming languages. Just search [JSON parser (name of your language}]. I'll highlight a few that are relevant to Activetuts+ readers.


For Flash and AS3

The standard library for encoding and decoding JSON data in AS3 is the as3corelib; see my guide to using external libraries if you're not sure how to install it.

You can decode a JSON-formatted String to AS3 objects and arrays by passing it to com.adobe.serialization.json.JSON.decode(); the return value will be either an array or an object, depending on the JSON. If you pass false as a second argument, the decoder won't follow the JSON standard so strictly, so you can get away with sloppier formatting.

You can encode an AS3 object or array (which can contain nested objects and arrays) to a JSON string by passing it to com.adobe.serialization.json.JSON.encode(); the return value will be a String.

It's been announced that future versions of Flash will include native JSON parsing, so there'll soon be no need to use the as3corelib for that purpose.


For .NET (Including Silverlight)

To parse JSON, just add a reference to System.Json. Then:

#using System.Json;

decoded = JsonValue.Parse(jsonString);	//may be a JsonPrimitive, JsonArray, or JsonObject, depending on the JSON passed

To encode an object to a JSON string is a little more complicated. You must first create a data contract for the type of object you wish to encode; let's call ours Thing, and the actual object myThing. Then:

#using System.Runtime.Serialization.Json;

MemoryStream myStream = new MemoryStream();
DataContractJsonSerializer jsonEncoder = new DataContractJsonSerializer(typeof(Thing));
jsonEncoder.WriteObject(myStream, myThing);

myStream.Position = 0;
StreamReader sr = new StreamReader(myStream);

encoded = sr.ReadToEnd();

You can also use this method to decode a JSON string to a specific class of object:

#using System.Runtime.Serialization.Json;

myStream.Position = 0;
myOtherThing = ser.ReadObject(myStream);	//you should cast this as Thing

For more information, see the MSDN pages Working with JSON Data and How to: Serialize and Deserialize JSON Data.


For JavaScript (and thus HTML 5 apps)

You could just pass the JSON string to eval() in JavaScript, but this is a terrible security risk. Most modern browsers support a function JSON.parse(), which will parse a JSON string into JavaScript objects, and JSON.stringify(), which will turn a JavaScript object or array into a JSON string.

Douglas Crockford created a library for doing this in older browsers; it's available on github.


For Unity

There's a C# assembly called LitJSON which you can use in your Unity projects to parse and generate JSON. You can use this even if your project is written in JavaScript or Boo rather than C#.

To decode a Unity object to a JSON string:

#using LitJson;

string jsonString = JsonMapper.ToJson (myObject);

To encode a JSON string to a Unity object of type Thing:

#using LitJson;

Thing myThing = JsonMapper.ToObject<Thing> (jsonString);

The LitJSON Manual is great; I recommend reading that for more guidance.


For Other Languages

JSON.org has a long list of libraries for various different platforms and languages -- plus, you can search Google, as mentioned above ;)

That site also has some great visualizations of how JSON can be constructed, and plenty of detail going beyond what I've explained in this quick introduction. Check it out if you want to know more!

Related Posts
  • Game Development
    Implementation
    Write Once, Publish Everywhere With HaxePunk: Making a GamePreviewretinaimage
    You've probably had this experience before: you hear about an awesome game, but then you find out that it's only coming out on the one platform that you don't own. It doesn't have to be this way. In this tutorial, you will learn how to use Haxe to make a game in one development platform that can target multiple gaming platforms, including Linux, Mac, Windows, iOS, Android, and Flash.Read More…
  • Code
    PHP
    Setting Up a Local Mirror for Composer Packages With SatisComposer retina preview
    Installing all your PHP libraries with Composer is a great way to save time. But larger projects automatically tested and run at each commit to your software version control (SVC) system will take a long time to install all the required packages from the Internet. You want to run your tests as soon as possible through your continuous integration (CI) system so that you have fast feedback and quick reactions on failure. In this tutorial we will set up a local mirror to proxy all your packages required in your project's composer.json file. This will make our CI work much faster, install the packages over the local network or even hosted on the same machine, and make sure we have the specific versions of the packages always available.Read More…
  • Code
    Android SDK
    Consuming Web Services with kSOAPEd4e2 preview image@2x
    In this tutorial, you'll learn how to consume web services using the popular kSOAP library in an Android application. kSOAP is a reputable library loved by developers who have the need to parse WSDL (Web Service Definition Language) and SOAP (Simple Object Access Protocol) messages.Read More…
  • Code
    JavaScript & AJAX
    JavaScript ObjectsCover
    In JavaScript, objects are king: Almost everything is an object or acts like an object. Understand objects and you will understand JavaScript. So let's examine the creation of objects in JavaScript.Read More…
  • Computer Skills
    App Training
    PopClip: Scripting ExtensionsPopclip400
    PopClip is a great utility program that, once you get used to it, is very hard to live without. This tutorial is going to show how to write a scripting extension by making an example extension.Read More…
  • Code
    Articles
    Web Assets - Tips for Better Organization and PerformanceWeb assets retina preview
    Remember back to when we had to spend a lot of time optimizing our project's assets (images, CSS, etc..)? Well today, users have a much faster Internet connection and it appears that we can afford to use bigger images or bigger flash files with a lot of video and pictures inside. However, with the rise of mobile development, we are again back in that same situation. It is extremely important to create well optimized sites, so that we have faster applications, which download less content and respond immediately. Read More…