JSONLab - Compact JSON/Binary JSON Encoder for MATLAB/Octave

JSONLab

Compact, portable, robust JSON/binary-JSON encoder/decoder for MATLAB/Octave

Version 2.9.8 MATLAB R2008+ GNU Octave 3.8+ BSD/GPL v3 License NIH Funded

📋 What is JSONLab?

JSONLab is a comprehensive, open-source JSON/UBJSON/MessagePack encoder and decoder written entirely in native MATLAB language. It provides seamless conversion between MATLAB data structures and multiple serialization formats.

As the official reference implementation for both JData and BJData specifications, JSONLab enables unambiguous storage and exchange of complex scientific data structures across diverse programming environments.

🏆 NeuroJSON Project

JSONLab is part of the NeuroJSON project (neurojson.org), funded by US NIH grant U24-NS124027. The project develops scalable, searchable, and reusable neuroimaging data formats using JSON/Binary JData as underlying serialization standards.

14+
Years Active
55K+
Downloads
12K+
GitHub Clones
70+
Functions
View on GitHub See Examples Documentation

⚡ Core Capabilities

  • Universal Compatibility: Works seamlessly across MATLAB R2008+ and GNU Octave 3.8+, ensuring broad accessibility
  • Multi-Format Support: Native support for JSON, Binary JData, UBJSON, MessagePack, and HDF5 formats
  • Complex Data Types: Full support for N-D arrays, sparse matrices, complex numbers, tables, and graphs
  • Type Preservation: Maintains exact data types during serialization and deserialization
  • Zero Dependencies: Written entirely in native MATLAB/Octave code with no external requirements
  • Cross-Platform: Works identically on Windows, Linux, and macOS systems
View Examples Browse Functions

🚀 High-Performance Features

  • Fast Array Parser: Highly optimized parser specifically designed for large N-D arrays, achieving up to 200% speed improvement over standard parsing
  • Binary Formats: Binary JData and UBJSON provide significantly smaller file sizes (up to 50% reduction) and faster I/O operations
  • Multi-Algorithm Compression: Support for zlib, gzip, lzma (highest compression), lz4 (fastest), lz4hc, and blosc2 meta-compressor
  • Streaming Support: Process large datasets without loading entire files into memory
  • Memory-Efficient: Optimized memory usage for handling large-scale scientific data
  • JIT-Compatible: Code structure optimized for MATLAB's Just-In-Time compiler
Performance Examples

💾 Supported Data Formats

📄 Text-Based Formats

  • JSON: Standard JSON with JData annotations
  • .jdt: JData text files
  • .jnii: JSON-based NIfTI neuroimaging format
  • .jmsh: JSON mesh data
  • .jnirs: JSON fNIRS data format

💿 Binary Formats

  • BJData: Binary JData (Draft 2)
  • UBJSON: Universal Binary JSON
  • MessagePack: Efficient binary serialization
  • .pmat: Portable MATLAB session files
  • HDF5: Hierarchical Data Format
JData Spec BJData Spec

🛠️ Advanced Tools & Features

🗺️ JSON Memory-Map (JSON-Mmap)

  • Fast random access without full parsing
  • Disk-map-like read/write operations
  • JSONPath-based indexing
  • Efficient for large files

🔍 JSONPath Query Engine

  • XPath-like data navigation
  • Deep-scan operators (..)
  • Array slicing and filtering
  • Wildcard support

🔗 Data Linking & Caching

  • Dynamic external file loading via _DataLink_
  • Automatic caching system
  • On-demand data download
  • Modular dataset management

🌐 Cross-Platform Integration

  • Python: pyjdata and pybj modules
  • JavaScript: Standard JSON compatibility
  • Built-in compression/decompression
  • Base64 encoding utilities
View Examples JSON-Mmap Spec

Key Features

Everything you need for JSON and binary JSON processing

📦

Multiple Formats

Support for JSON, Binary JData, UBJSON, MessagePack, and HDF5 formats with unified interface

⚡

High Performance

Fast array parser optimized for reading JSON files with large N-D arrays

🗜️

Compression

Built-in support for zlib, gzip, lzma, lz4, and blosc2 compression algorithms

🔗

Data Linking

Dynamic data linking with _DataLink_ annotation for modular dataset management

🗺️

Memory Mapping

JSON-Mmap for rapid disk-map-like reading/writing without parsing entire files

🎯

JSONPath

Query and navigate complex data structures using JSONPath expressions

Code Examples

Quick start with JSONLab

