How to use JSON effectively in FileMaker

Your FileMaker system needs to talk to a REST API, feed data to a web form, or exchange structured records with an AI tool — and suddenly you're staring at a JSON object three levels deep, wondering whether to parse it field-by-field or dump it straight into a variable and hope for the best. Get this wrong and you end up with scripts full of JSONGetElement calls that break the moment a vendor changes their API response by one nested field. This article walks through how experienced FileMaker developers actually structure, parse, and generate JSON without turning it into a maintenance trap.

Why does JSON even matter in a FileMaker system?

FileMaker has had native JSON functions since version 16 — JSONGetElement, JSONSetElement, JSONFormatElements, and later the more efficient JSONGetElement with paths — and that changed what a FileMaker solution can realistically connect to. Before that, developers relied on custom functions or plugins just to talk to a REST API.

Today, JSON is the default language of:

• REST APIs (Exact Online, Shopify, Mollie, shipping carriers, CRM platforms)
• AI tools and LLM APIs (OpenAI, Claude, and FileMaker-native AI layers like Klai, which lets you send structured prompts and receive structured, parseable responses back into your database)
• Modern web front-ends built on FileMaker data, including form tools like FM-BetterForms, which render FileMaker-driven web forms and submit data back as JSON payloads
• Webhooks — a shipping partner or payment provider pushing a JSON object into your system the moment something happens, instead of you polling for updates

If your FileMaker solution can't produce and consume JSON cleanly, it's effectively cut off from most of the modern integration ecosystem.

What does "using JSON effectively" actually mean?

It means three things, in order of how often developers get them wrong:

1. Storing JSON in the right place — not scattering parsed values across dozens of fields when a single JSON object field would be more maintainable, and not storing everything as raw JSON when a proper field would perform better.
2. Parsing JSON without exploding your script — using paths and loops instead of hard-coding a JSONGetElement call for every single key.
3. Generating JSON that the receiving system actually accepts — matching data types, array structures, and encoding exactly what the API or form expects, not just what looks right to a human.

When should you store parsed JSON versus raw JSON?

This is the first real decision point, and it's easy to get backwards.

Store raw JSON in a single field when:

• The data is a log or audit trail (e.g. the exact payload an API sent you, kept for debugging).
• The structure varies between records and doesn't need to be searched or reported on individually.
• You're passing data through — receiving it from one API and forwarding it to another without touching the fields yourself.

Parse into real fields when:

