# JSON Handling in Glaze

Glaze is one of the fastest JSON libraries in the world, offering automatic reflection and direct memory serialization/deserialization with incredible performance. Glaze makes JSON handling in C++ simple, fast, and type-safe. Start with basic automatic reflection and gradually adopt advanced features as your needs grow!

### Basic Example

With Glaze, your structs automatically get JSON serialization without any metadata:

```cpp
#include "glaze/glaze.hpp"

struct Person {
    std::string name = "John Doe";
    int age = 30;
    std::vector<std::string> hobbies = {"reading", "gaming"};
};

int main() {
    Person person{};
    
    // Write to JSON
    std::string buffer{};
    auto ec = glz::write_json(person, buffer);
    if (!ec) {
        // buffer now contains: {"name":"John Doe","age":30,"hobbies":["reading","gaming"]}
    }
    
    // Read from JSON
    std::string json_data = R"({"name":"Jane","age":25,"hobbies":["hiking","cooking"]})";
    Person jane{};
    ec = glz::read_json(jane, json_data);
    if (!ec) {
        // jane.name is now "Jane", jane.age is 25, etc.
    }
    
    return 0;
}
```

### Alternative API Styles

Glaze offers multiple ways to read and write JSON:

**Writing JSON:**
```cpp
Person person{};

// Primary method: Write into existing buffer
std::string buffer{};
auto ec = glz::write_json(person, buffer);
if (!ec) {
    // buffer contains the JSON string
}

// Alternative: Function returns std::expected<std::string, glz::error_ctx>
std::string json = glz::write_json(person).value_or("error");
```

**Reading JSON:**
```cpp
std::string json_data = R"({"name":"Alice","age":28})";

// Primary method: Read into existing object
Person person{};
auto ec = glz::read_json(person, json_data);
if (!ec) {
    // person is now populated from json_data
}

// Alternative: Function returns std::expected<T, glz::error_ctx>
auto result = glz::read_json<Person>(json_data);
if (result) {
    const Person& person = result.value();
}
```

**Partial Updates**: When reading into an existing object, `read_json` only updates fields present in the JSON—other fields retain their existing values. This makes `read_json` ideal for applying partial updates:

```cpp
Person person{.name = "Default", .age = 0, .hobbies = {}};
glz::read_json(person, R"({"age": 25})");
// person.name is still "Default", person.age is now 25
```

### File I/O

```cpp
Person person{};

// Read from file
auto ec = glz::read_file_json(person, "./person.json", std::string{});
if (!ec) {
    // person is now populated from the file
}

// Write to file  
auto ec = glz::write_file_json(person, "./person.json", std::string{});
if (!ec) {
    // person data has been written to the file
}
```

## Automatic Reflection

Glaze uses compile-time reflection to automatically serialize your structs. No macros, no manual registration - it just works!

**Supported out of the box:**
- All aggregate-initializable structs
- Standard library containers
- Primitive types
- Nested objects

```cpp
struct Address {
    std::string street;
    std::string city;
    int zip_code;
};

struct Employee {
    std::string name;
    int employee_id;
    Address address;
    std::optional<std::string> department;
    std::map<std::string, int> skills_rating;
};

// This struct automatically works with JSON - no additional code needed!
```

## Manual Metadata (When Needed)

For non-aggregate structs, private members, or custom behavior, you can provide explicit metadata:

```cpp
struct CustomStruct {
private:
    int value;
    std::string name;
    
    friend struct glz::meta<CustomStruct>; // friend only needed to access private members
    
public:
    CustomStruct(int v, const std::string& n) : value(v), name(n) {}
};

template <>
struct glz::meta<CustomStruct> {
    using T = CustomStruct;
    static constexpr auto value = glz::object(
        &T::value, // will use the key "value" automatically
        &T::name // will use the key "name" automatically
    );
};
```

### Custom Field Names

You can override the default field names:

