Welcome to another BoxLang quick tip - today I'm going to focus on working with JSON in BoxLang. Now, as you can probably guess, JSON is natively supported and supports what you would expect, going to and from JSON, but there's some particularities of the support that may interest you, so I've dug into it. As with my other quick tips, you can skip to the video version at the bottom if you prefer.

The Basics

Converting data to JSON can be done two ways, either via the built in function (BIF) jsonSerialize or the member function toJSON. There's no difference here, just use what makes sense for you:

name = "Raymond";
age = 52;
hobbies = ["beer","books","movies","video games","cats"]

// going TO json...
println("Testing serialization of variables:");
println(jsonSerialize(variables));
println('-'.repeat(80));
println(variables.toJSON());

As a reminder, variables is a scope in BoxLang.

Going from JSON can also be done two ways, either via jsonDeserialize or fromJSON:

println("Testing deserialization of JSON:");
// coming FROM json...
json = variables.toJSON();
newData = jsonDeserialize(json);
println(newData);
println('-'.repeat(80));
newData = json.fromJSON();
println(newData);

This is all pretty simple and straightforward, but you can test it yourself below:

Queries are Different...

So far so good. Queries in BoxLang serialize a bit differently than you may expect. This is based on past behavior in ColdFusion and represent the 'special' nature of queries as a proper data type in the language. Let's look at an example. First, here's our query:

people = queryNew("name,age,rank", "varchar,integer,varchar", [
	{"name":"Raymond Camden", "age": 52, "rank":"nerd"},
	{"name":"Jacob Camden", "age": 25, "rank":"uber nerd"},
	{"name":"Susie Smith", "age": 46, "rank":"jedi"},
	{"name":"Carol Green", "age": 63, "rank":"samarai"},

]);

When you convert this to JSON, you can pass an argument to define how it's serialized. There's two values, row and column, with row being the default. Here's how the JSON looks when using row:

{
	"columns": [
		"name",
		"age",
		"rank"
	],
	"data": [
		[
			"Raymond Camden",
			52,
			"nerd"
		],
		[
			"Jacob Camden",
			25,
			"uber nerd"
		],
		[
			"Susie Smith",
			46,
			"jedi"
		],
		[
			"Carol Green",
			63,
			"samarai"
		]
	]
}

As you can see, you get a value representing the columns of the query and then a data array where each element itself is an array of values that match the same order of columns.

To use the column format, you would pass it like so:

people.toJSON("column");

Which returns the information like so:

{
	"rowCount": 4,
	"columns": [
		"name",
		"age",
		"rank"
	],
	"data": {
		"name": [
			"Raymond Camden",
			"Jacob Camden",
			"Susie Smith",
			"Carol Green"
		],
		"age": [
			52,
			25,
			46,
			63
		],
		"rank": [
			"nerd",
			"uber nerd",
			"jedi",
			"samarai"
		]
	}
}

As you can see, each element in data now maps to a column with the value being an array of items for each row. You can see it for yourself below:

I'm not a fan of this output, but as I said, it matches how ColdFusion serialized queries so I get it. Luckily, it's also really trivial to use another format. Query objects have a member function, toArrayOfStructs, that converts the query object to, wait for it... an array of structs. I much prefer this 'shape' and even if I'm not using JSON will add this to my code getting database information. I could use this with the people query like so:

people.toArrayOfStructs().toJSON()

You can try this below:

Validating JSON

You can also check if a string is valid JSON first with isJSON:

x = ["foo","moo","goo"];

println("is x itself json? #isJson(x)#");

j = x.toJSON();
println("is j json? #isJson(j)#");

This works as expected - with the first check returning false and the second true:

Put Some Lipstick On It!

Finally, you can 'pretty' up your JSON printing with... jsonPrettify:

name = "Raymond";
age = 52;
hobbies = ["beer","books","movies","video games","cats"]

j = jsonSerialize(variables);
println(jsonPrettify(j));

Given the data above, you get this in your output:

{
  "hobbies" : [ "beer", "books", "movies", "video games", "cats" ],
  "name" : "Raymond",
  "age" : 52
}

Try it yourself below:

That's it. Let me know if you've got any questions, and enjoy the video version below: