JSONLab: a toolbox to encode/decode JSON files

A toolbox to encode/decode JSON/UBJSON/MessagePack files in MATLAB/Octave
Updated 14 Jun 2020

View License

Editor's Note: Popular File 2018

This file was selected as MATLAB Central Pick of the Week

** JSONLab 2.0 Final (Magnus Prime) is released on 06/14/2020.**
Release URL: https://github.com/fangq/jsonlab/releases/tag/v2.0
Depends on: https://www.mathworks.com/matlabcentral/fileexchange/71434-zmat
Data format according to
- JData Specification Draft-3: http://github.com/OpenJData/jdata, and
- Binary JData Specification Draft-1: http://github.com/OpenJData/bjdata
Python modules to read/write JSONLab files:
- jdata: https://pypi.org/project/jdata/
- bjdata: https://pypi.org/project/bjdata/

JSONLab is a free and open-source JSON/UBJSON/MessagePack encoder and
decoder written 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 and files, or to parse a
JSON/UBJSON/MessagePack file into MATLAB data structure. JSONLab supports both
MATLAB and GNU Octave [http://www.gnu.org/software/octave] (a free MATLAB clone).

JSON (JavaScript Object Notation, http://www.json.org/) is a highly portable,
human-readable and "fat-free" text format to represent complex and hierarchical
data, widely used for data-exchange in applications. UBJSON (Universal Binary JSON,
http://ubjson.org/ ) is a binary JSON format, designed to specifically address the
limitations of JSON, permitting efficient storage of binary data with strongly typed
data records, resulting in smaller file sizes and fast encoding and decoding.
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 to UBJSON.

We envision that both JSON and its binary counterparts will play important
rules not only for light-weight data storage, but also for storage and interchange
of scientific data. It has both the flexibility and generality as in other general-purpose
file specifications, such as HDF5 [http://www.hdfgroup.org/HDF5/whatishdf5.html]
but has significantly reduced complexity and excellent readability.

Towards this goal, we have developed the JData Specification (http://github.com/fangq/jdata)
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. JSONLab is not just a parser and writer
of JSON/UBJSON data files, but one that systematically converts complex scientific
data structures into human-readable and universally supported JSON forms using the
standardized JData data annotations.

Please find detailed online help at http://iso2mesh.sf.net/cgi-bin/index.cgi?jsonlab/Doc

== What's New ==

JSONLab v2.0 - code named "Magnus Prime" - is a stable release of JSONLab and
a new milestone towards a stable, complete reference implementation of the
JData Specification (http://openjdata.org) for portable scientific data storage.

There have been many major updates added to this release since the previous
release v1.9.8 in Oct. 2019. A list of the major changes are summarized below
(with key features marked by *), including the support to `_ArrayShape_` to
efficiently encode special matrices and the addition of `jsave/jload` to save
and restore variables in MATLAB/Octave like the `save/load` commands (experimental).

=== jsave.m ===

jsave % save the current workspace to jamdata.jamm
jsave mydata.jamm

=== jload.m ===

jload % load variables from jamdata.jamm to the current workspace
jload mydata.jamm % load variables

== Other updates

*change default workspace to caller for jload and jsave
*created `jdata` and `bjdata` python modules to share data with MATLAB
*add savebj and loadbj to dedicate to loading and saving bjdata
*add unit testing script, fix issues found in the testing unit
*accelerate fast_match_bracket, drop unicode2native for speed
*support Toeplitz matrices, use case-insensitive comparison
*jdatadecode now handles _ArrayOrder_
*add keeptype option to jsave and saveubjson
*make jsave and jload work on octave
*apply data compression to strings, new datatype char
*fix loadmsgpack ND array issue
*add jsave and jload for portable data sharing
*adding support to _ArrayShape_ to record special matrices
*jsonlab is compatible with matlab R2008
*saveubjson now implments BJData spec Draft1,https://github.com/fangq/bjdata
*add UseMap option to avoid key name conversion
*reduce jsonopt calls to speed up encoding and decoding
*enable jdataencode in savejson and saveubjson

Cite As

Qianqian Fang (2024). JSONLab: a toolbox to encode/decode JSON files (https://www.mathworks.com/matlabcentral/fileexchange/33381-jsonlab-a-toolbox-to-encode-decode-json-files), MATLAB Central File Exchange. Retrieved .

MATLAB Release Compatibility
Created with R2008a
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!
Version Published Release Notes

- fix bjdata spec link


- add unit testing script
- apply data compression to strings
- add jsave and jload for portable data sharing
- compatible with R2008
- add UseMap option output containers.Map
- supports BJData spec Draft 1
- add _ArrayShape_ to save special matrices

- update documentation, finalize 1.0
- fix a bug to strictly respect NoRowBracket in savejson

- fix UBSJON data endianness for all integer types
- fix several compatibility issues for GNU octave
- support 2D cell and struct arrays
- escape special characters in a JSON string
- fix a bug when saving UBSJON files

- update to jsonlab 1.0 beta release
- fix file read and write bugs in loadubjson and saveubjson

update to 1.0 alpha release, included functions (saveubjson and loadubjson) for writing and reading Universal Binary JSON files


- 2012/06/17 *new format for an invalid leading char, unpacking hex code in savejson
- 2012/06/01 support JSONP in savejson
- 2012/05/25 fix the empty cell bug
- 2012/04/05 savejson can save to a file

- fix a bug in saveubjson when saving integer 256

- fix openjdata.org link

- update savejson and saveubjson license statement

-Avoid double expanding arrayzipdata in savejson and saveubjson


-Official reference implementation for JData Spec Draft 2(http://github.com/fangq/jdata)
-Initial support to MessagePack
-ND array serialization changed from column-major->row-major
-Support LZMA/LZ4/LZHC compression
-Support graph,table,class&object



2012/02/28 loadjson quotation mark escape bug, see http://bit.ly/yyk1nS
2012/01/25 patch to handle root-less objects, contributed by Blake Johnson
- 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

-2012/01/13 speed up loadjson by 20 fold when parsing large data arrays in matlab
-2012/01/11 remove row bracket if an array has 1 element
-2011/12/22 accept sequence of 'param',value input
-2011/11/18 fix struct array bug


-use Big-endian format to store floating points (d/D) in saveubjson
-speedup parsing large unstructured data
-make parsing independent of whitespace
-allow to parse array of homogeneous elements
-fix a bug that prevents saving to a file in savejson


2011/10/21 fix a bug in loadjson, previous code does not use any of the acceleration
2011/10/20 loadjson supports JSON collections: appendable JSON objects

- 2x speed in savejson (Issue#17)
- fix FileName case bug (SVN rev#495)
- add SingletCell/SingletArray flags (Issue#15,#8)
- fix file name bug (Pull#14)
- fix bug for cell with transposed data (Pull#12)
- export matlab object to JSON (Pull#10,#11)
- 2x speed in savejson (Issue#17)
- fix FileName case bug (SVN rev#495)
- add SingletCell/SingletArray flags (Issue#15,#8)
- fix file name bug (Pull#14)
- fix bug for cell with transposed data (Pull#12)
- export matlab object to JSON (Pull#10,#11)
- 2x speed in savejson (Issue#17)
- fix FileName case bug (SVN rev#495)
- add SingletCell/SingletArray flags (Issue#15,#8)
- fix file name bug (Pull#14)
- fix bug for cell with transposed data (Pull#12)
- export matlab object to JSON (Pull#10,#11)
- 2x speed in savejson (Issue#17)
- fix FileName case bug (SVN rev#495)
- add SingletCell/SingletArray flags (Issue#15,#8)
- fix file name bug (Pull#14)
- fix bug for cell with transposed data (Pull#12)
- export matlab object to JSON (Pull#10,#11)

-massively accelerating loadjson
-parse logicals in loadjson
-make options case insensitive
-reading unicode encoded json files
-allow \uXXXX in a unicode in a string
-handle escape characters in a string
-implement the UBJSON Draft12 new name format