nfx-serialization

A cross-platform C++20 JSON extensible serialization library with type-safe manipulation, automatic serialization, and schema validation

Overview

nfx-serialization is a modern C++20 library providing comprehensive JSON serialization and deserialization capabilities. It offers type-safe document manipulation, automatic type mapping through an extensible trait system, STL-compatible iterators for arrays and objects, and JSON Schema validation - all optimized for performance across multiple platforms and compilers.

Key Features

📦 Core JSON Components

Document: Generic JSON document abstraction with type-safe value access and manipulation
Serializer: Template-based automatic serialization/deserialization with extensible trait customization
SchemaValidator: JSON Schema Draft 2020-12 validation with detailed error reporting
SchemaGenerator: Automatic JSON Schema generation from sample documents with format detection

🔄 Automatic Type Mapping

POD types (integers, floats, booleans, strings)
STL containers (vector, array, list, deque, set, unordered_set, map, unordered_map)
Smart pointers (unique_ptr, shared_ptr)
Optional types (std::optional, std::nullopt)
Custom types via SerializationTraits specialization
Nested structures and containers

✅ JSON Schema Validation

JSON Schema Draft 2020-12 support
Comprehensive constraint validation (type, required, properties, etc.)
Detailed error reporting with JSON Pointer paths
Custom error messages and validation contexts

📊 Real-World Applications

Configuration management (app settings, environment configs)
API request/response handling (REST, GraphQL)
Data persistence and caching
Inter-process communication (IPC)
Log processing and analysis
Database document storage (NoSQL, MongoDB-style)
Game save states and player data
Message queue payloads (Kafka, RabbitMQ)

⚡ Performance Optimized

Zero-copy document navigation with JSON Pointers
STL-compatible iterators for arrays and objects with range-for support
Compile-time type detection and optimization
Header-only template implementations

🌍 Cross-Platform Support

Linux, Windows
GCC 14+, Clang 18+, MSVC 2022+
Thread-safe operations
Consistent behavior across platforms

Quick Start

Requirements

C++20 compatible compiler:
- GCC 14+ (14.2.0 tested)
- Clang 18+ (19.1.7 tested)
- MSVC 2022+ (19.44+ tested)
CMake 3.20 or higher

CMake Integration

# --- JSON serialization support ---
option(NFX_SERIALIZATION_WITH_JSON             "Enable JSON serialization support"  ON )

# --- Library build types ---
option(NFX_SERIALIZATION_BUILD_STATIC          "Build static library"               OFF)
option(NFX_SERIALIZATION_BUILD_SHARED          "Build shared library"               OFF)

# --- Build components ---
option(NFX_SERIALIZATION_BUILD_TESTS           "Build tests"                        OFF)
option(NFX_SERIALIZATION_BUILD_EXTENSION_TESTS "Build extension tests"              OFF)
option(NFX_SERIALIZATION_BUILD_SAMPLES         "Build samples"                      OFF)
option(NFX_SERIALIZATION_BUILD_BENCHMARKS      "Build benchmarks"                   OFF)
option(NFX_SERIALIZATION_BUILD_DOCUMENTATION   "Build Doxygen documentation"        OFF)

# --- Installation ---
option(NFX_SERIALIZATION_INSTALL_PROJECT       "Install project"                    OFF)

# --- Packaging ---
option(NFX_SERIALIZATION_PACKAGE_SOURCE        "Enable source package generation"   OFF)
option(NFX_SERIALIZATION_PACKAGE_ARCHIVE       "Enable TGZ/ZIP package generation"  OFF)
option(NFX_SERIALIZATION_PACKAGE_DEB           "Enable DEB package generation"      OFF)
option(NFX_SERIALIZATION_PACKAGE_RPM           "Enable RPM package generation"      OFF)
option(NFX_SERIALIZATION_PACKAGE_WIX           "Enable WiX Windows installer (MSI)" OFF)

Using in Your Project

Option 1: Using FetchContent (Recommended)

include(FetchContent)
FetchContent_Declare(
  nfx-serialization
  GIT_REPOSITORY https://github.com/nfx-libs/nfx-serialization.git
  GIT_TAG        main  # or use specific version tag like "0.1.0"
)
FetchContent_MakeAvailable(nfx-serialization)

# Link with static library
target_link_libraries(your_target PRIVATE nfx-serialization::static)

Option 2: As a Git Submodule

# Add as submodule
git submodule add https://github.com/nfx-libs/nfx-serialization.git third-party/nfx-serialization