• You need to search, sort, summarize, or report on the values (FileMaker can't efficiently Find inside a JSON blob).
• The values drive relationships, calculations, or portals elsewhere in the solution.
• Multiple scripts or layouts need the same value — parsing once and storing it beats re-parsing the JSON every time.

A concrete example: an order comes in from a webshop as a JSON payload with 40 fields, but your invoicing script only ever uses six of them — customer name, order total, VAT, line items, shipping address, order date. Store the raw JSON for traceability in one field, but parse those six into proper fields immediately on import. Don't parse all 40 "just in case," and don't skip parsing and re-run JSONGetElement inside every downstream script — both are common overengineering (or underengineering) mistakes.

How do you parse nested JSON without a script full of hard-coded paths?

The most common mistake: writing a separate JSONGetElement ( $json ; "customer.address.city" ) line for every field, then duplicating that whole block for every record in an array. It works for a demo, and then breaks the moment the API adds a field or changes an order.

A more resilient pattern:

1. Get the array length first, using JSONListValues or JSONGetElement on the array itself, then use ValueCount to find how many items you're dealing with.
2. Loop through the array by index with a variable ($i), building the path dynamically: "items[" & $i & "].sku".
3. Use JSONGetElement with dynamic paths inside the loop, rather than one static call per field per item.
4. Check JSONGetElement's error handling. Every JSON function returns an empty result silently if the path doesn't exist — that's convenient until it hides a real bug. Wrap critical parses in a check against Get(LastError) or validate the value isn't empty when it shouldn't be.
5. Log malformed payloads instead of letting the script fail silently. APIs change without warning; a script that just skips a bad record without logging it will cost you a support ticket three weeks later when someone asks why an order is missing.

What's the fastest way to build JSON for an outgoing API call?

Use JSONSetElement chained with itself, or better, use it inside a loop that builds the object incrementally, and never use & "\"" & "key" & ... string concatenation to build JSON by hand. It looks faster to write in the moment, but a single unescaped quote or apostrophe in a customer name breaks the payload, and you won't discover it until a specific record fails in production.

A pattern that holds up well in practice:

• Build a base structure with JSONSetElement and empty placeholders.
• Loop through your found set or portal rows, adding each item with JSONSetElement ( $json ; "items[" & $i & "].sku" ; skuValue ; JSONString ).
• Explicitly set the JSON type (JSONString, JSONNumber, JSONArray, JSONObject) on every call — FileMaker will guess types if you don't, and it guesses wrong often enough to matter (a numeric-looking SKU code getting sent as a number instead of a string is a classic one).
• Validate the final JSON with JSONFormatElements before sending it — it pretty-prints the structure so you can visually catch a missing bracket before the API rejects the call.

How does this connect to AI tools like Klai inside FileMaker?

When you add an AI layer such as Klai into a FileMaker solution — for example, to summarize a customer record, draft a reply email, or classify incoming support tickets — the exchange with the AI model is JSON both ways. You send a structured prompt (often including context pulled from FileMaker fields), and you get back a JSON response that ideally isn't just a paragraph of prose but a structured object: { "category": "complaint", "priority": "high", "suggested_reply": "..." }.

The practical lesson here: when you control the prompt, ask the AI model to return JSON in a fixed shape, and validate that shape before you parse it. AI responses are not always perfectly formed JSON — a model can wrap the object in markdown code fences, add a trailing comment, or occasionally hallucinate a field. Build a small validation step (does it start with {, does JSONGetElement on the required keys return a value) before you trust the response and write it into your database. This one gotcha causes more silent failures in AI-in-FileMaker projects than almost anything else.

How does JSON connect FileMaker to modern web forms?

Tools like FM-BetterForms render a FileMaker-driven form in a browser and submit the filled-in data back as a JSON payload, which your FileMaker layer then parses and writes into records. The same rules apply as with any API: know exactly which keys the form will send, parse defensively (a required field might arrive empty, not missing), and decide upfront whether you're writing directly into production tables or into a staging table you validate before committing — staging is almost always safer for anything a user fills in from outside your controlled environment.

What are the most common JSON mistakes in FileMaker solutions?

• Re-parsing the same JSON repeatedly instead of parsing once and storing the result — this quietly kills performance on large payloads, especially in loops.
• Ignoring JSON data types, letting FileMaker auto-detect types on the way out, which causes silent type mismatches on the receiving system.
• Not validating array length before looping, causing scripts to error out — or worse, silently process zero records — when an API returns an empty array instead of the expected list.
• Storing giant JSON blobs in fields that get displayed on layouts, which drags down layout load time for no reason if nobody actually needs to see the raw JSON.
• Hardcoding paths for optional fields, so the script breaks the day an API stops always including a field it used to send.
• Skipping error logging, so integration failures go unnoticed until someone manually notices missing data days later.

A quick checklist before you ship a JSON integration

• Do you know the exact JSON shape both systems expect — sample payloads, not just documentation?
• Are you parsing arrays with dynamic paths and a loop, not hardcoded static calls?
• Are JSON types explicitly set on every outgoing JSONSetElement?
• Is there error handling and logging for malformed or unexpected payloads?
• Are you storing only what you'll actually query or report on as separate fields?
• Have you tested with an empty array, a missing optional field, and a malformed payload — not just the happy path?

FAQ

Does using JSON slow down a FileMaker solution? Parsing JSON itself is fast, but re-parsing the same large payload repeatedly inside loops or on every layout refresh is what actually causes slowdowns. Parse once, store the result, and only re-parse when the source data changes.

Should I store JSON in a container field or a text field? Use a text field. JSON is text, and FileMaker's JSON functions operate on text fields directly. Container fields add unnecessary overhead and complexity for something that's fundamentally a string.

Can FileMaker validate JSON against a schema? Not natively — there's no built-in JSON Schema validator. In practice, developers build lightweight validation scripts that check for required keys and expected types, which covers most real-world needs without the overhead of a full schema engine.

What's the difference between JSONGetElement and JSONListValues? JSONGetElement retrieves a single value or object at a given path. JSONListValues returns all the values at one level as a list, which is useful for quickly checking how many items are in an array or iterating over key names.

Where does this fit into the bigger picture?

JSON handling is one of many structural decisions that determine whether a FileMaker solution stays fast and maintainable as it grows, or slowly turns into a tangle of scripts nobody wants to touch. If you're looking at your solution's structure more broadly — not just its JSON integrations — it's worth reading our guide on how to improve the performance and structure of a FileMaker solution, which covers the same underlying principle: build for the data you'll have in two years, not just the data you have today.

Whether you're connecting FileMaker to a webshop, feeding structured prompts to an AI layer like Klai, or collecting form submissions through a tool like FM-BetterForms, the underlying JSON patterns are the same — and getting them right the first time saves weeks of debugging later. If you're planning an integration like this and want a second pair of eyes on the data structure before you build it, Loggix can help map out the right approach, whether that means a custom FileMaker script layer, an API connector, or a broader consultancy session on your system's architecture.