Introduction

An object is a fundamental complex data type in JMESPath and JSON. It is an unordered collection of key-value pairs, where keys and values are connected by a colon, different key-value pairs are separated by a comma, and the whole object is enclosed in braces. The key-value pairs are sometimes called properties. Here's an example of an object:

{
	"name": "Alice",
	"age": 47,
	"currentAddress": {
		"city": "Anytown",
		"street": "Main street",
		"houseNumber": 1
	}
}

Notice that the keys are always text strings, but the values can be text, numbers or even objects themselves.

In programming, similar data structures are sometimes called dictionaries. This can be a helpful way of thinking about objects, where the key works like a word in a dictionary, and the value represents the definition of the word.

Most data in JSON files is transmitted inside objects, so working with objects is an essential part of JMESPath.

What will I learn?

This guide will teach you to:

• Retrieve data from an object.
• Create new objects.
• Merge objects.
• Reformat objects to create different structures in the data.
• Get lists of keys, values and properties from objects.

Prerequisites

You'll only need access to a Documotor tenant and a basic understanding of the platform. Other data types are used implicitly, but no familiarity is expected.

Sample data

Consider the following dataset.

{
	"idNumber": 1234,
	"person": {
		"name": "Alice",
		"age": 47,
		"currentAddress": {
			"city": "Anytown",
			"street": "Main street",
			"houseNumber": 1
		},
		"previousAddress": {
			"city": "Anyville",
			"street": "High street",
			"houseNumber": 3
		} 
	}
}

It's good practice to observe the structure of the dataset before commencing the transformations. The object containing all the data only has one property: person. The value of the person property is an object containing personal info like name, age and current address.

Retrieving data from objects

Fetch a value from an object by using the property identifier:

	id: idNumber
	// 1234

In case of nested objects, use subexpressions access the properties of the next object in the hierarchy by placing after the property name of the first object:

	name: person.name,
	// "Alice"
	age: person.age,
	// 47
	city: person.address.city,
	// "Anytown"
	street: person.address.street,
	// "Main street"

Consider the problem of finding all the cities where a person lived. In this case, there is only two of them, so doing it with two lines such as person.currentAddress.city and person.previousAddress.city is easy, but what if there were too many to list conveniently?

We can solve this problem with a wildcard expression, which looks like this:

	familiarCities: person.*.city
	// ["Anytown", "Anyville"]

In a way, the asterisk stands in for all the properties of person; hence the name wildcard expression. In the background, JMESPath is trying to access the city subproperty of all the properties of the person object. Whenever it succeeds, the result is added to an array, and when all the properties have been tried, it returns the array.

Building new objects

One way to build new objects is to define them inside the transformation explicitly.

	apartmentInfo: `{"floor": 3, number: 2}`

The backticks denote a literal expression, which creates the exact object specified inside it.

After defining a property within the transformation, we're also able to access it using the current output operator $. The dollar sign represents the entire data payload created in the transformation up to the line where the operator is used. Thus, we can use $.apartmentInfo to access the newly created object.

Now that we have the apartment info, the merge function allows us to merge it with the rest of the address.

	addressMergedWithApartment: merge(person.currentAddress, $.apartmentInfo),
	//{"city": "Anytown", "street": "Main street", "houseNumber": 1, "floor": 3, "number": 2}

Some of the other functions used for working with objects fetch an array of all of its keys, values, or key-value pairs.

	availableInfo: keys(person),
	listOfValues: values(person),
	personAsArray: items(person)

Objects are omnipresent in JMESPath, and following our other guides will inevitably make you more comfortable with working with objects as well. Proceed to our array guide, or learn more about object-focused functions in Documotor.