```cpp
template <>
struct glz::meta<Person> {
    using T = Person;
    static constexpr auto value = glz::object(
        "full_name", &T::name,
        "years_old", &T::age,
        "interests", &T::hobbies
    );
};

// JSON output: {"full_name":"John","years_old":30,"interests":["reading"]}
```

### Function Pointers in Metadata

When a `glz::meta` definition references a function pointer (member or non-member), Glaze skips that entry during JSON writes by default. This prevents unintentionally emitting empty values for callables.

If you want the key to be emitted—you can opt back in by supplying a custom options type with `write_function_pointers = true`:

## Error Handling

Glaze provides comprehensive error handling with detailed error messages:

```cpp
std::string invalid_json = R"({"name":"John", "age":})"; // Missing value

Person person{};
auto ec = glz::read_json(person, invalid_json);
if (ec) {
    // Get a detailed error message
    std::string error_msg = glz::format_error(ec, invalid_json);
    std::cout << error_msg << '\n';
}
```

### Bytes Consumed (Read Operations)

The `error_ctx` returned by read operations includes a `count` field that tracks the byte position:

```cpp
std::string buffer = R"({"name":"Alice","age":30})";
Person person{};
auto ec = glz::read_json(person, buffer);
if (!ec) {
    // Success: ec.count contains bytes consumed
    size_t bytes_read = ec.count;

    // Useful for reading multiple values from one buffer:
    std::string_view remaining = std::string_view(buffer).substr(bytes_read);
}
```

On error, `count` indicates where the parse error occurred, which `format_error` uses to show the error position.

### Bytes Written (Write Operations)

Write operations return `error_ctx` with a `count` field. See [Writing](./writing.md) for details.

### Input Buffer Requirements

For optimal performance, use null-terminated buffers (like `std::string`):

```cpp
// Recommended - null terminated
std::string json_data = "...";
Person person{};
auto ec = glz::read_json(person, json_data);

// If you must use non-null terminated buffers
constexpr auto options = glz::opts{.null_terminated = false};
auto ec = glz::read<options>(person, buffer);
```

## Type Support

### Containers and Arrays

All standard C++ containers are supported, and if your containers match C++ standard APIs they will work as well:

```cpp
std::vector<int> numbers = {1, 2, 3, 4, 5};
std::array<std::string, 3> colors = {"red", "green", "blue"};
std::set<int> unique_numbers = {1, 2, 3};
std::deque<double> values = {1.1, 2.2, 3.3};

// All serialize to JSON arrays: [1,2,3,4,5], ["red","green","blue"], etc.
```

### Maps and Objects

```cpp
std::map<std::string, int> scores = {{"Alice", 95}, {"Bob", 87}};
std::unordered_map<std::string, std::string> config = {{"host", "localhost"}};

// Serialize to JSON objects: {"Alice":95,"Bob":87}
```

For non-string composite keys, Glaze can also serialize map-like containers as flat JSON arrays via the optional wrapper in `glaze/json/flatten_map.hpp`:

```cpp
#include "glaze/json/flatten_map.hpp"

struct pair_hash
{
   size_t operator()(const std::pair<int, int>& value) const noexcept
   {
      return std::hash<int>{}(value.first) ^ (std::hash<int>{}(value.second) << 1);
   }
};

using map_t = std::unordered_map<std::pair<int, int>, std::string, pair_hash>;

struct payload
{
   map_t map{};
};

template <>
struct glz::meta<payload>
{
   using T = payload;
   static constexpr auto value = glz::object("map", glz::flatten_map<&T::map>);
};

payload value{};
value.map[{1, 2}] = "example";
value.map[{3, 4}] = "another";

std::string json{};
glz::write_json(glz::flatten_map<&payload::map>(value), json);
// json == [1,2,"example",3,4,"another"] (ordering depends on the container)

payload parsed{};
auto wrapped = glz::flatten_map<&payload::map>(parsed);
glz::read_json(wrapped, json);
```

This format flattens each entry into the surrounding array as `[key elements..., mapped value]`. It is intended for map-like containers with fixed-size keys such as `std::pair`, tuples, Glaze arrays, and `std::array`.

