MATLAB JSON Parsing and Formatting Functions

If you need to work with JSON in MATLAB, the core functions are straightforward: use jsondecode to parse JSON text into MATLAB data, and use jsonencode to turn MATLAB variables back into JSON. For direct file-based workflows, newer MATLAB releases also add helpers such as readstruct, writestruct, and readdictionary. For most search visitors, the real questions are usually how to decode formatted JSON text, how nested arrays of objects behave, and how to write a valid JSON file without losing structure. This page focuses on those practical cases.

jsondecode: Parse JSON Text into MATLAB Data

jsondecode accepts JSON text as a character vector or string scalar and converts it into the nearest MATLAB representation. That makes it the right tool for API responses, config files loaded with fileread, and any situation where you already have raw JSON text.

Example: Decode Nested JSON with Multiple Objects

A common MATLAB JSON question is how to handle an array of multiple child objects or nodes. If the objects in the JSON array have a compatible structure, MATLAB gives you a struct array that you can index naturally.

jsonText = ['{' ...
    '"project":"demo",' ...
    '"files":[' ...
        '{"name":"input.csv","rows":12,"active":true},' ...
        '{"name":"output.csv","rows":18,"active":false}' ...
    ']' ...
    '}'];

data = jsondecode(jsonText);

firstName = data.files(1).name
rowCounts = [data.files.rows]
activeFlags = [data.files.active]

Does jsondecode Work with Formatted JSON Text?

Yes. Pretty-printed JSON with spaces and line breaks is still valid JSON, so jsondecode can parse it directly. In practice, the reliable MATLAB pattern is to read the whole file with fileread and pass that text to jsondecode.

formattedText = sprintf(['{\n' ...
    '  "user": "alice",\n' ...
    '  "settings": {\n' ...
    '    "theme": "light",\n' ...
    '    "autosave": true\n' ...
    '  }\n' ...
    '}']);

config = jsondecode(formattedText);
mode = config.settings.theme

% When reading from disk:
config = jsondecode(fileread("config.json"));

How jsondecode Maps JSON to MATLAB

• JSON objects decode to MATLAB structs.
• JSON arrays of numbers decode to MATLAB numeric arrays, typically double.
• JSON arrays of booleans decode to MATLAB logical arrays.
• JSON arrays of compatible objects often decode to struct arrays; mixed or incompatible content can decode to cell arrays instead.
• JSON strings decode to MATLAB character vectors.
• JSON null becomes NaN inside numeric arrays, but becomes an empty array in nonnumeric positions.
• JSON object keys that are not valid MATLAB identifiers may be adjusted when converted into struct field names.

jsonencode: Convert MATLAB Data to JSON

jsonencode converts MATLAB values into JSON text. It is the function behind most MATLAB JSON formatting tasks, whether you need compact output for transport or pretty-printed output for a readable JSON file.

Example: Encode a MATLAB Struct as JSON

person = struct( ...
    "name", "Alice", ...
    "age", 30, ...
    "isStudent", false, ...
    "scores", [91 88 95]);

compactJson = jsonencode(person)
prettyJson = jsonencode(person, PrettyPrint=true)

Special Values: NaN and Inf

By default, jsonencode converts NaN, Inf, and -Inf to null because strict JSON has no native representation for those numeric values. If you are targeting a consumer that accepts nonstandard tokens, MATLAB also supports a compatibility mode.

values = struct("ok", 5, "missing", NaN, "upper", Inf);

strictJson = jsonencode(values)
compatJson = jsonencode(values, ConvertInfAndNaN=false)

Write MATLAB Data to a JSON File

If your goal is simply "write to JSON file in MATLAB," the portable approach is still to encode the data first and then write the returned text to disk.

settings = struct( ...
    "mode", "auto", ...
    "threshold", 0.75, ...
    "enabled", true);

jsonText = jsonencode(settings, PrettyPrint=true);

fid = fopen("settings.json", "w");
fprintf(fid, "%s", jsonText);
fclose(fid);

File-Based Helpers in Newer MATLAB Releases

MATLAB has added higher-level JSON file APIs beyond jsonencode and jsondecode. These are worth knowing because many users search for a MATLAB JSON reader or a direct JSON file writer, not just text conversion.

• readstruct can read JSON files directly into a struct. MathWorks added JSON support for it in R2023b.
• writestruct can write structs to JSON files directly in R2023b and newer.
• readdictionary was added in R2024b and is useful when you want JSON object keys to stay as keys instead of becoming MATLAB struct field names.

% R2023b+
data = readstruct("payload.json");
writestruct(data, "payload-pretty.json", PrettyPrint=true);

% R2024b+
headers = readdictionary("headers.json");

Common Pitfalls and Troubleshooting

• Invalid key names: JSON keys can contain characters MATLAB does not allow in struct field names. After jsondecode, inspect the resulting field names carefully or use readdictionary in R2024b or newer.
• Arrays of objects: If an array does not resolve cleanly to one struct layout, MATLAB may return a cell array instead of a struct array. Check with class and index accordingly.
• Formatted JSON from files: Prefer fileread for loading multi-line JSON text. It is simpler and more reliable than line-by-line or whitespace-delimited reads.
• Strict vs nonstandard JSON: jsondecode expects valid JSON syntax. Comments, trailing commas, and nonstandard numeric tokens are not safe inputs there.
• MATLAB object serialization: jsonencode encodes public object properties, but complex custom classes may still need a deliberate export struct for stable JSON output.

Version Notes

• jsonencode and jsondecode were introduced in MATLAB R2016b.
• Modern name=value syntax such as PrettyPrint=true works in R2021a and newer.
• readstruct and writestruct gained JSON support in R2023b.
• readdictionary was introduced in R2024b.

Conclusion

For most MATLAB JSON work, the core recipe is simple: jsondecode to parse, jsonencode to format, fileread when the source is a JSON file, and newer file-based helpers when you want less boilerplate. Once you know how MATLAB maps arrays, objects, null, and nonfinite numbers, most JSON interoperability issues become predictable.