Xojo Documentation Xojo Documentation

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. JSON is not as verbose as XML and is often used for Internet and web data communication because its data files are smaller.

Xojo has two ways to deal with JSON. The first is to use the methods in the Xojo.Data namespace: ParseJSON and GenerateJSON. You use Xojo.Data.ParseJSON to parse JSON text into Dictionaries and Arrays. And you can use Xojo.Data.GenerateJSON to create JSON from Dictionaries and Arrays.

Alternatively you can use the JSONItem class in desktop, web and console projects. With the JSONItem class, you can manage data similarly to Dictionaries or Arrays.

Use Xojo.Data.ParseJSON and Xojo.Data.GenerateJSON for iOS apps.

Here is an example of a JSON document that describes three fictional baseball teams (Seagulls, Penguins and Crows):

[
    
    {
        "players":
        [
            
            {
                "Name":"Bob",
                "position":"1B"
            },
            
            {
                "Name":"Tom",
                "position":"2B"
            }
        ],
        "Team":"Seagulls"
    },
    
    {
        "players":
        [
            
            {
                "Name":"Bill",
                "position":"1B"
            },
            
            {
                "Name":"Tim",
                "position":"2B"
            }
        ],
        "Team":"Pigeons"
    },
    
    {
        "players":
        [
            
            {
                "Name":"Betty",
                "position":"1B"
            },
            
            {
                "Name":"Tina",
                "position":"2B"
            }
        ],
        "Team":"Crows"
    }
]

This JSON example has a lot of white space to make it easier to read. Without all this white space, the JSON is much smaller:

[{"players":[{"Name":"Bob","position":"1B"},{"Name":"Tom","position":"2B"}],"Team":"Seagulls"},
{"players":[{"Name":"Bill","position":"1B"},{"Name":"Tim","position":"2B"}],"Team":"Pigeons"},
{"players":[{"Name":"Betty","position":"1B"},{"Name":"Tina","position":"2B"}],"Team":"Crows"}]

