Binary JData

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

📋 Synopsis

Format overview

🔢 Type Markers

Data type reference

📐 N-D Arrays

Multi-dimensional data

⚡ Optimized

Compact containers

📋 BJData Format Synopsis

Universal Construct

[type] [length]? [data]?

1-byte ASCII marker + optional length + optional payload

Value Types

                                    Z=null T=true F=false

                                    i=int8 U=uint8 I=int16

                                    l=int32 L=int64 d=float32

Containers

                                    [ ... ] = array

                                    { ... } = object

                                    $=type #=count

                            Example: {"val": 42}

                            { i3val i42 }
                            ← Little-Endian
                        

📄 Full Specification (Draft 3) →

🔢 Type Marker Reference

Z T F N

null, bool, no-op

i U I u

int8/16, uint8/16

l m L M

int32/64, uint32/64

h d D

float16/32/64

S C H

string, char, high-prec

[ ] { }

array, object

BJData extensions: u uint16, m uint32, M uint64, h float16

📐 N-Dimensional Arrays

Native packed arrays with row-major or column-major ordering.

// 2×3 uint8 matrix (row-major)
[[] [$][U] [#][[] [$][U][#][i][2] [2][3]
    [1][2][3]  // row 0
    [4][5][6]  // row 1

// Column-major: wrap dims in [[]]
[[] [$][U] [#][[] [[]...[]]
    [1][4][2][5][3][6]

⚡ Optimized Containers

Use $ (type) and # (count) for compact storage.

// Regular array (with type markers)
[[] [d][1.5] [d][2.5] [d][3.5] []]

// Optimized: type + count header
[[] [$][d] [#][i][3]
    [1.5] [2.5] [3.5]
// No end marker, no type markers!

// Valid types: i,U,I,u,l,m,L,M,h,d,D,C,B

BJData extends JSON with binary encoding and N-dimensional arrays for scientific computing. Version 1 (Draft 3) - Frozen March 23, 2025. All values in Little-Endian order.

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