### Optional and Nullable Types

```cpp
struct OptionalData {
    std::optional<std::string> nickname;
    std::unique_ptr<int> priority;
    std::shared_ptr<std::vector<int>> tags;
};

// null values are written as JSON null, valid values are serialized normally
```

### Enums

Enums can be serialized as integers (default) or strings:

```cpp
enum class Status { Active, Inactive, Pending };

// Default: serialize as integers (0, 1, 2)
Status status = Status::Active;

// For string serialization, add metadata:
template <>
struct glz::meta<Status> {
    using enum Status;
    static constexpr auto value = glz::enumerate(
        Active,
        Inactive,
        Pending
    );
};
// Now serializes as: "Active", "Inactive", "Pending"
```

> [!TIP]
>
> For automatic enum-to-string serialization without writing metadata for each enum, see [Automatic Enum Strings](enum-reflection.md).

### Variants

```cpp
std::variant<int, std::string, double> data = "hello";
// Glaze automatically handles variant serialization
```

## Advanced Features

### JSON with Comments (JSONC)

Read JSON files with comments:

```cpp
std::string jsonc_data = R"({
    "name": "John", // Person's name
    /* Multi-line comment
       about age */
    "age": 30
})";

Person person{};
auto ec = glz::read_jsonc(person, jsonc_data);
// Or: glz::read<glz::opts{.comments = true}>(person, jsonc_data);
```

### Pretty Printing

```cpp
Person person{};

// Write prettified JSON directly
std::string buffer{};
auto ec = glz::write<glz::opts{.prettify = true}>(person, buffer);

// Or prettify existing JSON
std::string minified = R"({"name":"John","age":30})";
std::string pretty = glz::prettify_json(minified);
```

Output:
```json
{
   "name": "John",
   "age": 30
}
```

### Minification

```cpp
// Write minified JSON (default behavior)
Person person{};
std::string buffer{};
auto ec = glz::write_json(person, buffer); // Already minified by default

// Minify existing JSON text
std::string pretty_json = "..."; // JSON with whitespace
std::string minified = glz::minify_json(pretty_json);

// For reading minified JSON (performance optimization)
auto ec = glz::read<glz::opts{.minified = true}>(person, minified_buffer);
```

### Custom Serialization

For complex custom behavior, use `glz::custom`:

```cpp
struct TimestampObject {
    std::chrono::system_clock::time_point timestamp;
    
    void read_timestamp(const std::string& iso_string) {
        // Parse ISO 8601 string to time_point
    }
    
    std::string write_timestamp() const {
        // Convert time_point to ISO 8601 string
    }
};

template <>
struct glz::meta<TimestampObject> {
    using T = TimestampObject;
    static constexpr auto value = glz::object(
        "timestamp", glz::custom<&T::read_timestamp, &T::write_timestamp>
    );
};
```

### Boolean Flags

Represent multiple boolean flags as a JSON array:

```cpp
struct Permissions {
    bool read = true;
    bool write = false;
    bool execute = true;
};

template <>
struct glz::meta<Permissions> {
    using T = Permissions;
    static constexpr auto value = glz::flags(
        "read", &T::read,
        "write", &T::write,
        "execute", &T::execute
    );
};

// JSON output: ["read", "execute"]
```

### Dynamic JSON Objects with glz::obj

`glz::obj` is a compile-time, stack-allocated JSON object builder that allows you to create JSON objects on the fly without defining structs. It's perfect for logging, custom serialization, temporary data structures, and rapid prototyping.

#### Basic Usage

```cpp
// Create a JSON object with key-value pairs
auto obj = glz::obj{"name", "Alice", "age", 30, "active", true};

std::string buffer{};
auto ec = glz::write_json(obj, buffer);
// Results in: {"name":"Alice","age":30,"active":true}
```

#### Key Features

- **Stack-allocated**: No dynamic memory allocation for better performance
- **Type-safe**: Compile-time type checking
- **Heterogeneous types**: Mix different value types in the same object
- **Reference semantics**: Can store references to existing variables
- **Nested support**: Can contain other `glz::obj` or `glz::arr` instances

