JSON Integration Explained

If you have ever inspected the traffic between a web app and its backend, watched a mobile app talk to a cloud service, or wired two enterprise systems together over an API, you have seen JSON. It is the default data format of the modern web, and it has quietly become the format most enterprise systems reach for first when they need to exchange data. This guide sits inside a wider set of articles on how systems talk to each other. If you want the full landscape first, start with the pillar on enterprise system integration explained, then come back here for the deep dive on the format itself.

The message up front: JSON is deceptively simple. The syntax fits on a postcard, which is exactly why teams underestimate it. The hard parts are not the braces and brackets. They are number precision, date handling, null semantics and schema discipline, and every one of those has broken an integration I have been called in to fix.

1. What JSON is

JSON stands for JavaScript Object Notation. It is a lightweight, text-based format for representing structured data. Despite the name, JSON is not tied to JavaScript. It was derived from the object literal syntax of JavaScript, but it is a language-independent data format, and today every serious programming language ships a JSON parser and serializer, either in its standard library or as a well-established package.

The whole format is built from two kinds of structure and a small set of primitive values. The two structures are the object, which is an unordered collection of name and value pairs, and the array, which is an ordered list of values. The primitive values are strings, numbers, the literals true and false, and null. That is the entire grammar. There is nothing else to learn about the syntax, which is precisely why it spread so fast.

A JSON document is just text. You can open it in any editor, read it with your eyes, store it in a file, put it in a database column, or send it across a network. Because it is text and not a binary format, it is trivial to log, diff, version-control and debug, which matters more in day-to-day integration work than most people expect. When an integration misbehaves at three in the morning, being able to read the payload directly, without a special tool, is worth a great deal.

2. Why JSON won the web

For most of the 2000s, XML was the assumed format for machine-to-machine data exchange. SOAP web services, enterprise message buses and configuration files were all XML. JSON overtook it for a handful of practical reasons, and understanding them explains a lot about why modern APIs look the way they do.

First, JSON is less verbose. It carries the data and almost nothing else, so payloads are smaller and easier to read at a glance. Second, it maps cleanly onto the data structures that programming languages already use. A JSON object becomes a dictionary or map, a JSON array becomes a list, and the primitives become native strings, numbers and booleans. There is very little impedance mismatch between the wire format and the objects in your code. Third, it arrived at the same moment that browsers, single-page applications and mobile apps exploded, and all of those environments spoke JavaScript, where JSON parsing was effectively free.

The result is that JSON became the default for REST APIs, and REST became the default style for web integration. If you are building or consuming an API today, the safe assumption is that it speaks JSON over HTTP. For how that plays out in practice, the companion article on REST APIs explained covers the request and response model that JSON usually rides on top of.

3. Structure: objects, arrays and values

The best way to understand JSON is to look at a real structure and name each part. A JSON document has a single root value, almost always an object or an array. Objects group related fields under keys. Arrays hold ordered sequences. Values can themselves be objects or arrays, which is how JSON represents nested and hierarchical data. The diagram below shows a work-order-style object with a nested object and an array of values.

Reading that structure back in words: the root is an object delimited by curly braces. Inside it, each key is a string in double quotes, followed by a colon, followed by a value. Pairs are separated by commas. The value for the key "asset" is itself an object, which is how JSON nests. The value for "parts" is an array, delimited by square brackets, holding an ordered list of values that can mix types. Notice that an array can contain strings and a number side by side. JSON permits that, though a good schema will usually forbid it.

A few rules catch people out. Keys must be strings in double quotes. Single quotes are not valid JSON. There is no trailing comma allowed after the last element of an object or array, a restriction that trips up developers who came from JavaScript, where trailing commas are tolerated. Numbers have no quotes, and there is no separate integer or float type at the syntax level, just a single number type. Those constraints are small but strict, and a parser will reject a document that breaks any of them.

4. JSON Schema and validation