% Save MATLAB data to JSON with savejson
data = struct('name', 'JSONLab', 'version', 2.9, 'array', [1,2,3]);
savejson('', data, 'filename', 'output.json');

% Load JSON file with loadjson
data = loadjson('output.json');

% Unified interface: savejd/loadjd auto-detect format
savejd('', data, 'output.json');
data = loadjd('output.json');
% JData format: encode complex MATLAB data with jdataencode
raw = struct('complex', 2+4i, 'sparse', sparse(eye(5)));
encoded = jdataencode(raw);
savejson('', encoded);

% Decode JData back to MATLAB with jdatadecode
decoded = jdatadecode(encoded);

% 3D arrays with type preservation
data3d = reshape(1:24, 2, 3, 4);
savejson('', data3d, 'NestArray', 0);

% Compressed arrays in JSON/BJData
savejson('', eye(100), 'Compression', 'zlib', 'CompressArraySize', 1);
% Binary JData with savebj/loadbj (smaller, faster)
data = struct('string', 'value', 'array', single([1 2 3]));
savebj('', data, 'filename', 'data.bjd');
data = loadbj('data.bjd');

% MessagePack with savemsgpack/loadmsgpack
savemsgpack('', data, 'data.msgpk');
data = loadmsgpack('data.msgpk');

% UBJSON with saveubjson/loadubjson
saveubjson('', data, 'data.ubj');
data = loadubjson('data.ubj');
% Query data structures with jsonpath
data = struct('book', struct('title', {'Yoda', 'Jinn', 'Kenobi'}, ...
              'author', {'Master', 'Qui-Gon', 'Obi-Wan'}));

% Get nested field
titles = jsonpath(data, '$.book.title')

% Deep scan with .. operator
authors = jsonpath(data, '$..author')

% Array slicing [start:end]
first_two = jsonpath(data, '$.book.title[0:1]')

% Negative indices (last element)
last_item = jsonpath(data, '$.book.title[-1]')
% jdict: xarray-like attribute access for MATLAB
data = struct('exp', struct('trials', rand(10,5)));
jd = jdict(data);

% Access nested fields with ()
trials = jd.('exp').('trials');

% Use JSONPath syntax
trials = jd.('$.exp.trials');

% Modify values with .v() accessor
jd.('exp').('trials').v(1) = 999;

% Add xarray-like attributes with {}
jd.('exp').('trials'){'dims'} = {'time', 'channels'};
jd.('exp').('trials'){'units'} = 'microvolts';
% jdlink: dynamically download from REST APIs
% Load dataset from NeuroJSON.io with loadjson
ds = loadjson('https://neurojson.io:7777/openneuro/ds000001');

% Find linked files with jsonpath
links = jsonpath(ds, '$..anat.._DataLink_');

% Download files matching regex pattern with jdlink
files = jdlink(links, 'regex', 'sub-01_.*\.nii');

% Check cache location with jsoncache
[cache_path, fname] = jsoncache(...
    'https://neurojson.io:7777/openneuro/ds000001');

% Files cached in ~/.neurojson/ for fast reuse

Core Functions

Comprehensive API for all your needs

JSON Processing

  • savejson / loadjson
  • savebj / loadbj
  • saveubjson / loadubjson
  • savemsgpack / loadmsgpack
  • savejd / loadjd (unified)

JData Encoding

  • jdataencode
  • jdatadecode
  • jsave / jload

Memory Mapping

  • jsonget / jsonset
  • jsonpath
  • filterjsonmmap

Compression

  • zlibencode / zlibdecode
  • gzipencode / gzipdecode
  • lzmaencode / lzmadecode
  • lz4encode / lz4decode
  • base64encode / base64decode

Data Linking

  • jdlink
  • jsoncache

Utilities

  • encodevarname
  • decodevarname
  • jsonopt
  • mergestruct

Installation

Get started in minutes

📦 Manual Installation

Download and add to MATLAB path:

addpath('/path/to/jsonlab');
rehash;

🐧 Debian/Ubuntu

Install via package manager:

sudo apt-get install octave-jsonlab

🎩 Fedora

Install official package:

sudo dnf install octave-jsonlab
sudo dnf install octave-zmat

🔧 From Source

Clone from GitHub:

git clone https://github.com/NeuroJSON/jsonlab.git

Ready to Get Started?

Join thousands of researchers using JSONLab

14+
Years Development
55K+
MATLAB Downloads
12K+
GitHub Clones (Bi-weekly)
Download Latest Release Documentation

Supported by NIH Grant U24-NS124027

BSD or GPL v3 License

Powered by Habitat