2026-09-29 · 8 min read
- matlab
- json
- api
MATLAB arrays carry a size in every dimension. JSON arrays only nest. jsonencode uses that size: row vectors become one JSON array, column vectors become nested single-element arrays, and matrices become arrays of rows.
The storage inside MATLAB is column-major, which matters for linear indexing and for (:). It does not mean jsonencode emits a flat column-major buffer. Mixing those two ideas is how calibration payloads and API samples get transposed.
Name the shape in the contract
Write whether each array is a flat list, a column of samples, or a matrix stored row by row. Include the JSON example next to the MATLAB size. A sentence such as 1-by-n row encoded as a JSON array is specific enough to review.
- Prefer row vectors when the API wants a flat list.
- Document transpose points in the script.
- Reject unexpected ndims before encoding.
- Keep struct field names stable when the array is nested.
Encode from an explicit shape
Build the value with a size you can assert: a 1-by-n row for a flat list, or an m-by-n matrix whose rows are the JSON inner arrays. Do not flatten with (:) unless the consumer wants column-major order and you document that order.
Singleton dimensions disappear in some MATLAB operations and survive in others. Check size after squeeze, permute, and reshape, not only after the math that produced the numbers.
Preserve non-finite values on purpose
JSON has no NaN or Infinity. jsonencode converts NaN, Inf, and -Inf to null, so a missing sensor sample and a true null become the same token. If the difference matters, encode a sentinel the schema allows, or reject non-finite values before publish.
Large integers above the exact JSON number range need a policy too. Double arrays cannot hold every int64. Decide whether the wire format is a JSON number or a string before the first client parses it back.
Expect decode to return a row
jsondecode of a one-dimensional JSON array returns a row vector. A column you encoded as nested arrays can come back as a column, but a flat list will not remember that it started as n-by-1. Round-trip tests should compare size, not only the numeric values.
Cell arrays, string arrays, and numeric arrays encode differently. Do not assume a struct field that looks numeric in the workspace is numeric on the wire.
Review payloads with shape fixtures
Use Flashman's MATLAB array helper for shape, the JSON formatter for encoded text, the MATLAB struct helper for field wrappers, diff for row versus column output, and the Markdown editor for the orientation contract.
Test a row, a column, a matrix, an empty 0-by-n array, NaN and Inf, a struct field, a jsondecode round trip, and a script that uses (:) or transpose before encode.