Reading and writing data in JSON Format

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 ParseJSON to parse JSON text into Dictionaries and Arrays. The second is to use GenerateJSON to create JSON from Dictionaries and Arrays.

Alternatively you can use the JSONItem class which you can manage data similarly to Dictionaries or Arrays.

Use ParseJSON and 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

Creating JSON data

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

Var teams As New JSONItem
Var 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.AddRow(team)

' Add players
Var seagullPlayers As New JSONItem

' Bob
player = New JSONItem
player.Value("Name") = "Bob"
player.Value("position") = "1B"
seagullPlayers.Add(player)

' Tom
player = New JSONItem
player.Value("Name") = "Tom"
player.Value("position") = "2B"
seagullPlayers.Add(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.Add(team)

' Add Players
Var penguinPlayers As New JSONItem

' Bill
player = New JSONItem
player.Value("Name") = "Bill"
player.Value("position") = "1B"
penguinPlayers.Add(player)

' Tim
player = New JSONItem
player.Value("Name") = "Tim"
player.Value("position") = "2B"
penguinPlayers.Add(player)

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

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

' Add Players
Var crowPlayers As New JSONItem

' Betty
player = New JSONItem
player.Value("Name") = "Betty"
player.Value("position") = "1B"
crowPlayers.Add(player)

' Tina
player = New JSONItem
player.Value("Name") = "Tina"
player.Value("position") = "2B"
crowPlayers.Add(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 with the Load method

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

Var 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
  Var team As JSONItem = teams.Value(t)
  TextArea1.AddText(team.Value("Team") + EndOfLine)

  Var players As JSONItem = team.Value("players")
  For p As Integer = 0 To players.Count - 1
    Var player As JSONItem = players.Value(p)
    TextArea1.AddText("--->" + 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 JSON Data

Creating JSON data

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

Var teams(), team, player As Dictionary

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

' Add Seagulls team
team = New Dictionary
team.Value("Team") = "Seagulls"
teams.Add(team)

' Add players
Var seagullPlayers() As Dictionary

' Bob
player = New Dictionary
player.Value("Name") = "Bob"
player.Value("position") = "1B"
seagullPlayers.Add(player)

' Tom
player = New Dictionary
player.Value("Name") = "Tom"
player.Value("position") = "2B"
seagullPlayers.Add(player)

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

Do the same thing for the next two teams:

' Add Pigeons team
team = New Dictionary
team.Value("Team") = "Pigeons"
teams.Add(team)

' Add Players
Var penguinPlayers() As Dictionary

' Bill
player = New Dictionary
player.Value("Name") = "Bill"
player.Value("position") = "1B"
penguinPlayers.Add(player)

' Tim
player = New Dictionary
player.Value("Name") = "Tim"
player.Value("position") = "2B"
penguinPlayers.Add(player)

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

' Add Crows team
team = New Dictionary
team.Value("Team") = "Crows"
teams.Add(team)

' Add Players
Var crowPlayers() As Dictionary

' Betty
player = New Dictionary
player.Value("Name") = "Betty"
player.Value("position") = "1B"
crowPlayers.Add(player)

' Tina
player = New Dictionary
player.Value("Name") = "Tina"
player.Value("position") = "2B"
crowPlayers.Add(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 = GenerateJSON(teams)

Loading JSON data with the ParseJSON method

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

Var teams() As Variant = ParseJSON(kBaseballJSON)

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

For Each team As Dictionary In teams
  TextArea1.AddText(team.Value("Team") + EndOfLine)
  Var players() As Variant = team.Value("players")
  For Each player As Dictionary In players
    TextArea1.AddText("--->" + 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.AddText(team.Value("Coach") + EndOfLine)
End If

Sample projects

Examples/Communication/Internet/JSON Example
Examples/Text/FormatJSON
Examples/Text/JSONTree

Reading and writing data in JSON Format

Using JSONItem

Creating JSON data

Loading JSON data with the Load method

Using JSON Data

Creating JSON data

Loading JSON data with the ParseJSON method

Extending the file format

Sample projects

See also