#### Advanced Examples

```cpp
// Nested objects and arrays
auto nested = glz::obj{
    "user", glz::obj{"id", 123, "name", "Bob"},
    "scores", glz::arr{95, 87, 92},
    "metadata", glz::obj{"version", "1.0", "timestamp", 1234567890}
};

// Storing references to existing variables
std::string name = "Charlie";
int score = 100;
auto ref_obj = glz::obj{"player", name, "score", score};
// Changes to 'name' or 'score' will be reflected when serializing ref_obj

// Mixed types in one object
std::vector<int> vec = {1, 2, 3};
std::map<std::string, double> map = {{"pi", 3.14}, {"e", 2.71}};
auto mixed = glz::obj{
    "numbers", vec,
    "constants", map,
    "flag", true,
    "message", "Hello"
};
```

#### glz::obj_copy

When you need value semantics instead of reference semantics, use `glz::obj_copy`:

```cpp
int x = 5;
auto obj_ref = glz::obj{"x", x};  // Stores reference to x
auto obj_val = glz::obj_copy{"x", x};  // Copies the value of x

x = 10;
// obj_ref will serialize as {"x":10}
// obj_val will serialize as {"x":5}
```

### Dynamic JSON Arrays with glz::arr

Similar to `glz::obj`, `glz::arr` creates stack-allocated JSON arrays:

```cpp
// Basic array
auto arr = glz::arr{1, 2, 3, 4, 5};

// Mixed types
auto mixed_arr = glz::arr{"Hello", 42, true, 3.14};

// Nested structures
auto nested_arr = glz::arr{
    glz::obj{"id", 1, "name", "Item1"},
    glz::obj{"id", 2, "name", "Item2"},
    glz::arr{1, 2, 3}
};

std::string buffer{};
auto ec = glz::write_json(nested_arr, buffer);
// Results in: [{"id":1,"name":"Item1"},{"id":2,"name":"Item2"},[1,2,3]]
```

#### glz::arr_copy

Just like `glz::obj_copy`, use `glz::arr_copy` for value semantics:

```cpp
std::string s = "original";
auto arr_ref = glz::arr{s};  // Reference to s
auto arr_val = glz::arr_copy{s};  // Copy of s
```

### Object Merging

`glz::merge` allows you to combine multiple JSON objects into a single object. This is useful for composing objects from different sources:

```cpp
// Merge glz::obj instances
glz::obj metadata{"version", "1.0", "author", "John"};
glz::obj settings{"debug", true, "timeout", 5000};
auto merged1 = glz::merge{metadata, settings};
// Results in: {"version":"1.0","author":"John","debug":true,"timeout":5000}

// Merge different object types
std::map<std::string, int> scores = {{"test1", 95}, {"test2", 87}};
auto user_data = glz::obj{"user_id", 42, "username", "alice"};
auto merged2 = glz::merge{user_data, scores};
// Results in: {"user_id":42,"username":"alice","test1":95,"test2":87}

// Merge with raw_json
glz::raw_json raw{R"({"extra":"data"})"};
auto merged3 = glz::merge{metadata, raw};
// Results in: {"version":"1.0","author":"John","extra":"data"}
```

#### Key Collision Behavior

When merging objects with duplicate keys, the last value wins:

```cpp
auto obj1 = glz::obj{"key", "first"};
auto obj2 = glz::obj{"key", "second"};
auto merged = glz::merge{obj1, obj2};
// Results in: {"key":"second"}
```

### Struct Flattening with Merge

`glz::merge` can also be used inside `glz::meta` to flatten multiple sub-structs into a single JSON object. This is useful when you compose a type from reusable components but want a flat JSON representation for both **reading and writing**.

```cpp
struct Species {
   std::string name{};
   int legs{};
};

struct Appearance {
   double weight{};
   std::string color{};
};

struct BearRecord {
   Species species{};
   Appearance appearance{};
};

template <>
struct glz::meta<BearRecord> {
   using T = BearRecord;
   static constexpr auto value = glz::merge{&T::species, &T::appearance};
};
```

