I have received lots of requests to do a video on JSON for beginners. This video takes you through the basics of working with JsonObjects and the other data types in AL.
This is part of my AL for beginners series.
In this video, Erik provides a beginner-friendly introduction to working with JSON in AL (the programming language for Business Central). He walks through the four JSON data types available in AL — JsonObject, JsonArray, JsonToken, and JsonValue — and demonstrates how to both construct and read JSON structures using practical code examples.
What is JSON?
JSON stands for JavaScript Object Notation. It’s basically JavaScript’s way of describing an object in code, and it has become the standard way of handling complex data structures — especially coming out of the Node.js and JavaScript world. It has largely taken over as the default data interchange format in modern systems.
As Erik puts it: if you need to design a new file format for exchanging data with somebody else, you go JSON all the way. If you were to present CSV or XML these days, people would find that strange — everybody understands JSON.
The Structure of a JSON Document
A great example of a JSON file that every AL developer already has access to is the launch.json file in your Visual Studio Code workspace. Looking at any JSON document, the first two things you’ll notice are:
- Curly brackets
{ }— these denote a JSON Object - Square brackets
[ ]— these denote a JSON Array
These two structural elements, combined with key-value pairs, form the building blocks of every JSON document.
The Four JSON Data Types in AL
When you declare a variable in AL and look at the available JSON-related data types, you’ll find exactly four:
- JsonObject — represents a curly bracket
{ }structure - JsonArray — represents a square bracket
[ ]structure - JsonToken — a “wildcard” type that can hold any JSON element
- JsonValue — represents a primitive value (text, number, boolean, date, etc.)
Building JSON: Objects and Arrays
Creating a Simple JSON Object
A JsonObject corresponds to curly brackets. You can think of it like a record with fields. To create one and add members to it:
var
obj: JsonObject;
txt: Text;
begin
obj.Add('field', 'Youtube Video');
obj.Add('Price', 123.456);
obj.WriteTo(txt);
Message(txt);
end;This produces the following JSON output:
{"field":"Youtube Video","Price":123.456}Notice that the text value "Youtube Video" has quotes around it, while the decimal value 123.456 does not — this is standard JSON behavior where strings are quoted and numbers are not.
The Add method on JsonObject has 16 different overloads, allowing you to add values of many types: text, boolean, char, byte, option, integer, BigInteger, decimal, duration, date, and even other JSON objects or arrays.
Adding a JSON Array
A JsonArray corresponds to square brackets. Unlike objects, arrays don’t use named keys — they’re simply ordered lists of items. You can add objects, values, or a mix of both into an array:
var
obj: JsonObject;
item: JsonObject;
ja: JsonArray;
begin
obj.Add('field', 'Youtube Video');
obj.Add('Price', 123.456);
obj.Add('version', '0.2.0');
// Add objects to the array
item.Add('No', 20201110D);
ja.Add(item);
Clear(item);
item.Add('No', 20201112D);
ja.Add(item);
// Add plain values to the array
ja.Add(100);
ja.Add(200);
// Add the array to the main object
obj.Add('Items', ja);
end;This produces a JSON structure where Items is an array containing two objects (each with a No field) followed by two plain number values.
Reading JSON: Tokens and Values
Using JsonToken as a Wildcard
When you need to read data out of a JSON structure, you’ll primarily work with JsonToken and JsonValue. Every time you ask a JSON object for a member using Get, you receive a JsonToken.
Think of JsonToken as a wildcard or, in object-oriented terms, as the base class from which the other types inherit. Once you have a token, you can inspect what it actually is:
Token.IsArray()— checks if it’s an arrayToken.IsObject()— checks if it’s an objectToken.IsValue()— checks if it’s a value
Then you cast it to the appropriate type using the As functions: AsArray(), AsObject(), or AsValue().
Extracting and Converting Values
JsonValue is where you bridge the gap between JSON and Business Central’s native data types. Once you have a JsonValue, you can convert it to proper AL types:
AsText()AsCode()AsDate()AsDecimal()AsInteger()AsBoolean()AsTime()- …and more
Erik demonstrates this by storing dates in the JSON and then performing date calculations on the extracted values:
V := T3.AsValue();
Message('Value as Date %1', CalcDate('+5D', V.AsDate()));This takes the date value from the JSON, adds 5 days to it using CalcDate, and displays the result — proving that the conversion to a proper AL date type is fully functional.
Setting Values with JsonValue
JsonValue isn’t just for reading — you can also use it when building JSON. The SetValue method accepts all the standard AL data types:
var
v: JsonValue;
begin
v.SetValue(123.456);
obj.Add('Price', v);
end;This is functionally equivalent to obj.Add('Price', 123.456), but the JsonValue approach becomes very handy when you’re working with record references or other dynamic scenarios where the data type isn’t known at compile time.
Complete Source Code
Here’s the full page extension that Erik builds throughout the video, adding an action to the Sales Order card that demonstrates all four JSON data types:
pageextension 50144 "JSON" extends "Sales Order"
{
actions
{
addfirst(processing)
{
action(ShowJson)
{
Caption = 'Show JSON';
Promoted = true;
PromotedCategory = Process;
PromotedIsBig = true;
PromotedOnly = true;
ApplicationArea = all;
Image = Document;
trigger OnAction()
var
obj: JsonObject;
O2: JsonObject;
item: JsonObject;
Token: JsonToken;
T2: JsonToken;
T3: JsonToken;
ja: JsonArray;
v: JsonValue;
txt: Text;
begin
obj.Add('field', 'Youtube Video');
v.SetValue(123.456);
obj.Add('Price', v);
obj.Add('version', '0.2.0');
item.add('No', 20201110D);
ja.add(item);
clear(item);
item.add('No', 20201112D);
ja.add(item);
ja.Add(100);
ja.Add(200);
obj.Add('Items', ja);
if obj.Contains('Items') then begin
obj.get('Items', Token);
foreach T2 in Token.AsArray() do begin
if T2.IsObject() then begin
O2 := T2.AsObject();
O2.Get('No', T3);
if T3.IsValue() then begin
V := T3.AsValue();
Message('Value as Date %1', CalcDate('+5D', V.AsDate()));
end;
end;
end;
end;
//obj.WriteTo(txt);
//Message(txt);
end;
}
}
}
}A Note on Error Handling
Erik makes an important point about JSON compared to XML: JSON doesn’t have a built-in standard for schema validation the way XML does (with XSD). There are some implementations, but nothing standardized. This means that when you’re processing unknown or foreign JSON data, you need to do proper error handling. Use methods like Contains(), IsObject(), IsValue(), and IsArray() to verify that the data is structured the way you expect before attempting to process it.
Summary
Here’s a quick reference for the four JSON data types in AL:
- JsonObject — Curly brackets
{ }. The root of a JSON structure is typically always an object. UseAdd()to insert named key-value pairs,Get()to retrieve them, andContains()to check for existence. - JsonArray — Square brackets
[ ]. An ordered list of items without named keys. UseAdd()to append objects or values. - JsonValue — Represents primitive values. Primarily used when getting data out of JSON and converting it to native AL types (
AsDate(),AsDecimal(),AsText(), etc.), or when dynamically setting values withSetValue(). - JsonToken — The wildcard. Every time you retrieve something from a JSON structure, you get a token. Inspect it with
IsObject(),IsArray(), orIsValue(), then cast it withAsObject(),AsArray(), orAsValue().
With just JsonObject and JsonArray, you can construct most JSON structures you’ll ever need. Add JsonToken and JsonValue to the mix, and you have everything required to both build and parse JSON in Business Central AL development.
