json/api/macros/json_brace_init_copy_semantics.md

JSON_BRACE_INIT_COPY_SEMANTICS

#define JSON_BRACE_INIT_COPY_SEMANTICS /* value */

When defined to 1, single-element brace initialization of a basic_json value is treated as a copy/move of the element rather than wrapping it in a single-element array.

Default definition

The default value is 0 (disabled — existing behavior is preserved).

#define JSON_BRACE_INIT_COPY_SEMANTICS 0

Notes

!!! note "Background"

C++ always prefers the `initializer_list` constructor over the copy/move constructor for brace initialization. This
means that code like

```cpp
json obj = {{"key", "value"}};
json j{obj};
```

creates a single-element **array** `[{"key":"value"}]` instead of a copy of `obj`. This behavior is
compiler-dependent for older compilers (GCC wrapped, Clang did not), but starting from Clang 20, both compilers
behave the same way.

Enabling this macro opts into copy/move semantics for this case
(see [#5074](https://github.com/nlohmann/json/issues/5074)).

!!! warning "Opt-in only"

This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.

!!! warning "Applies to every single-element list"

The macro does not only affect a single JSON value in braces. **Any** single-element braced list is treated as its
element, so it no longer creates a one-element array:

```cpp
json j1 = {1};       // 1, not [1]
json j2 = {"text"};  // "text", not ["text"]
json j3 = {{1, 2}};  // [1,2], not [[1,2]]
```

Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one
element, and a single `[string, value]` pair such as `{{"key", "value"}}`, which still creates an object, are not
affected. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes
`[5]`.

!!! note "ABI compatibility"

The value of this macro is encoded in the [namespace](../../features/namespace.md) (tag `_bics`), resulting in
distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program
without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.

!!! tip "Workaround without the macro"

To explicitly create a single-element array without enabling this macro, use `json::array()`:

```cpp
json j = json::array({obj});  // always creates [obj]
```

Examples

??? example "Default behavior (macro not defined)"

Without the macro, single-element brace initialization wraps the value in an array:

```cpp
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json obj = {{"key", "value"}};

    json j{obj};
    // j is [{"key":"value"}]  -- single-element array, NOT a copy of obj
}
```

??? example "Opt-in copy semantics (macro defined to 1)"

With the macro, single-element brace initialization copies/moves the value:

```cpp
#define JSON_BRACE_INIT_COPY_SEMANTICS 1
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json obj = {{"key", "value"}};

    json j{obj};
    // j is {"key":"value"}  -- copy of obj
}
```

See also

• FAQ: Brace initialization yields arrays
• basic_json(initializer_list_t) - the affected constructor

Version history

• Added in version 3.13.0.