JSON step

This step is available at Startup, Pro and Business pricing plans

JSON (JavaScript Object Notation) is a lightweight data format. JSON is the most popular data-interchange language—90% of all the APIs on the Internet interchange data in JSON format.

The example of data in JSON format:

{
  "firstName": "Ernest",
  "lastName": "Hemingway",
  "isGenius": "true",
  "books": [
    {
      "name": "The Sun Also Rises",
      "year": "1927"
    },
    {
      "name": "The Old Man and the Sea",
      "year": "1951"
    }
  ]
}

This step is made for:

• parsing JSON-data to objects (in order to process them);
• vice versa—composing JSON data from objects (usually, in order to send this piece of data to a third party system).

You can also use JavaScript SDK to handle JSON data

Setting up JSON schema

First and foremost, you need to setup JSON schema for parsing or composing. You can do it simply by copy-pasting example of your JSON-data into the field (the values may be any, only keys are matter).

The component will validate your JSON automatically—you won't be able to proceed in case of an error in scheme.

After setting up the scheme you can choose what are you going to do: to parse or to compose JSON.

Parsing JSON to fields and objects

First, you choose the field in object (type of json) where the step will get the JSON to parse.Then, you map json properties to the fields of the current object.

Parsing nested objects

If the property is object, you will have two options for parsing.

// example of object property – "book":
{
   "book": {
      "title": "Crime and Pinishment",
      "author": "Dostoevsky"
   }
}

Parsing nested objects. Option 1. Parsing to current object

You can fetch properties of object without creating new objects on Directual. Choose to current object in a subselect.

Parsing nested objects. Option 2. Parsing to a new object

You can map properties of object to the fields of a new object on Directual. Choose to other object in a subselect. On the right side you choose field type of link, a new object will be created (or of you map property to id field and such an object exists, it will be edited accordingly).

Parsing complex arrays

If the property is a complex array (an array of objects), you will have two options for parsing.

// example of complex array property – "books":
{
  "books": [
    {
      "name": "The Sun Also Rises",
      "year": "1927"
    },
    {
      "name": "The Old Man and the Sea",
      "year": "1951"
    }
  ]
}

Simple arrays (like ["1","2","3"]) can be parsed to string or array fields directly.

Parsing arrays of objects. Option 1. Parsing array to objects

If you choose to parse array property to objects, you will have to choose the destination field type of arrayLink. The step will create new objects and write array of IDs of these objects into the selected field.

In this option you configure mapping of child elements of the JSON array to child elements of arrayLink field.

Parsing arrays of objects. Option 2.1 Saving one element from the array as a separate JSON

You can pick one element from the JSON array and save it to a field type of JSON.

Parsing arrays of objects. Option 2.2 Saving one element from an array as a new object

You can pick one element from the JSON array and save it to a new object. In order to do that choose field type of link on the right side. The step will create new object and write ID of this object into the selected field.

Note, that you can combine any type of parsing.

Composing JSON from fields and objects

First, you choose the field in object (type of json) in which the composed JSON will be saved.Then, you map fields of the current object and json properties.

Note that here (only here) you can choose the fields of linked (like {{authorId.firstName}}) objects and paste them to the composed JSON:

Composing nested objects

If the field (on the left side) has a type of link, the json property will be nested object& You setup mapping of fields of the elements from linked object and properties of nested object property (which were set up in JSON Schema).

// example of object property to compose from linked object – "book":
{
   "book": {
      "title": "Crime and Pinishment",
      "author": "Dostoevsky"
   }
}

Composing complex arrays

If the field (on the left side) has a type of arrayLink, the json property will be array as well, with elements from this field. You setup mapping of fields of the elements from arrayLink and properties of array (which were set up in JSON Schema).

// example of complex array property to be composed – "books":
{
  "books": [
    {
      "name": "The Sun Also Rises",
      "year": "1927"
    },
    {
      "name": "The Old Man and the Sea",
      "year": "1951"
    }
  ]
}