JSON by itself has no built-in notion of a contract. The syntax tells a parser whether a document is well-formed, but it says nothing about whether the document is the right shape for your integration. Is the "id" field required? Must "title" be a string? Can "parts" be empty? Plain JSON answers none of that. This is where JSON Schema comes in.

JSON Schema is a separate specification for describing the structure of a JSON document. A schema is itself written in JSON, and it lets you declare which fields are required, what type each field must be, allowed value ranges, string patterns, array length limits, and nested object shapes. You then run a validator that checks a candidate document against the schema and reports exactly where it fails. A tiny example of a schema fragment looks like this:

The value of a schema in integration work is that it turns a vague agreement between two teams into an executable contract. Instead of an email thread saying the "id" should probably be a number and "title" is usually present, you have a document that either passes or fails, checked automatically at the boundary. When a partner sends a payload that violates the contract, the validator names the offending field instead of letting a bad record slip through and surface as a mysterious failure three systems downstream.

The practitioner's habit: validate at the edge. Every integration boundary that accepts JSON from another system should validate it against a schema before doing anything else. It is the single cheapest defence against malformed data, and it converts a class of silent, hard-to-trace bugs into loud, precise, early failures. For the wider picture of where these boundaries sit, see the pillar on enterprise system integration.

5. JSON versus XML

JSON did not appear in a vacuum. It replaced XML in a great many places, but not all of them, and it is worth being precise about the trade-offs rather than treating JSON as simply better. The two formats have genuinely different strengths, and enterprise integration still uses both. The table below sets them side by side across the dimensions that actually matter when you are choosing.

The honest summary is that JSON is the better fit for the data-carrying, API-driven world that most integration now lives in, while XML retains an edge for document-centric data, mixed content where text and markup interleave, and the many established enterprise and government exchanges that were built on it and are not going anywhere. If you are working with the older side of that world, the companion piece on XML integration covers it in the same depth this article gives JSON.

6. JSON in APIs and integration

In practice, JSON almost always travels as the body of an HTTP request or response in a REST API. A client sends a request, the server responds with a JSON body and a content type of application/json, and both sides parse the text into native objects. This is the pattern behind the vast majority of cloud integrations, from a payment gateway to a facilities platform to an ERP.

Modern business systems expose their data this way as a matter of course. Microsoft Dynamics 365 Business Central, for example, exposes its entities through JSON-based web APIs, and integrating with it means constructing and consuming JSON payloads over HTTP. If that is your world, the article on Business Central APIs and integrations walks through exactly how those endpoints behave and how to work with them safely.

JSON is not only a live-API format. It is also a perfectly good file format for batch and scheduled exchange. A nightly export of records as a JSON file, dropped to a shared location and picked up by another system, is a common and reliable pattern, and it competes directly with the older CSV and fixed-width file approaches. The trade-offs between streaming APIs and file drops are their own topic, covered in the article on file-based integration. The point for now is that JSON serves both the real-time and the batch worlds, which is part of why it has become the default.

7. Common pitfalls: number precision, dates and nulls

The syntax of JSON is easy. The semantics are where integrations break. Three problems account for a large share of the JSON-related bugs I have been called in to diagnose, and none of them is visible from the syntax alone.

Number precision. JSON has a single number type and no distinction between integers and floating point at the format level. Many parsers, following the JavaScript heritage, represent every number as a double-precision float. That is fine until you send a very large integer, such as a 64-bit identifier or a high-precision monetary amount, and the receiving side silently rounds it because a double cannot hold that many significant digits exactly. The classic symptom is an ID that arrives slightly wrong, or a currency total that is off by a fraction. The defensive move is to transmit large identifiers and exact decimal amounts as strings, so no parser reinterprets them as floats.

