Beginner's Guide to JSON Functions with Claris FileMaker

Introduction to JSON in FileMaker

JSON (JavaScript Object Notation) is a lightweight data interchange format that's easy for humans to read and write, and easy for machines to parse and generate. As FileMaker has evolved into a powerful development environment for custom business applications, JSON has become an indispensable tool for structuring and transporting data.

In FileMaker, JSON enables developers to build dynamic, scalable applications that can communicate effectively with APIs, manage structured data internally, and simplify script complexity. Whether you're just beginning with FileMaker or looking to modernize your approach, understanding JSON is essential.

Why JSON Matters in FileMaker Development

Traditionally, developers relied on carriage-return-separated lists or repeating fields to manage collections of data in FileMaker. While functional, these methods fall short when dealing with complex, nested data structures. JSON provides a flexible and standardized way to represent structured data, making it an ideal choice for modern FileMaker development.

Key advantages include:

Simplified data management using objects and arrays.
Seamless integration with REST APIs and external web services.
Easier data transformation, storage, and export.

Core JSON Functions in FileMaker

FileMaker provides a suite of JSON functions that allow you to build, manipulate, and extract structured data. Here are the essential ones:

JSONSetElement: Adds or updates a key-value pair in a JSON object.
JSONGetElement: Retrieves the value of a specified key or index.
JSONDeleteElement: Removes an element from the JSON data.
JSONListKeys: Returns a list of keys from a JSON object.
JSONListValues: Returns a list of all values in a JSON object or array.

These functions form the backbone of JSON handling within FileMaker and are used frequently in scripts and calculations.

JSON Syntax Essentials for FileMaker

Understanding JSON syntax is crucial when working in FileMaker. JSON uses key-value pairs within objects, denoted by curly braces {}, and arrays, denoted by square brackets [].

There are two primary notations for accessing elements:

Dot Notation: person.name accesses the "name" key inside the "person" object.
Bracket Notation: ['person']['name'] does the same, and is required when keys include special characters like periods.

Paths allow you to navigate nested structures efficiently, enabling precision in both reading and writing data.

Creating JSON Objects in FileMaker

The JSONSetElement function is your go-to tool for creating JSON objects. For example:

JSONSetElement ( "" ; "firstName" ; "Alice" ; JSONString )

This produces:

{ "firstName": "Alice" }

You can build more complex objects with multiple fields by wrapping entries in a list:

JSONSetElement ( "" ; [ "user.name" ; "Alice" ; JSONString ] ; [ "user.age" ; 30 ; JSONNumber ] ; [ "user.active" ; True ; JSONBoolean ])

Notice how we've created a user parent key with an object to define the attributes of that user, by using dot notation. This results in a nested JSON structure with clearly defined types.

{"user":{"active":true,"age":30,"name":"Alice"}}

Building JSON Arrays in FileMaker JSON arrays are collections of items and are indexed starting from 0. To create an array of user records, you can do:

JSONSetElement ( "" ; [ "users[0].name" ; "Alice" ; JSONString ] ; [ "users[1].name" ; "Bob" ; JSONString ])

Arrays enable you to store multiple records in a single, structured variable, making them ideal for reporting, syncing, or exporting data.

{"users":[{"name":"Alice"},{"name":"Bob"}]}

FileMaker 21.0 Enhancements to JSON Functions

With the release of FileMaker 21.0, several enhancements were introduced to streamline JSON handling:

JSONMakeArray: Easily converts return-delimited lists into JSON arrays.
[+] Operator: Adds a new element to the end of an array.
[:] Operator: Refers to the last element in an array.

These updates make it significantly easier to manage array operations such as pushing or popping elements, especially in dynamic scripting contexts.

Parsing and Extracting JSON Data

Extracting data from JSON is straightforward with JSONGetElement. You can target deeply nested elements using precise paths. To loop through arrays, use JSONListValues in combination with ValueCount and GetValue to iterate over each element efficiently.

Modifying and Updating JSON Structures

To update existing values or add new ones, use JSONSetElement. FileMaker intelligently replaces values if the key or index exists, or adds it if not. You can also dynamically add elements to arrays using the "[+]" operator:

JSONSetElement ( json ; "items[+]" ; "NewItem" ; JSONString )

Deleting Elements from JSON in FileMaker

The JSONDeleteElement function removes specified keys or indices from a JSON structure. This is especially useful for pruning arrays or eliminating unused data before export.

Example:

JSONDeleteElement ( json ; "users[2]" ) // removes the third user from the array

Formatting and Validating JSON Data

Use JSONFormatElements to make JSON more human-readable, especially during development. To check for malformed data, inspect whether the result starts with a question mark (?), or use JSONGetElementType to verify the structure before processing it further.

Using JSON with External Data Sources

The Insert from URL script step is often used to retrieve JSON from web APIs. You can store the response in a variable (e.g., $$JSON ) and parse it using FileMaker's built-in JSON functions. This makes it easy to integrate with third-party services, such as e-commerce platforms, CRM systems, or repositories.

Practical Use Cases for JSON in FileMaker

Multi-value fields: Use JSON arrays to store related data, such as tags, related IDs, or multikeys.
API communication: Send and receive structured payloads with API endpoints.
Data exports: Format complex data for integration or reporting.
Virtual lists: Use JSON arrays to create flexible reporting interfaces.

Best Practices for JSON in FileMaker

Always specify types explicitly when using JSONSetElement to avoid incorrect parsing. You can review all the types in FileMaker’s Documentation
Use let statements to store intermediate JSON fragments and simplify the code.
Use while statements to iterate over found sets or to create complex JSON arrays with a single Set Variable statement.
Format your JSON for readability when debugging using the JSONFormatElements function.
Keep JSON keys consistent and meaningful.
Validate that a JSON element exists before trying to parse it for a critical process.
Minimize parsing large JSON blobs repeatedly by extracting only what you need.

Conclusion and Learning Resources

JSON has transformed how FileMaker developers approach data handling. From simple records to complex integrations, understanding how to use JSON effectively opens the door to modern, efficient app development.

To continue learning, explore the following resources:

Experiment using the Data Viewer and try building your own JSON structures to solidify your understanding. The more you use it, the more powerful and intuitive it becomes.