The JSON Parser and JSON Bundler actors allow you to parse or create data structures in the JSON (JavaScript Object Notation) format, which is often used on the web as a way to cleanly encapsulate bundles of data. This Knowledge Base article assumes you have a basic understanding of JSON. If you need to learn about JSON, please read this useful introduction.

You can download these plugins from our plugins page.

JSON Parser

To decode a JSON structure, you would pass a JSON text string to the 'json in' input. Upon receiving a new input, the 'elements' output will update to show you how many top-level elements were found. You will then want to set the 'selectors' input to specify how many selectors you would like to access, and finally enter the selector names in 'select 1', 'select 2', etc.

For example, this JSON string

{
    "first_name" : "Mark",
    "last_name" : "Coniglio",
    "employer" : "TroikaTronix"
}

Would be parsed by setting up the JSON Parser as follows:

Note the selector names in the 'select' inputs on the left (first_name, last_name, employer). When you enter a selector name, JSON Parser looks for an item with that selector label. If it finds it, the value for that item will be sent to the corresponding 'element' output.

When the source data is an array (i.e., enclosed by square brackets [ ] ) then you need to enter the index of that item in the 'select' input. For example:

[
    "Mark",
    "Coniglio",
    "TroikaTronix"
]

These indexes are zero-based, so you get the first element by using index 0, the second by using index 1, etc., as shown below.

If one of those elements is an "object" -- meaning it is a list enclosed by curly brackets (e.g., { and } ) then you would use a second JSON Parser to extract those values. For example, consider this JSON structure:

{
    "first_name" : "Mark",
    "last_name" : "Coniglio",
    "employer" : "TroikaTronix",
    "jobs" :
    {
        "job_1" : "bus boy",
        "job_2" : "programmer",
        "job_3" : "record producer"
    }
}

As you can see, the selector label "jobs" contains its own JSON structure. When you enter 'jobs' as a selector, the corresponding 'element' output will contain that sub-structure, and you can then use a second JSON Parser actor to access its individual elements.

You can also access an embedded element by using a string of selectors separated by colons. For example, the selector "jobs:job_1" will give you the element "job_1" inside of the list "jobs". 

JSON Bundler

The JSON Bundler accepts numeric or text input and bundles it into a valid JSON string. The JSON Bundler only accepts basic data types like number or strings; it will not accept stream data types like video, sound, or blobs. (You'll see a circle-slash cursor if you attempt to connect one of these types to the input.)

When you first add the JSON Bundler, it will look like this:

If you know you want your JSON Structure to consist of three elements, you would set the 'elements' input to 3.

Note the green dots to the left of the 'value' input properties. This means that the input is mutable; it will change its type to match the data type of the output property to which it is linked.

Here is an example of a three-element structure, with elements named 'name', 'age', and 'employer':Note that the order of the elements in the output string does not match the order specified at the input. The JSON Bundler sorts the elements in alphabetical order according to the selector name. That's why the order is 'age', 'employer', and 'name'.

You can add a JSON structure to another JSON structure by using two JSON Bundler actors. For example, here's a JSON Bundler that lists three jobs.

You could then take the output of that JSON Bundler, and use it as an input to a second JSON Bundler, using the selector label 'jobs'.

The resulting JSON text string, formatted to make it more readable, looks like this:

{
  "age": 99,
  "employer": "TroikaTronix",
  "jobs": {
    "job_1": "bus boy",
    "job_2": "programmer",
    "job_3": "record producer"
  },
  "name": "Mark Conigio"
}