Dates. JSON has no date type. A date is either a string or a number, and the format is entirely a matter of convention between the two systems. The safe convention, and the one I insist on, is ISO 8601 in UTC, for example a timestamp written as year, month, day, then a T, then the time with a Z suffix. Where integrations go wrong is when one side sends a local time with no timezone, or a regional format like day-month-year, and the other side guesses. Guessing about dates is how you get records stamped a day off or an hour off across a boundary, and those errors are painful to trace after the fact.

The honest caution: JSON's simplicity hides these traps rather than solving them. Because the format itself imposes no rules on numbers, dates or nulls, every integration has to agree on conventions explicitly and enforce them with a schema. Assuming the other side handles them the way you do is the most common root cause of the intermittent, hard-to-reproduce data bugs that JSON integrations suffer from.

Nulls and missing keys. There is a real semantic difference between a key whose value is null, a key that is present with an empty string, and a key that is absent entirely. Null usually means the value is known to be empty. An absent key usually means the value was never supplied. Many systems treat these three cases differently, and many others conflate them, so a field that is null on one side can arrive as absent on the other and be interpreted as no change rather than clear the value. Decide explicitly what null, empty and absent each mean in your contract, document it, and validate it, because the format will not decide for you.

8. When to use JSON

JSON is the right default for most integration work today, but it is worth being deliberate rather than reflexive about it. It is an excellent fit when you are building or consuming a web or mobile API, when you are integrating cloud services, when you want a payload that developers can read and debug directly, and when the data maps naturally onto objects, arrays and simple values. For the overwhelming majority of REST-style integrations, JSON is the correct and unremarkable choice.

There are places where it is not the best tool. If you are exchanging document-centric data with rich mixed content, or working within a regulated ecosystem that standardised on XML years ago, fighting that current to force JSON in is usually a mistake. If you are moving very large volumes of highly repetitive numeric data where every byte counts, a binary format may serve better than any text format. And if your counterpart system only speaks CSV or a fixed-width file, meeting it there is more pragmatic than insisting on JSON. The skill is not defaulting to JSON everywhere; it is recognising the common case where JSON is clearly right and the narrower cases where something else fits better.

9. References

JSON is a genuinely standardised format, and it is worth knowing the documents that define it rather than relying on folklore. Three references matter for a working integration engineer:

• ECMA-404, The JSON Data Interchange Syntax. The standard that formally defines the JSON grammar, published by Ecma International. It specifies exactly what a well-formed JSON document looks like.
• RFC 8259, The JavaScript Object Notation (JSON) Data Interchange Format. The IETF standard, aligned with ECMA-404, which serves as the definitive interoperability reference and covers details such as encoding and interchange considerations.
• JSON Schema. The specification for describing and validating the structure of JSON documents. It is the contract language that turns an informal agreement about payload shape into something a validator can check automatically.

Between ECMA-404 and RFC 8259 you have the authoritative definition of the syntax, and JSON Schema gives you the tooling to enforce structure on top of it. Those three together are the foundation any serious JSON integration rests on.

Final thoughts

JSON earned its place as the lingua franca of modern integration by being small, readable and a near-perfect match for the data structures programs already use. That simplicity is a genuine strength, but it is also a trap, because it hides the parts that actually break integrations: number precision, date conventions, null semantics and the absence of any enforced contract. The engineers who ship reliable JSON integrations are the ones who respect those hidden edges, agree conventions explicitly, and validate every payload at the boundary against a schema.

Treat JSON as what it is: a clean, well-standardised format that carries your data faithfully as long as both sides agree on what the data means. The braces and brackets will never be your problem. The agreement about what a large number, a timestamp and a null actually represent is where the real work lives, and getting that right is the difference between an integration that runs quietly for years and one that surfaces a mysterious off-by-a-day bug every few weeks. For the full context of where JSON sits among the other patterns and formats, circle back to the pillar on enterprise system integration explained.

Related reading: Enterprise system integration explained, XML integration, REST APIs explained, File-based integration, Business Central APIs and integrations.