Skip to main content

JSON structure and syntax

Eva Ferreira
  • Updated

JSON is the most widely used data format for APIs, and many API requests return information in a JSON response body. To create assertions and variables from a JSON response body, you need to write JSON paths. A JSON path extracts the specific information that you want from a response. For example, the following JSON path extracts a user ID from the response body.

Extracting an ID with JSON path

Extracting an ID with JSON path

JSON response bodies are made up of objects and arrays:

  • Objects are key-value pairs enclosed in { }. The value of a key-value pair may be a boolean, string, object, number, or array.
  • Arrays are ordered lists enclosed in [ ].

JSON response bodies can have deeply nested structures, with arrays within objects and objects within arrays. This article covers the syntax mabl supports for writing JSON paths against those structures, as well as the JSONPath features that mabl doesn’t support:

Keys

Use the keys in a JSON object to access specific values. For example, the JSON path for accessing the value true in the following JSON response body uses the key "authenticated" without the quotes: authenticated.

{
  "authenticated": true
}

Dot notation

If you need to extract a value in a nested object, the JSON path uses keys with dot notation. Dot notation means using literal periods to chain keys together, the same way you’d access a nested property in JavaScript. In the following response, the JSON path for accessing the value "email@example.com" is data.email.

{
  "data": {
    "id": 7,
    "email": "email@example.com",
    "first_name": "John",
    "last_name": "Smith",
    "image": "https://example.com/7/image.jpg"
  }
}

Square brackets

JSON path also uses square brackets to access values, most commonly to access an item in an array, but also to access keys that contain a dot.

Arrays

Arrays count from zero, so the first item in an array has an index of 0. For example, data[0] accesses "comedy" in the following response body.

{
  "statusCode": 200,
  "message": "Genres",
  "data": [
    "comedy",
    "horror",
    "noir",
    "action",
    "drama",
    "rom-com",
    "art house"
  ]
}

If you are accessing an object within an array of objects, you can combine keys with square brackets and dot notation to get at the right value. For example, the JSON path for accessing the unique ID of the third user is records[2].id.

{
  "records": [
    {
      "id": "rec25eKmUsfiieG2B",
      "createdTime": "2021-05-21T20:17:43.000Z",
      "username": "Jonny W"
    },
    {
      "id": "rec2dLF92AG8JTL0S",
      "createdTime": "2021-03-20T18:02:38.000Z",
      "username": "Debbie"
    },
    {
      "id": "rec5w5lUPzN8Yd3um",
      "createdTime": "2021-03-20T20:41:51.000Z",
      "username": "Louie"
    }
  ]
}

Unwrapped array responses

If the response body itself is an array, the path should start with the index in square brackets. In the following example, [1].name retrieves the value "Barb".

[
  {
    "name": "Ron",
    "occupation": "Physician"
  },
  {
    "name": "Barb",
    "occupation": "Nuclear physicist"
  }
]

Keys containing a dot

You can also use square brackets to access values for a key that contains a dot. In the following example, you would need to use the syntax [0]["person.Email"] to access Bob’s email address:

[
  {
    "person.Name": "Bob",
    "person.Email": "bob@example.com"
  }
]

Finding an object in an array by property value

To find an object in an array by property value, use one of the following approaches:

  1. If the array order is stable, use a predictable index.
  2. If the array order may change, you can write a post-request JavaScript snippet that finds the matching object. For example, the following snippet finds the record where the username equals “Debbie” and stores its id in a variable called “matched_id”:
const body = pm.response.json();
const match = body.records.find(r => r.username === "Debbie");
if (match) {
  pm.variables.set("matched_id", match.id);
}

Limitations

mabl’s JSON path parser supports the key, dot notation, and square-bracket syntax described above. It does not support the following JSONPath features from other tools:

  • Wildcards, such as records[*].id
  • The root selector $. at the start of a path
  • Recursive descent with ..
  • Filter expressions, such as records[?(@.username == "Debbie")].id. See the section on finding an object in an array by property value for workarounds.

Paths that use these features return “Cannot find anything for that body path.” To request support for a JSONPath feature, submit an idea at the mabl product portal.

Related articles