This JSON is organized as an array (indicated by the "[" that starts the JSON. There are 3 JSON objects in the array. Each JSON object consists of the key "Team" with the value being the name of the team and the key "players" with the value being another array consisting of JSON objects that contain players and their positions.

Using JSONItem

JSONItem is works with desktop, web and console projects.

Creating JSON Data

To create the JSON data shown above you first create JSONItem objects to hold everything:

Dim teams As New JSONItem
Dim team, player As JSONItem

Now you can populate the data for each team. This is how you populate the first team:

// Add Seagulls team
team = New JSONItem
team.Value("Team") = "Seagulls"
teams.Append(team)

// Add players
Dim seagullPlayers As New JSONItem

// Bob
player = New JSONItem
player.Value("Name") = "Bob"
player.Value("position") = "1B"
seagullPlayers.Append(player)

// Tom
player = New JSONItem
player.Value("Name") = "Tom"
player.Value("position") = "2B"
seagullPlayers.Append(player)

// Add players to the team
team.Value("players") = seagullPlayers

// Do the same thing for the next two teams:

// Add Pigeons team
team = New JSONItem
team.Value("Team") = "Pigeons"
teams.Append(team)

// Add Players
Dim penguinPlayers As New JSONItem

// Bill
player = New JSONItem
player.Value("Name") = "Bill"
player.Value("position") = "1B"
penguinPlayers.Append(player)

// Tim
player = New JSONItem
player.Value("Name") = "Tim"
player.Value("position") = "2B"
penguinPlayers.Append(player)

// Add players to the team
team.Value("players") = penguinPlayers

// Add Crows team
team = New JSONItem
team.Value("Team") = "Crows"
teams.Append(team)

// Add Players
Dim crowPlayers As New JSONItem

// Betty
player = New JSONItem
player.Value("Name") = "Betty"
player.Value("position") = "1B"
crowPlayers.Append(player)

// Tina
player = New JSONItem
player.Value("Name") = "Tina"
player.Value("position") = "2B"
crowPlayers.Append(player)

// Add players to the team
team.Value("players") = crowPlayers

Now all the JSON data is created. You can convert this to a string to save (using a TextOutputStream) or to display. This code displays the JSON data in a Text Area:

JSONArea.Text = league.ToString

Loading JSON Data

JSON data can also be parsed and loaded using the JSONItem class. Presuming you have the above JSON text assigned to a Text constant in your project (called kBaseballJSON) you can parse it with this code:

Dim teams As New JSONItem
teams.Load(kBaseballJSON)

With the data in a JSONItem, you can now parse it for display. You loop through all the teams, displaying them and then for each team display its players.

For t As Integer = 0 To teams.Count - 1
Dim team As JSONItem = teams.Value(t)
TextArea1.AppendText(team.Value("Team") + EndOfLine)

Dim players As JSONItem = team.Value("players")
For p As Integer = 0 To players.Count - 1
Dim player As JSONItem = players.Value(p)
TextArea1.AppendText("--->" + player.Value("Name") + _
" (" + player.Value("position") + ")" + EndOfLine)
Next
Next

This code loops through the JSON array, displaying each team name. For each team, it then gets the array of players and displays their names and positions.

Using Xojo.Data

Creating JSON Data

To create the JSON data shown above you first create Xojo.Core.Dictionary objects to hold everything:

Dim teams(), team, player As Xojo.Core.Dictionary

Now you can populate the data for each team. This is how you populate the first team, Seagulls:

// Add Seagulls team
team = New Xojo.Core.Dictionary
team.Value("Team") = "Seagulls"
teams.Append(team)

// Add players
Dim seagullPlayers() As Xojo.Core.Dictionary

// Bob
player = New Xojo.Core.Dictionary
player.Value("Name") = "Bob"
player.Value("position") = "1B"
seagullPlayers.Append(player)

// Tom
player = New Xojo.Core.Dictionary
player.Value("Name") = "Tom"
player.Value("position") = "2B"
seagullPlayers.Append(player)

// Add players to the team
team.Value("players") = seagullPlayers

Do the same thing for the next two teams:

// Add Pigeons team
team = New Xojo.Core.Dictionary
team.Value("Team") = "Pigeons"
teams.Append(team)

// Add Players
Dim penguinPlayers() As Xojo.Core.Dictionary

// Bill
player = New Xojo.Core.Dictionary
player.Value("Name") = "Bill"
player.Value("position") = "1B"
penguinPlayers.Append(player)

// Tim
player = New Xojo.Core.Dictionary
player.Value("Name") = "Tim"
player.Value("position") = "2B"
penguinPlayers.Append(player)

// Add players to the team
team.Value("players") = penguinPlayers

// Add Crows team
team = New Xojo.Core.Dictionary
team.Value("Team") = "Crows"
teams.Append(team)

// Add Players
Dim crowPlayers() As Xojo.Core.Dictionary

// Betty
player = New Xojo.Core.Dictionary
player.Value("Name") = "Betty"
player.Value("position") = "1B"
crowPlayers.Append(player)

// Tina
player = New Xojo.Core.Dictionary
player.Value("Name") = "Tina"
player.Value("position") = "2B"
crowPlayers.Append(player)

// Add players to the team
team.Value("players") = crowPlayers

Now all the JSON data is created. You can convert this to Text to save (using a TextOutputStream) or to display by using the GenerateJSON method. This code displays the JSON data in a Text Area:

TextArea1.Text = Xojo.Data.GenerateJSON(teams)

Loading JSON Data

To load JSON data you use the ParseJSON method. Presuming you have the above JSON text assigned to a Text constant in your project (called kBaseballJSON) you can parse it with this code:

Dim teams() As Auto = Xojo.Data.ParseJSON(kBaseballJSON)

With the data now loaded you can loop through it for display.

For Each team As Xojo.Core.Dictionary In teams
TextArea1.AppendText(team.Value("Team") + EndOfLine)
Dim players() As Auto = team.Value("players")
For Each player As Xojo.Core.Dictionary In players
TextArea1.AppendText("--->" + player.Value("Name") + _
" (" + player.Value("position") + ")" + EndOfLine)
Next
Next

This code loops through the JSON array, displaying each team name. For each team, it then gets the array of players and displays their names and positions.

Extending the File Format

Much like XML, you can extend your JSON format fairly easily.

For example, if you wanted to update the format to add a “coach” for each team, you can easily do so when the file is saved and you can modify any loading code to only process the “coach” if it exists.

In the saving code, add a new value after each team JSONItem is created, such as this:

team.Value("Coach") = "Coach Mark"

With this change, create new JSON data and display it using the existing loading code. The JSON displays properly, but the new coach value is ignored. You have just extended your JSON data format without breaking its ability to be loaded.

Of course, you’ll want to update the loading code so that it can display the coach. To do that, in the loading code above add this code after the team name is displayed to check if there is a Coach value in the JSON and display it if it is there:

If team.HasName("Coach") Then
TextArea1.AppendText(team.Value("Coach") + EndOfLine)
End If

See Also

JSONItem, Xojo.Core.Dictionary classes; Xojo.Data.GenerateJSON, Xojo.Data.ParseJSON methods UserGuide:Framework topic