`BearRecord` now reads and writes as a single flat object:

```json
{"name":"Grizzly","legs":4,"weight":300.5,"color":"brown"}
```

Without `glz::merge`, the default serialization would nest each sub-struct:

```json
{"species":{"name":"Grizzly","legs":4},"appearance":{"weight":300.5,"color":"brown"}}
```

#### Merging N Structs

Any number of sub-structs can be merged:

```cpp
struct Habitat {
   std::string biome{};
   bool endangered{};
};

struct BearProfile {
   Species species{};
   Appearance appearance{};
   Habitat habitat{};
};

template <>
struct glz::meta<BearProfile> {
   using T = BearProfile;
   static constexpr auto value = glz::merge{&T::species, &T::appearance, &T::habitat};
};
// All fields flattened into one JSON object
```

#### Sub-Structs with Custom Keys

Sub-structs that define their own `glz::meta` will use their custom key names in the merged output:

```cpp
struct Dimensions {
   double height{};
   double width{};
};

template <>
struct glz::meta<Dimensions> {
   using T = Dimensions;
   static constexpr auto value = glz::object("h", &T::height, "w", &T::width);
};

struct MeasuredBear {
   Species species{};
   Dimensions dims{};
};

template <>
struct glz::meta<MeasuredBear> {
   using T = MeasuredBear;
   static constexpr auto value = glz::merge{&T::species, &T::dims};
};
// Produces: {"name":"Sun","legs":4,"h":1.5,"w":0.8}
```

#### Format Support

Struct flattening via `glz::merge` works across all Glaze formats (JSON, BEVE, YAML, CBOR, etc.) because it integrates at the reflection layer.

### Performance Considerations

- **Stack allocation**: Both `glz::obj` and `glz::arr` are stack-allocated, avoiding heap allocations
- **Compile-time optimization**: The structure is known at compile time, enabling optimizations
- **Zero-copy references**: When storing references, no data copying occurs
- **Efficient serialization**: Direct memory access without intermediate representations

### Use Cases

1. **Logging and Debugging**:
```cpp
auto log_entry = glz::obj{
    "timestamp", std::time(nullptr),
    "level", "INFO",
    "message", "User logged in",
    "user_id", user.id
};
glz::write_json(log_entry, log_buffer);
```

2. **API Responses**:
```cpp
auto response = glz::obj{
    "status", 200,
    "data", glz::arr{item1, item2, item3},
    "metadata", glz::obj{"page", 1, "total", 100}
};
```

3. **Configuration Objects**:
```cpp
auto config = glz::obj{
    "database", glz::obj{"host", "localhost", "port", 5432},
    "cache", glz::obj{"enabled", true, "ttl", 3600}
};
```

## Performance Features

### Direct Memory Access

Glaze reads and writes directly to/from object memory, avoiding intermediate representations:

```cpp
// No DOM tree, no temporary objects - direct serialization
LargeObject large_object{};
std::string buffer{};
auto ec = glz::write_json(large_object, buffer);
```

### Compile-Time Optimizations

- Perfect hash tables for object keys
- Compile-time reflection eliminates runtime overhead
- SIMD and SWAR optimizations where possible

## JSON Conformance

Glaze is RFC 8259 compliant. UTF-8 encoding is validated when reading unless you opt out with `validate_utf8 = false`. Two further checks are off by default for performance:

- `validate_skipped = false`: Faster parsing by not fully validating skipped values (does not affect resulting C++ objects)
- `validate_trailing_whitespace = false`: Stops parsing after the target object

For strict compliance, enable these options:

```cpp
struct strict_opts : glz::opts {
    bool validate_skipped = true;
    bool validate_trailing_whitespace = true;
};

auto ec = glz::read<strict_opts{}>(obj, json_data);
```

`glz::validate_json` and `glz::validate_jsonc` enable both, so a document that passes them is fully RFC 8259 conformant.