# In your CMakeLists.txt
add_subdirectory(third-party/nfx-serialization)
target_link_libraries(your_target PRIVATE nfx-serialization::static)

Option 3: Using find_package (After Installation)

find_package(nfx-serialization REQUIRED)
target_link_libraries(your_target PRIVATE nfx-serialization::static)

Building

Build Commands:

# Clone the repository
git clone https://github.com/nfx-libs/nfx-serialization.git
cd nfx-serialization

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake .. -DCMAKE_BUILD_TYPE=Release

# Build the library
cmake --build . --config Release --parallel

# Run tests (optional)
ctest -C Release --output-on-failure

# Run benchmarks (optional)
./bin/Release/BM_JSON_Serialization

Documentation

nfx-serialization includes API documentation generated with Doxygen.

📚 Online Documentation

The complete API documentation is available online at: https://nfx-libs.github.io/nfx-serialization

Building Documentation Locally

# Configure with documentation enabled
cmake .. -DCMAKE_BUILD_TYPE=Release -DNFX_SERIALIZATION_BUILD_DOCUMENTATION=ON

# Build the documentation
cmake --build . --target nfx-serialization-documentation

Requirements

Doxygen - Documentation generation tool
Graphviz Dot (optional) - For generating class diagrams

Accessing Local Documentation

After building, open ./build/doc/html/index.html in your web browser.

Usage Examples

Document - JSON Manipulation

#include <nfx/serialization/json/Document.h>

using namespace nfx::serialization::json;

// Create and manipulate JSON document
Document doc;

// Set values using JSON Pointer notation
doc.set<std::string>("/name", "John Doe");
doc.set<int>("/age", 30);
doc.set<std::string>("/email", "john.doe@example.com");

// Get values with type safety
auto name = doc.get<std::string>("/name");  // optional<string>
auto age = doc.get<int>("/age");            // optional<int>

// Work with nested objects
doc.set<std::string>("/address/city", "New York");
doc.set<std::string>("/address/zip", "10001");

// Arrays
doc.set<std::string>("/hobbies/0", "reading");
doc.set<std::string>("/hobbies/1", "gaming");
doc.set<std::string>("/hobbies/2", "coding");

// Serialize to JSON string
std::string json = doc.toString(2); // Pretty-print with 2-space indent

Serializer - Automatic Type Mapping

#include <nfx/serialization/json/Serializer.h>
#include <vector>
#include <map>

using namespace nfx::serialization::json;

// Simple example with STL containers
std::vector<int> numbers = {1, 2, 3, 4, 5};
std::string json = Serializer<std::vector<int>>::toString(numbers);
// json = "[1,2,3,4,5]"

std::vector<int> restored = Serializer<std::vector<int>>::fromString(json);
// restored == numbers

// Map example
std::map<std::string, int> scores = { {"Alice", 95}, {"Bob", 87} };
std::string scoresJson = Serializer<std::map<std::string, int>>::toString(scores);
// scoresJson = {"Alice":95,"Bob":87}

// With options
Serializer<std::vector<int>>::Options opts;
opts.prettyPrint = true;
std::string prettyJson = Serializer<std::vector<int>>::toString(numbers, opts);

Array Iteration with Range-For

#include <nfx/serialization/json/Document.h>

using namespace nfx::serialization::json;

auto docOpt = Document::fromString(R"({
    "items": [
        {"id": 1, "name": "Item A"},
        {"id": 2, "name": "Item B"},
        {"id": 3, "name": "Item C"}
    ]
})");

if (!docOpt)
{
    return 1;
}

// Get array and iterate with range-for
auto itemsOpt = docOpt->get<Document::Array>("items");
if (itemsOpt)
{
    for (const auto& item : itemsOpt.value())
    {
        auto id = item.get<int64_t>("id");
        auto name = item.get<std::string>("name");
        if (id && name)
        {
            std::cout << "ID: " << *id << ", Name: " << *name << std::endl;
        }
    }
}

Object Iteration with Range-For

#include <nfx/serialization/json/Document.h>

using namespace nfx::serialization::json;

auto docOpt = Document::fromString(R"({
    "config": {
        "timeout": 30,
        "retries": 3,
        "debug": true
    }
})");

if (!docOpt)
{
    return 1;
}

// Get object and iterate with range-for (structured bindings)
auto configOpt = docOpt->get<Document::Object>("config");
if (configOpt)
{
    for (const auto& [key, value] : configOpt.value())
    {
        std::cout << "Key: " << key << ", Value: " << value.toString() << std::endl;
    }
}

SchemaValidator - JSON Schema Validation

