README.md

pjson Tutorials

Welcome! pjson ("Praveen's JSON") is an ultra-simple JSON library for C++. This tutorial series takes you from never having used JSON all the way to building a complete, schema-validated application — one small step at a time.

You do not need any prior JSON experience. We explain every concept as it comes up.

How to read this

Work through the chapters in order. Each one:

• introduces one idea,
• uses focused excerpts and, where provided, links an explicitly maintained program under examples/src/,
• and ends with what you just learned.

flowchart LR
    A[00 What is JSON?] --> B[01 Getting started]
    B --> C[02 Creating JSON]
    C --> D[03 Parsing & reading]
    D --> E[04 Editing]
    E --> F[05 Parsing & errors]
    F --> G[06 Schema validation]
    G --> H[07 Capstone: address book]
    H --> I[08 Building & installing]
    I --> J[09 Testing]
    J --> K[10 Contributing]
    K --> L[11 Streaming large files]
    L --> M[12 Custom allocators]

Loading

Chapters

#	Chapter	You will learn
00	What is JSON?	The data model, from zero
01	Getting started	Include pjson and print your first value
02	Creating JSON	Build objects, arrays, and nested data
03	Parsing & reading	Turn text into data and read it back safely
04	Editing	Change, add, and remove parts of a document
05	Parsing, limits & errors	Control budgets, duplicates, and diagnostics
06	Schema validation	Check that data has the shape you expect
07	Capstone: address book	Put it all together
08	Building & installing	Canonical sources, CMake, packages, build.sh
09	Testing	Run and understand the test suite
10	Contributing	Style, sanitizers, and sending changes
11	Streaming large JSON	Process huge inputs and write incrementally
12	Custom allocators	Control persistent DOM allocation and ownership

Reference and migration

• pjson 2.0 behavioral and ABI contract — current ownership, parsing, numeric, mutation, error, allocator, thread-safety, and binary-compatibility guarantees
• Browsable API reference — generated per-symbol documentation (its source page is kept in this repository).
• Migrating from nlohmann/json — translate DOM ownership, lookup, parsing, serialization, streaming, and validation.
• Migrating from RapidJSON — replace allocator-bound DOM and Reader/Writer idioms with pjson equivalents.

Build and validate the browsable reference with Doxygen and Python 3:

cmake -S . -B out/build-docs \
  -DPJSON_BUILD_TESTS=OFF \
  -DPJSON_BUILD_EXAMPLES=OFF \
  -DPJSON_BUILD_BENCHMARKS=OFF \
  -DPJSON_BUILD_DOCS=ON
cmake --build out/build-docs --target pjson-docs-check

Then open out/build-docs/docs/reference/html/index.html. Documentation warnings and missing public API families fail the build.

Contributing and project policies

• Contributor guide and detailed workflow
• Security policy and private vulnerability reporting
• Versioning and compatibility policy
• Release process and changelog
• Licensing and SPDX policy

The one-minute taste

#include "pjson.h"
#include "pjson_parser.h"
#include <cstdint>
#include <iostream>
using namespace ByteDance;

int main() {
    pjson person;
    person["name"] = "Ada";
    person["age"]  = int64_t(36);
    person["languages"] += "C++";
    person["languages"] += "Ada";

    pjson::SerializeOptions pretty = pjson::SerializeOptions::prettyPrinted();
    std::cout << person.toString(pretty) << "\n";

    pJsonParser::Error error;
    pjson parsed = pJsonParser().parse(person.toString(pretty), error);
    std::string name;
    if (error.ok && parsed.tryGet("name", name))
        std::cout << name << "\n"; // Ada
}

Ready? Start with Chapter 00 — What is JSON?, or jump to the canonical runnable Hello, World tutorial.