Binary JData

A portable interchange format for complex binary data - efficient, strongly-typed, and quasi-human-readable

BJData extends JSON with binary encoding, strongly-typed arrays, and N-dimensional data structures essential for scientific computing. Version 1 (Draft 3) - Frozen March 23, 2025.

🔢 Binary Efficiency

Strongly-typed binary format with Little-Endian encoding for maximum performance

📐 N-D Arrays

Native support for N-dimensional packed arrays in row-major or column-major order

👁️ Quasi-Readable

ASCII type markers make binary data partially human-readable for easy debugging

♾️ Unlimited Size

No file size limits unlike BSON (4GB) or MessagePack (4GB per record)

Scroll to explore the specification

Format Structure

BJData Overview

Every BJData element follows a simple construct: a 1-byte ASCII marker indicating type, followed by optional length and data payload.

[type, 1-byte char] ([integer length]) ([data payload])

Type Marker

A single ASCII character that identifies the data type. For example: i for int8, D for float64.

Length (Optional)

Required for variable-length types like strings. Uses integer type markers for the count.

Data Payload

The actual binary data in Little-Endian byte order (changed from UBJSON's Big-Endian).

                    ⚠️ Important: BJData uses Little-Endian byte order for all numeric values. 
                    This differs from UBJSON (Draft 12) which uses Big-Endian.
                

Data Types

Type Markers Reference

BJData supports a comprehensive set of data types including unsigned integers and half-precision floats not available in standard JSON or UBJSON.

Type	Marker	Size	Range / Notes
null	Z	1 byte	No payload
no-op	N	1 byte	Skip signal / keep-alive
true	T	1 byte	No payload
false	F	1 byte	No payload
int8	i	2 bytes	-128 to 127
uint8	U	2 bytes	0 to 255
int16	I	3 bytes	-32,768 to 32,767
uint16 *	u	3 bytes	0 to 65,535
int32	l	5 bytes	-2.1B to 2.1B
uint32 *	m	5 bytes	0 to 4.3B
int64	L	9 bytes	±9.2×10¹⁸
uint64 *	M	9 bytes	0 to 1.8×10¹⁹
float16 *	h	3 bytes	IEEE 754 half-precision
float32	d	5 bytes	IEEE 754 single
float64	D	9 bytes	IEEE 754 double
high-precision	H	variable	String-encoded number
char	C	2 bytes	ASCII 0-127
byte	B	2 bytes	Raw byte (0-255)
string	S	variable	UTF-8 encoded
array	[ ]	variable	Ordered container
object	{ }	variable	Key-value container

* Types marked with asterisk are BJData extensions not present in UBJSON Draft 12

Containers

Arrays & Objects

Container types support optional optimization parameters for better performance and smaller file sizes.

Basic Array Example

JSON: [null, true, false, 4782345193, 153.132, "ham"]

[[] [Z] [T] [F] [l][4782345193] [d][153.132] [S][i][3][ham] []]

Optimized Containers

Type Marker: $

Specifies uniform type for all elements. Must be followed by count. Only fixed-length types allowed: i,U,I,u,l,m,L,M,h,d,D,C,B

Count Marker: #

Specifies element count. Eliminates need for end marker. Enables pre-allocation for parsing.

Optimized Array Example

5 float32 values with type and count optimization:

[[][$][d][#][i][5] [29.97] [31.13] [67.0] [2.113] [23.8889] // No end marker needed - count specified

Scientific Computing

N-Dimensional Arrays

BJData's killer feature: native support for N-dimensional packed arrays with both row-major (C/Python) and column-major (MATLAB/Fortran) serialization.

2×3×4 uint8 Array Structure

Row-major format (default - C/Python/JavaScript order):

[[] [$][U] [#][[] [$][U][#][3] [2][3][4] [1][9][6][0] [2][9][3][1] [8][0][9][6] [6][4][2][7] [8][5][1][2] [3][3][2][6]

Column-major format (MATLAB/Fortran order) - wrap dimensions in extra array:

[[] [$][U] [#][[] [[] [$][U][#][3] [2][3][4] []] [1][6][2][8] [8][3][9][4] [9][5][0][3] [6][2][3][1] [9][2][0][7] [1][2][6][6]

                💡 Key Insight: The dimensional vector following [#][[] defines the array shape. 
                A single [[]...[]] = row-major. Double [[[]...[]]] = column-major.
            

Try It Live

Interactive BJData Demo

Encode and decode BJData in your browser using a JavaScript implementation.

Encode JSON → BJData

Decode BJData → JSON

Inspect Bytes

Enter JSON data to encode: Encoded BJData (hex view):

Click "Encode to BJData" to see results...

Original JSON size:

-

BJData size:

-

Implementations

Official BJData Parsers

BJData is supported across major programming languages with high-quality, well-tested implementations.

🐍 Python

bjdata

pip install bjdata

📊 MATLAB/Octave

JSONLab

apt install octave-jsonlab

⚡ C++

JSON for Modern C++

nlohmann/json v3.11+

🌐 JavaScript

bjd

npm install bjd

Quick Start Examples

Python

JavaScript

C++

MATLAB

import bjdata as bj

# Encode Python object to BJData
data = {'name': 'experiment', 'values': [1, 2, 3]}
encoded = bj.dumpb(data)

# Decode BJData back to Python
decoded = bj.loadb(encoded)

# File I/O
with open('data.bjd', 'wb') as f:
    bj.dump(data, f)

Learn More

Resources & Links

Explore the full specification, contribute to development, or join the NeuroJSON community.

📄 Full Specification 💻 GitHub Repo 🧠 NeuroJSON Project 📋 JData Spec

Specification Details

Version: 1 (Draft 3)

Status: Frozen March 23, 2025

License: Apache 2.0

File Extension: .bjd

MIME Type: application/jdata-binary

Byte Order: Little-Endian

Maintained by Qianqian Fang <q.fang at neu.edu>
Supported by NIH Grant U24-NS124027 (NeuroJSON)
Derived from UBJSON Specification Draft 12