JSON (JavaScript Object Notation)
JSON (JavaScript Object Notation) is a lightweight, text-based format for representing structured data as key-value pairs and ordered lists.
Definition
JSON (JavaScript Object Notation) is a lightweight, text-based format for representing structured data as key-value pairs and ordered lists. In Salesforce, it is the default body format for REST API requests and responses, Apex HTTP callouts, platform event and Change Data Capture payloads, and the data passed between Apex and Lightning components. Because most modern web services speak JSON, it is the common format Salesforce uses to exchange data with outside systems.
Apex has built-in JSON support through the System.JSON class, which converts Apex objects to JSON strings and parses JSON strings back into Apex objects. The same class exposes a streaming generator and parser for large or custom payloads. JavaScript in Lightning Web Components and Aura already treats JSON as its native object format, so data crossing the Apex-to-browser boundary is serialized and parsed automatically. Reading and writing JSON correctly is a core skill for any Salesforce integration work.
How JSON moves data through the Salesforce platform
The JSON data model in plain terms
JSON describes data with a small set of building blocks. An object is a set of key-value pairs wrapped in curly braces, such as {"name":"Acme","employees":50}. An array is an ordered list wrapped in square brackets, like ["a","b","c"]. Values can be strings, numbers, booleans (true or false), null, nested objects, or nested arrays. That short list covers almost everything a business record needs to express. The format is text, so any system that can read a string can read JSON, which is why it travels well between Salesforce and other platforms. Keys are always quoted strings. Salesforce typically uses the API name of a field as the key, so an Account name arrives under the key Name and a custom field arrives under Region__c. There is no date type in JSON itself, so Salesforce represents dates and datetimes as ISO 8601 strings such as 2026-06-16T10:30:00.000+0000. Numbers have no separate integer and decimal types in the spec, which matters when you parse untyped data in Apex and need to cast a value to Integer or Decimal yourself.
REST API requests and responses
The Salesforce REST API uses JSON as its primary body format. A GET to /services/data/v60.0/sobjects/Account/001XXXXXXXXXXXX returns that Account as a JSON object, with each field as a key. To create a record, you POST a JSON body holding the field values to /services/data/v60.0/sobjects/Account, and the response returns the new record Id, again as JSON. The composite and sObject Collections resources accept and return JSON too, which lets one request carry many records and cut the number of round trips. The same shape appears when Apex calls an external service. You build an HttpRequest, set the body to a JSON string, send it, then read the HttpResponse body, which is usually JSON you parse back into Apex objects. Because the request and response are just text, you can inspect them in debug logs, replay them with a tool like Postman, and reason about them without special tooling. This predictability is a big reason JSON became the default contract for web APIs and, by extension, for Salesforce integrations.
The Apex System.JSON class
Apex ships JSON handling in the System.JSON class. JSON.serialize(anyObject) turns an Apex object, list, or map into a JSON string. JSON.serializePretty(anyObject) does the same with indentation for readable output. A second parameter, suppressApexObjectNulls, lets you drop keys whose values are null so the payload stays compact. On the way back in, JSON.deserialize(jsonString, MyType.class) parses a string into a strongly typed Apex class or collection, while JSON.deserializeStrict additionally rejects any JSON key that has no matching Apex member. When you do not know the shape ahead of time, JSON.deserializeUntyped(jsonString) returns an Object you cast to Map<String, Object> for an object or List<Object> for an array, then walk key by key. Untyped parsing is flexible but verbose, and every value comes back as Object, so you cast as you read. Strongly typed deserialization is cleaner and self-documenting when the schema is stable, so prefer it for production code and reserve untyped parsing for exploratory or genuinely dynamic payloads.
Generators and parsers for big or custom payloads
The convenience methods build or consume the whole structure in memory, which is fine for typical records but costly for very large bodies. For those cases Apex offers a streaming pair. JSON.createGenerator returns a JSONGenerator that writes tokens one at a time, so you can construct a precise payload, including custom key names and a specific field order, without first assembling a matching Apex object. This is handy when an external API expects a shape that does not map cleanly to your classes. On the read side, JSON.createParser returns a JSONParser that walks a JSON string token by token. Instead of materializing the entire object tree, you advance through the tokens and pull out only the fields you care about. For multi-megabyte responses, this streaming approach keeps heap usage down and helps you stay inside the Apex governor limits. The trade-off is more code than a one-line deserialize call, so reach for the streaming classes when payload size or an unusual contract makes the convenience methods impractical, not as the default.
Events, components, and stored JSON
JSON is also the payload format for asynchronous and UI data paths. Platform events carry their field data as JSON, and Change Data Capture publishes record changes as JSON messages that subscribers parse. Clients on the Pub/Sub API receive the binary Avro form, but the logical record shape mirrors the same field structure you see elsewhere. Apex triggers on event objects and external subscribers both read these messages and act on the structured content inside. Inside the UI, Lightning Web Components and Aura are JavaScript, so JSON is their native object format. An @AuraEnabled Apex method returns a typed Apex object, and the framework serializes it to JSON for the browser automatically, where it arrives as a plain JavaScript object. Some teams also store JSON as text, packing structured data into a Long Text Area or a custom metadata record so admins can extend behavior without new objects. That pattern works, but JSON hidden in a text field skips field-level security and is not indexed for reporting, so use it deliberately rather than as a shortcut around the data model.
Contracts, schema, and common failure points
Production integrations need a shared contract so both sides agree on the JSON shape. JSON Schema describes the expected keys, types, and required fields, and Salesforce External Services consumes an OpenAPI specification that embeds JSON Schema to generate invocable actions for Flow and Apex. A declared schema catches a renamed or missing field at design time instead of letting it surface as a runtime error in front of a user. Most JSON bugs in Apex come from small mismatches. Apex deserialization matches keys exactly and does not auto-convert casing, so a firstName key will not populate an Apex member named first_name, and the value lands as null instead. Reserved words and characters that are not valid in Apex identifiers force the use of the JsonGenerator or a field-mapping approach. The @JsonAccess annotation lets a class declare whether its instances may be serialized or deserialized, which guards sensitive types. Logging the raw JSON before parsing remains the fastest way to spot these issues during development.
Trust & references
Cross-checked against the following references.
- JSON Support | Apex Developer GuideSalesforce
- JSON Class | Apex Reference GuideSalesforce
Straight from the source - Salesforce's reference material on JSON (JavaScript Object Notation).
Hands-on resources to go deeper on JSON (JavaScript Object Notation).
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is JSON in the context of Salesforce development?
Q2. Which Apex class moves data between JSON strings and Apex objects?
Q3. Why is JSON described as the lingua franca Salesforce speaks with external systems?
Discussion
Loading discussion…