JSON (JavaScript Object Notation)
JSON (JavaScript Object Notation) is the lightweight, text-based data format Salesforce uses for nearly every modern data exchange.
Definition
JSON (JavaScript Object Notation) is the lightweight, text-based data format Salesforce uses for nearly every modern data exchange. It is the request and response format of the Salesforce REST API, the payload format of platform events and Change Data Capture, the persistence format for JSONB-style fields, and the default serialization for Apex callouts. JSON''s near-universal adoption across web APIs makes it the lingua franca that Salesforce speaks with external systems.
Apex provides first-class JSON support through the JSON, JSON.deserialize, JSON.serialize, and JSON.deserializeUntyped methods. The JSON class parses strings into Apex objects, serializes Apex objects to strings, and handles edge cases like null values, custom field names, and nested structures. Lightning Web Components and Aura Components consume JSON natively in JavaScript. The Bulk API 2.0 uses CSV instead of JSON for its primary data format, but the job-status responses are JSON. Working effectively with JSON in Salesforce is a foundational skill for any integration developer.
How JSON shows up across the Salesforce platform
REST API JSON payloads
Every Salesforce REST API call uses JSON for request and response bodies. A GET to /services/data/v60.0/sobjects/Account/001xx returns the Account record as JSON. A POST to the same endpoint creates an Account from a JSON body. Apex callouts to external REST APIs follow the same pattern; the HttpResponse body is typically JSON that the developer parses with JSON.deserialize.
Apex JSON class
The Apex JSON class is the standard JSON toolkit. JSON.serialize(object) returns a JSON string; JSON.deserialize(jsonString, Type.forName(''MyClass'')) parses into a strongly-typed Apex class; JSON.deserializeUntyped(jsonString) returns a Map<String, Object> for navigation when the schema is uncertain. The class handles edge cases like ISO 8601 date formatting, escaping, and Unicode encoding.
Platform Events and Change Data Capture
Platform Events carry their payload as JSON. Change Data Capture (CDC) events also serialize record changes to JSON. Subscribers (Apex triggers on PlatformEvent objects, external systems via CometD or Pub/Sub API) receive JSON and parse it for processing. The JSON shape mirrors the standard sObject field structure.
LWC and Aura JSON consumption
Lightning Web Components and Aura Components are JavaScript; JSON is the native data format. @AuraEnabled Apex methods return strongly-typed Apex objects that the framework automatically serializes to JSON for the browser. The component receives the data as a JavaScript object and renders accordingly. Custom REST callouts from LWC also exchange JSON.
JSON in Custom Metadata and Long Text Areas
Some Salesforce features store structured data as JSON inside Long Text Area fields or Custom Metadata records. The pattern lets admins extend the data model declaratively without creating new objects. Apex code reads the JSON, deserializes it, and acts on the structured content. Care is needed: storing JSON in a text field bypasses field-level security and indexing.
JSON Schema and contract enforcement
Modern integrations use JSON Schema to define the expected shape of JSON payloads. Salesforce''s External Services and OpenAPI-based integrations rely on JSON Schema to declare contracts. Strong contracts catch payload changes at design time rather than runtime.
Performance considerations
JSON parsing in Apex consumes CPU. Large JSON payloads (multi-megabyte) can blow the 10-second CPU governor limit if parsed naively. The fix is JSON.JSONParser for streaming parse, which processes the JSON token-by-token rather than building the full object tree. For very large payloads, consider compressing the response or chunking the request.
Work with JSON in Apex
The standard JSON pattern in Apex is serialize on the way out, deserialize into a strongly-typed class on the way in.
- Define the Apex class
Create a class with public fields matching the JSON shape: public class MyResponse { public String status; public List<MyItem> items; }.
- Serialize Apex to JSON
String jsonOut = JSON.serialize(myObject); Returns a JSON string ready for HTTP request bodies, debug logs, or storage.
- Deserialize JSON to Apex
MyResponse parsed = (MyResponse) JSON.deserialize(jsonString, MyResponse.class); Strongly-typed access to fields.
- Handle uncertain schemas
Map<String, Object> raw = (Map<String, Object>) JSON.deserializeUntyped(jsonString); Walk the Map for ad-hoc parsing.
- Handle null and missing fields
Apex deserializes missing fields to null. Check for null on every field access; assuming a field is present is the leading source of NullPointerExceptions.
- For large payloads, use JSON.JSONParser
Stream-parse via JSONParser to avoid building the full object tree in memory.
The strongly-typed class matching the JSON shape.
The standard methods for two-way conversion.
Required for any field that might be missing.
Required when the JSON exceeds the practical 6-MB heap limit.
- Apex JSON.deserialize requires field names in the Apex class to match the JSON. Mismatched names silently leave fields null; debug by logging the raw JSON before deserializing.
- Large JSON payloads consume CPU. The 10-second governor limit kicks in for naive deserializes of multi-megabyte payloads; switch to streaming parse.
- JSON does not enforce schema. Without JSON Schema validation, payload changes can break consumers silently; build contract tests for any production integration.
- JSON stored in Long Text Areas bypasses field-level security. Sensitive data should not be persisted as JSON in unmarked text fields.
Trust & references
Cross-checked against the following references.
- Apex JSON ClassSalesforce Developers
- REST APISalesforce Developers
Straight from the source - Salesforce's reference material on JSON (JavaScript Object Notation).
- JSON.orgJSON.org
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?
Q2. What Apex class handles JSON?
Q3. Where is JSON used in Salesforce?
Discussion
Loading discussion…