#include <nfx/serialization/json/Document.h>
#include <nfx/serialization/json/SchemaValidator.h>

using namespace nfx::serialization::json;

// Define JSON Schema
auto schemaOpt = Document::fromString(R"({
    "type": "object",
    "required": ["name", "age"],
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0, "maximum": 150},
        "email": {"type": "string", "format": "email"}
    }
})");

if (!schemaOpt)
{
    std::cerr << "Invalid schema JSON" << std::endl;
    return 1;
}

// Create validator
SchemaValidator validator(*schemaOpt);

// Validate document
auto dataOpt = Document::fromString(R"({"name": "John", "age": 30, "email": "john@example.com"})");
if (!dataOpt) {
    std::cerr << "Invalid data JSON" << std::endl;
    return 1;
}

ValidationResult result = validator.validate(*dataOpt);
if (result.isValid())
{
    std::cout << "Document is valid!" << std::endl;
}
else
{
    std::cout << "Validation errors:" << std::endl;
    for (const auto& error : result.errors())
    {
        std::cout << "  - " << error.toString() << std::endl;
    }
}

SchemaGenerator - Automatic Schema Generation

#include <nfx/serialization/json/Document.h>
#include <nfx/serialization/json/SchemaGenerator.h>

using namespace nfx::serialization::json;

// Sample data
auto dataOpt = Document::fromString(R"({
    "name": "John Doe",
    "age": 30,
    "email": "john@example.com",
    "tags": ["developer", "manager"],
    "address": {
        "city": "New York",
        "zip": "10001"
    }
})");

if (!dataOpt)
{
    std::cerr << "Invalid data JSON" << std::endl;
    return 1;
}

// Generate schema with options
SchemaGenerator::Options opts;
opts.inferFormats = true;        // Detect email, date, URI, etc.
opts.title = "User Schema";
opts.description = "Generated from sample data";

SchemaGenerator generator(*dataOpt, opts);
const Document& schema = generator.schema();

// Output generated schema
std::cout << schema.toString(2) << std::endl;

Sample Output:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User Schema",
  "description": "Generated from sample data",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "address": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        },
        "zip": {
          "type": "string"
        }
      },
      "required": ["city", "zip"]
    }
  },
  "required": ["name", "age", "email", "tags", "address"]
}

Complete Example

#include <iostream>
#include <vector>
#include <nfx/serialization/json/Document.h>
#include <nfx/serialization/json/Serializer.h>

int main()
{
    using namespace nfx::serialization::json;

    // Create a JSON document
    Document doc;
    doc.set<std::string>( "/title", "My Application" );
    doc.set<std::string>( "/version", "1.0.0" );

    // Add array of users
    std::vector<std::string> users = { "Alice", "Bob", "Charlie" };
    std::string usersJson = Serializer<std::vector<std::string>>::toString( users );
    auto usersDoc = Document::fromString( usersJson );
    if ( usersDoc )
    {
        doc.set<Document>( "/users", *usersDoc );
    }

    // Add configuration object
    doc.set<bool>( "/config/debug", true );
    doc.set<int>( "/config/timeout", 30 );

    // Print JSON
    std::string json = doc.toString( 2 );
    std::cout << "Generated JSON:\n"
              << json << std::endl;

    // Iterate users with range-for
    auto usersArrayOpt = doc.get<Document::Array>( "/users" );
    if ( usersArrayOpt )
    {
        std::cout << "\nUsers:" << std::endl;
        for ( const auto& userDoc : usersArrayOpt.value() )
        {
            auto user = userDoc.get<std::string>( "" );
            if ( user )
            {
                std::cout << "  - " << *user << std::endl;
            }
        }
    }

    // Deserialize users back
    auto usersDocOpt = doc.get<Document>( "/users" );
    if ( usersDocOpt )
    {
        std::string usersArrayJson = usersDocOpt->toString();
        std::vector<std::string> restored = Serializer<std::vector<std::string>>::fromString( usersArrayJson );
        std::cout << "\nRestored " << restored.size() << " users" << std::endl;
    }

    return 0;
}

Sample Output:

Generated JSON:
{
  "title": "My Application",
  "version": "1.0.0",
  "users": [
    "Alice",
    "Bob",
    "Charlie"
  ],
  "config": {
    "debug": true,
    "timeout": 30
  }
}

Users:
  - Alice
  - Bob
  - Charlie

Restored 3 users

Custom Traits - Extending for Your Types

The serializer can work with your custom container types and user-defined structures through a simple trait system. There are two main approaches:

Approach 1: Mark Custom Containers (Trait Specialization)

