What Is SaJSON?

SaJSON is a lightweight, header-only C++ JSON library designed to provide a clean and minimal API for parsing, constructing, and serializing JSON data. Unlike heavyweight alternatives that rely on extensive template metaprogramming or SIMD optimizations, SaJSON takes a pragmatic approach: deliver correctness and ease of use with a small codebase and near-zero compilation overhead.

The library targets developers who need JSON support in C++ projects but want to avoid the compile-time penalty and dependency bloat associated with larger ecosystems. Its design emphasizes explicit type handling, clear error reporting, and predictable behavior across compiler versions and platforms.

Architecture and Design Philosophy

Header-Only by Design

SaJSON is distributed as a single-header library. There are no compiled binaries, no CMake targets, and no package manager dependencies. The entire implementation resides in one .hpp file, which can be dropped into any project's include path. This design decision has two major implications:

1. Zero-link builds: Since everything is inlined at the include site, link times remain unaffected.
2. Version pinning is trivial: Updating SaJSON is as simple as replacing the header file — no rebuild of dependent shared libraries is required.

Memory Management Model

SaJSON uses a copy-on-write–inspired approach combined with small-string optimization (SSO) for compact representations. Strings up to 15 characters are stored directly within the JSON value struct, avoiding heap allocation for the common case of short keys and values. Larger strings trigger a single heap allocation with reference counting.

Error Handling Strategy

Rather than throwing exceptions by default, SaJSON provides a dual-mode error system:

• Return-code mode: Functions return a status code or optional result, allowing callers to handle errors without exception overhead.
• Exception mode: When enabled via compile flag, malformed input throws a typed exception with a descriptive message and line/column position.

This dual approach is uncommon among modern JSON libraries and gives SaJSON a distinct advantage in performance-critical and embedded contexts where exception handling is either disabled or incurs measurable cost.

Core API Walkthrough

Parsing JSON

#include "sajson.hpp"

sajson::Result<sajson::Value> result = sajson::parse(
    sajson::StringView(buffer, length)
);

if (result.is_success()) {
    sajson::Value document = result.get_value();
}

Constructing JSON Documents

sajson::Document doc;
auto root = doc.add_object();
root["name"] = doc.create_string("sajson");
root["version"] = doc.create_integer(2);
root["features"] = doc.create_array();
root["features"].append(doc.create_string("header-only"));
root["features"].append(doc.create_string("fast-parse"));

Serialization and Output

SaJSON supports both pretty-printed and compact output through a writer abstraction:

sajson::String allocator;
sajson::write(document, allocator);
std::string output = allocator.to_string(); // compact
// or
sajson::write_pretty(document, allocator); // indented

Performance Comparison

The following table compares SaJSON against the most widely used C++ JSON libraries across key dimensions. Benchmarks are synthesized from publicly available benchmark suites (JSONBench, rapidjson benchmarks, nlohmann self-benchmarks) and represent median results across 64-bit x86-64 Linux with -O3.