File Exchange

image thumbnail


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


Updated 06 May 2019

GitHub view license on GitHub

** JSONLAB v1.9 (Magnus - alpha) is released on 05/06/2019.**

Release URL:
(Optional) Data compression/decompression:

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

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, and is essential for the wild success of Ajax and Web2.0.

UBJSON (Universal Binary JSON) is a binary JSON format, 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.

JSONLab provides two functions, loadjson.m -- a MATLAB->JSON decoder,
and savejson.m -- a MATLAB->JSON encoder, for the text-based JSON, and
two equivalent functions -- loadubjson and saveubjson for the binary
JSON. The savejson, loadubjson and saveubjson functions were written by
Qianqian Fang, while the loadjson.m script was derived from the previous works cited in the Acknowledgement section.

Please find detailed online help at

== What's New ==

JSONLab v1.9 is the alpha release of the next milestone - code named "Magnus".

The biggest change in this release, compared to v1.8 released in July 2018, is the support of data compression via the 'Compression' option for both savejson and saveubjson. Two compression methods are currently supported - "zlib" and "gzip". The compression interfaces, zlibencode/zlibdecode/gzipencode/ gzipdecode are modified from the "Byte Encoding Utilities" by Kota Yamaguchi [1], which has built-in support for java-based compression in MATLAB (when jvm is enabled). To support Octave, as well as MATLAB in "nojvm" mode, a mex-based data compression/encoding toolbox, ZMat [2], written by Qianqian Fang, takes priority over the java-based utilities, if installed. For savejson, a 'base64' encoding is applied to convert the compressed binary stream into a string; 'base64' encoding is not used in saveubjson. The encoding and restoration of the binary matlab arrays are automatically handled in save*json/load*json round-trip conversions.

To save matlab data with compression, one simply append 'Compression', 'method' pair in the savejson/saveubjson call. For example


In addition, the below features are added to JSONLab

* save function handles
* support saving "string" class in MATLAB
* fix two bugs in saveubjson
* unescape strings in loadjson

External Links:

Cite As

Qianqian Fang (2019). JSONLab (, GitHub. Retrieved .

Comments and Ratings (7)

@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.

@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

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.



- unescape strings in loadjson.m
- support zmat base64 encoding
- support data compression
- support function handles
- add option to parse string array or convert to char
- treat string array as cell array in newer matlab
- save 64bit int in ubjson

== JSONlab 1.8 (codename: Nominus - final) ==
- support strings object
- support MATLAB table objects
- fix octave warning for saveubjson
- avoid error in matlab 2017a, close #34
- added package.json
- added README.rst
- respect integer types

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