If you have a custom container that implements a standard container interface (iterators, typedefs, insert/operator[]), you can mark it as a container so the Serializer treats it like STL containers:

// Your custom containers
template<typename K, typename V>
struct CustomHashMap {
    using key_type = K;
    using mapped_type = V;
    using value_type = std::pair<const K, V>;

    V& operator[](const K& key);
    auto begin() -> /* iterator */;
    auto end() -> /* iterator */;
    // ... other container methods
};

template<typename T>
struct CustomSet {
    using value_type = T;

    void insert(const T& value);
    auto begin() -> /* iterator */;
    auto end() -> /* iterator */;
    // ... other container methods
};

// Specialize the trait in the detail namespace
namespace nfx::serialization::json::detail {
    template<typename K, typename V>
    struct is_container<CustomHashMap<K,V>> : std::true_type {};

    template<typename T>
    struct is_container<CustomSet<T>> : std::true_type {};
}

// Now use them like STL containers
CustomHashMap<std::string, int> myMap;
myMap["answer"] = 42;
std::string json = Serializer<CustomHashMap<std::string, int>>::toString(myMap);

Container Interface Requirements:

For sequence containers (vector, list, set):

using value_type = T;
begin() / end() returning iterators
insert(const value_type&) for deserialization

For associative containers (map, unordered_map):

using key_type = K;
using mapped_type = V;
using value_type = std::pair<const K, V>;
operator[](const key_type&) for deserialization
begin() / end() returning iterators

Approach 2: Custom Serialization Logic (`SerializationTraits`)

For types that need special handling or don't fit the container model, implement SerializationTraits:

struct Point3D {
    double x, y, z;
};

template<>
struct SerializationTraits<Point3D> {
    static void serialize(const Point3D& point, Document& doc) {
        doc.set<double>("/x", point.x);
        doc.set<double>("/y", point.y);
        doc.set<double>("/z", point.z);
    }

    static void deserialize(Point3D& point, const Document& doc) {
        point.x = doc.get<double>("/x").value_or(0.0);
        point.y = doc.get<double>("/y").value_or(0.0);
        point.z = doc.get<double>("/z").value_or(0.0);
    }
};

// Usage
Point3D origin{0, 0, 0};
std::string json = Serializer<Point3D>::toString(origin);
// Result: {"x":0.0,"y":0.0,"z":0.0}

Key Points:

Container trait specializations go in nfx::serialization::json::detail namespace
SerializationTraits specializations go in nfx::serialization::json namespace
You don't modify library code - just expose the minimal interface
Mix both approaches: use trait marking for containers, SerializationTraits for custom logic
See samples/Sample_JsonSerializer.cpp for complete working examples

Optional Extensions

nfx-serialization provides optional integration headers for other nfx libraries. These headers use conditional compilation (__has_include()) and are safe to include even if the external library is not installed:

Available Extensions

extensions/ContainersTraits.h - Serialization support for nfx-containers types
- nfx::containers::PerfectHashMap - Compile-time perfect hash map
- nfx::containers::FastHashMap - Runtime open-addressing hash map
- nfx::containers::FastHashSet - Runtime open-addressing hash set
extensions/DatatypesTraits.h - Serialization support for nfx-datatypes types
- nfx::datatypes::Int128 - 128-bit integer (cross-platform)
- nfx::datatypes::Decimal - Fixed-point decimal arithmetic
extensions/DateTimeTraits.h - Serialization support for nfx-datetime types
- nfx::time::DateTime - Date and time representation (ISO 8601)
- nfx::time::DateTimeOffset - Date and time with timezone offset
- nfx::time::TimeSpan - Duration/time interval

Usage

#include <nfx/serialization/json/Serializer.h>
#include <nfx/serialization/json/extensions/ContainersTraits.h>  // Optional
#include <nfx/serialization/json/extensions/DateTimeTraits.h>    // Optional

#include <nfx/containers/FastHashMap.h>   // Requires nfx-containers
#include <nfx/datetime/DateTime.h>        // Requires nfx-datetime

using namespace nfx::serialization::json;

// Serialize nfx types just like STL types
nfx::containers::FastHashMap<std::string, int> scores;
scores.insertOrAssign("Alice", 95);
scores.insertOrAssign("Bob", 87);

std::string json = Serializer<decltype(scores)>::toString(scores);

// DateTime serialization
nfx::time::DateTime now = nfx::time::DateTime::now();
std::string timeJson = Serializer<nfx::time::DateTime>::toString(now);
// Result: "2025-11-30T10:30:45.123Z" (ISO 8601)

