File Exchange

image thumbnail

JSONLab (Development Branch)

version 1.9.8 (148 KB) by Qianqian Fang
A toolbox to encode/decode JSON and UBJSON files in MATLAB/Octave


Updated 29 Sep 2020

From GitHub

View Version History

View license on GitHub

This is the development branch (unstable) of the JSONLab Toolbox. The download link is directly pointed to the latest commit in the "master" branch of the JSONLab Github repository at

Please use this branch with caution: it may contain the latest bug fixes, but in the meantime, it may also contain partially implemented features, and may be unstable. If you need a stable release, please download from the below link instead

The previous stable release of JSONLab:

** JSONLab 2.0 beta (Magnus - beta) is released on 10/24/2019.**

Release URL:
Reference implementation for JData Specification Draft 2 -
Depends on:

JSONLab is a free and open-source implementation of a JSON/UBJSON/MessagePack encoder
and a decoder in the native MATLAB language. It can be used to convert a MATLAB
data structure (array, struct, cell, struct array, cell array, and objects) into
JSON/UBJSON/MessagePack formatted strings, or to decode a
JSON/UBJSON/MessagePack file into MATLAB data structure. JSONLab supports both
MATLAB and [ GNU Octave] (a free MATLAB clone).

JSON ([ JavaScript Object Notation]) is a highly portable,
human-readable and [ "fat-free"] text format
to represent complex and hierarchical data. It is as powerful as [ XML]
but less verbose. JSON format is widely used for data-exchange in applications.

UBJSON ([ Universal Binary JSON]) is a binary JSON format, specifically
specifically optimized for compact file size and better performance while keeping
the semantics as simple as the text-based JSON format. Using the UBJSON
format allows to wrap complex binary data in a flexible and extensible
structure, making it possible to process complex and large dataset
without accuracy loss due to text conversions. MessagePack is another binary
JSON-like data format widely used in data exchange in web/native applications.
It is slightly more compact than UBJSON, but is not directly readable compared

We envision that both JSON and its binary counterparts will play important
roles as mainstream data-exchange formats for scientific research.
It has both the flexibility and generality as offered by other popular
general-purpose file specifications, such as [ HDF5]
but with significantly reduced complexity and excellent readability.

Towards this goal, we have developed the JData Specification (
to standardize serializations of complex scientific data structures, such as
N-D arrays, sparse/complex-valued arrays, trees, maps, tables and graphs using
JSON/binary JSON constructs. The text and binary formatted JData files are
syntactically compatible with JSON/UBJSON formats, and can be readily parsed
using existing JSON and UBJSON parsers.

Please note that data files produced by ``saveubjson`` may utilize a special
"optimized header" to store N-D (N>1) arrays, as defined in the JData Specification Draft 2.
This feature is not supported by UBJSON Specification Draft 12. To produce
UBJSON files that can be parsed by UBJSON-Draft-12 compliant parsers, you must
add the option ``'NestArray',1`` in the call to ``saveubjson``.

Please find detailed online help at

External Links:

Cite As

Qianqian Fang (2021). JSONLab (Development Branch) (, GitHub. Retrieved .

Comments and Ratings (7)

Qianqian Fang

@Otis, thanks for reporting this issue. I was able to reproduce the problem and fix it.

Please see my github commit:

What happened was that jsonlab by default removes the square brackets of a single element (controlled by opt.SingletArray). However, in the case of UBJSON, the binary data stream may also contain "]" or "[" which can be accidentally replaced. To avoid this side effect, I used "]$" which only match and remove the ending square bracket. A workaround is to append 'SingletArray', 1 to the end of savejson. This will leave the field enclosed by a pair of []. With this fix, I was able to run your reported case without errors.

Please update your jsonlab and give it a try.

Qianqian Fang

@Raoann, you need to run addpath('/path/to/jsonlab') in order for matlab to find this toolbox. This is required for installing any matlab toolbox.


I came across a weird bug in loadubjson.

The code below crashes in the call to loadubjson.
C.a = 3.779487702;
ubjdata = saveubjson('C', C, 'C.ubjson']);
dat = loadubjson('C.ubjson');

But if you redo this with C.a = 3.779487802, i.e. C.a is different by one digit, it works. There are some numbers for values of a struct field, that after being saved by saveubjson, just can't be read in by loadubjson. I haven't been able to find a pattern that might indicate what is going on.


I have a JSON file that I want to read in Matlab. The file contains values for the production of solar PV and the consumption of a micro-grid. I started by typing these few lined to read the JSON file:

fname = 'Chalokwa Test Bench2.json';
fid = fopen(fname);
raw = fread(fid,inf);
str = char(raw');
val = jsondecode(str);

But, when I type this line:
data = loadjson('Chalokwa Test Bench2.json');

the command window answer that ( loadjson )is undefined, what should I do?
I am a beginner in Matlab and I hope to get some help from you guys.

Best regards

Le Bai

It works well when i load small json file, but when i load the big json file ''instances_train2017.json", Matlab works whole night and not completed, this file is about 460 megabytes in size, that small one is 9 Mb in size and completed takes about 1 min. Does anyone konw how to deal with this problem? Thanks.


Excellent work

Richard Behrens

Hi Qianqian, thanks for the extremely useful toolbox! Here's a bug, though: In a Matlab array of strings which is a field in an array of structures, the "\" characters that are added as escape characters by savejson are not properly stripped off when you loadjson.

MATLAB Release Compatibility
Created with R2010a
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!