### UTF-8 Validation

RFC 8259 section 8.1 requires JSON text to be encoded in UTF-8, and Glaze enforces it on read. It is on by default because read input is by definition someone else's data, and accepting malformed encodings silently propagates them into your program. See [Disabling validation](#disabling-validation) below for the option that turns it off.

```cpp
std::vector<std::string> v{};
auto ec = glz::read_json(v, "[\"a\xFF\"]"); // ec == glz::error_code::invalid_utf8
```

This rejects lone continuation bytes, overlong encodings, truncated sequences, encoded UTF-16 surrogate halves, and code points above U+10FFFF. Escape sequences are validated separately, so `"\ud800"` without a matching low surrogate is rejected as well.

Validation applies to every string the reader materializes, including map keys, keys that match no member, values you do not model, and values reached through `glz::skip` or `glz::raw_json`. A malformed byte in a field you never look at still fails the parse. This is the change most likely to affect existing code: input that previously parsed will now return an error.

The one string not checked is an object key that matches a member name in your `glz::meta` or reflected struct. Matching compares the input bytes against the program's own literal, so a match proves the key is whatever you wrote in your C++ source, and no separate pass can tell you anything new. Keys read into a `std::map` or `glz::generic` are materialized and so are checked.

Validation uses the Lemire & Keiser vector algorithm, with backends for AVX-512BW, AVX2, SSSE3, AArch64 NEON, and WebAssembly SIMD128. Targets without a byte-granular shuffle fall back to a scalar validator. Reading a string value skips validation entirely when the string is pure ASCII, because the scan that finds its closing quote already proves no byte has the high bit set. Object keys and skipped strings are located with `memchr`, which proves nothing about the bytes it passed over, so those always run a full pass.

Cost therefore tracks how much of a document is non-ASCII. Measured on `twitter.json` (22% non-ASCII, string heavy), reading costs roughly 5% into structs and 6% into `glz::generic`. A pure ASCII document is within noise of unvalidated parsing when read into structs, and costs about 3% when read into `glz::generic`.

Writing is **not** validated. Data you serialize is your own, so Glaze does not pay to re-check it; validate before writing if you have a specific reason to. Note that this makes round-tripping asymmetric: a `std::string` holding non-UTF-8 bytes will write successfully and then fail to read back.

JSONC comments are skipped without validation, since comments are not part of RFC 8259 and their bytes never reach your program.

#### Disabling validation

The inheritable `validate_utf8` option turns the check off, which restores the pre-validation behavior and its performance:

```cpp
struct unchecked_opts : glz::opts {
   bool validate_utf8 = false;
};

std::vector<std::string> v{};
auto ec = glz::read<unchecked_opts{}>(v, "[\"a\xFF\"]"); // no error; v[0] holds the raw bytes
```

Disabling it makes the parse non-conformant, so reach for it only when the encoding is already guaranteed by an earlier stage, or when the bytes are deliberately not UTF-8 and you accept that the resulting `std::string` may hold anything. The option is a compile-time setting like every other Glaze option, so it inherits into custom option structs and applies to nested values, keys, and skipped fields alike. It also governs `lazy_json_view::get<std::string>()`. Everything else still applies: unpaired `\uXXXX` surrogate escapes, raw control characters, and unterminated strings are rejected regardless.

## See Also

- [Writing](./writing.md) - Understanding `error_ctx` and buffer handling
- [Lazy JSON](./lazy-json.md) - On-demand parsing for selective field access
- [Generic JSON](./generic-json.md) - Working with `glz::generic` for dynamic JSON
- [JSON Patch (RFC 6902)](./json-patch.md) - Apply structured patches to JSON documents
- [JSON Merge Patch (RFC 7386)](./json-merge-patch.md) - Apply partial updates to JSON documents
- [JSON Schema](./json-schema.md) - Generate JSON Schema from C++ types
- [JSON Pointer Syntax](./json-pointer-syntax.md) - Path syntax for navigating JSON documents