Note: These extensions are header-only and zero-cost - if you don't include them or don't have the external library installed, they have no impact on compile time or binary size.

Installation & Packaging

nfx-serialization provides packaging options for distribution.

Package Generation

# Configure with packaging options
cmake .. -DCMAKE_BUILD_TYPE=Release \
         -DNFX_SERIALIZATION_BUILD_STATIC=ON \
         -DNFX_SERIALIZATION_BUILD_SHARED=ON \
         -DNFX_SERIALIZATION_PACKAGE_ARCHIVE=ON \
         -DNFX_SERIALIZATION_PACKAGE_DEB=ON \
         -DNFX_SERIALIZATION_PACKAGE_RPM=ON

# Generate binary packages
cmake --build . --target package
# or
cd build && cpack

# Generate source packages
cd build && cpack --config CPackSourceConfig.cmake

Supported Package Formats

Format	Platform	Description	Requirements
TGZ/ZIP	Cross-platform	Compressed archive packages	None
DEB	Debian/Ubuntu	Native Debian packages	`dpkg-dev`
RPM	RedHat/SUSE	Native RPM packages	`rpm-build`
WiX	Windows	Professional MSI installer	`WiX 3.11+`
Source	Cross-platform	Source code distribution (TGZ+ZIP)	None

Installation

# Linux (DEB-based systems)
sudo dpkg -i nfx-serialization_*_amd64.deb

# Linux (RPM-based systems)
sudo rpm -ivh nfx-serialization-*-Linux.rpm

# Windows (MSI installer)
nfx-serialization-0.1.0-MSVC.msi

# Manual installation (extract archive)
tar -xzf nfx-serialization-*-Linux.tar.gz -C /usr/local/

Project Structure

nfx-serialization/
├── benchmark/             # Performance benchmarks with Google Benchmark
├── cmake/                 # CMake modules and configuration
├── include/nfx/           # Public headers: Document, Serializer, SchemaValidator
├── samples/               # Example usage and demonstrations
├── src/                   # Implementation files
└── test/                  # Comprehensive unit tests with GoogleTest

Performance

For detailed performance metrics and benchmarks, see the benchmark documentation.

Roadmap

See TODO.md for upcoming features and project roadmap.

Changelog

See the CHANGELOG.md for a detailed history of changes, new features, and bug fixes.

License

This project is licensed under the MIT License.

Dependencies

nfx-stringutils: String validation utilities (MIT License) - Core dependency
nlohmann/json: Modern JSON library for C++ (MIT License) - Core dependency

Development Dependencies

GoogleTest: Testing framework (BSD 3-Clause License) - Development only
Google Benchmark: Performance benchmarking framework (Apache 2.0 License) - Development only

All dependencies are automatically fetched via CMake FetchContent when building the library, tests, or benchmarks.

Updated on December 20, 2025

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github		.github
benchmark		benchmark
cmake		cmake
doc		doc
include/nfx		include/nfx
licenses		licenses
samples		samples
src/json		src/json
test		test
testdata		testdata
.clang-format		.clang-format
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CMakeLists.txt		CMakeLists.txt
LICENSE.txt		LICENSE.txt
README.md		README.md
TODO.md		TODO.md

License

nfx-libs/nfx-serialization

Folders and files

Latest commit

History

Repository files navigation

nfx-serialization

Overview

Key Features

📦 Core JSON Components

🔄 Automatic Type Mapping

✅ JSON Schema Validation

📊 Real-World Applications

⚡ Performance Optimized

🌍 Cross-Platform Support

Quick Start

Requirements

CMake Integration

Using in Your Project

Option 1: Using FetchContent (Recommended)

Option 2: As a Git Submodule

Option 3: Using find_package (After Installation)

Building

Documentation

📚 Online Documentation

Building Documentation Locally

Requirements

Accessing Local Documentation

Usage Examples

Document - JSON Manipulation

Serializer - Automatic Type Mapping

Array Iteration with Range-For

Object Iteration with Range-For

SchemaValidator - JSON Schema Validation

SchemaGenerator - Automatic Schema Generation

Complete Example

Custom Traits - Extending for Your Types

Approach 1: Mark Custom Containers (Trait Specialization)

Approach 2: Custom Serialization Logic (SerializationTraits)

Optional Extensions

Available Extensions

Usage

Installation & Packaging

Package Generation

Supported Package Formats

Installation

Project Structure

Performance

Roadmap

Changelog

License

Dependencies

Development Dependencies

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Languages

Approach 2: Custom Serialization Logic (`SerializationTraits`)