json/docs/mkdocs/docs/integration/migration_guide.md

Migration Guide

This page collects some guidelines on how to future-proof your code for future versions of this library. For how to add the library to your project in the first place, see Integration, CMake, or Package Managers. The roadmap lists what will change in version 4.0, including the macros that let you try its behavior with a 3.x release; this page describes how to adjust your code.

Replace deprecated functions

The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0), see the roadmap for an overview. All deprecations are annotated with HEDLEY_DEPRECATED_FOR to report which function to use instead.

!!! tip "Find all calls of deprecated functions"

Define [`JSON_DELETE_DEPRECATED_FUNCTIONS`](../api/macros/json_delete_deprecated_functions.md) to `1` (or set the
CMake option [`JSON_DeleteDeprecatedFunctions`](cmake.md#json_deletedeprecatedfunctions)) to delete all deprecated
functions. Every remaining call then fails to compile, even if deprecation warnings are disabled, so your code is
ready for version 4.0.0 once it compiles with the macro.

Parsing

• Function friend std::istream& operator<<(basic_json&, std::istream&) is deprecated since 3.0.0. Please use friend std::istream& operator>>(std::istream&, basic_json&) instead.

  === "Deprecated"

    ```cpp
    nlohmann::json j;
    std::stringstream ss("[1,2,3]");
    j << ss;
    ```
  

  === "Future-proof"

    ```cpp
    nlohmann::json j;
    std::stringstream ss("[1,2,3]");
    ss >> j;
    ```
  

• Passing iterator pairs or pointer/length pairs to parsing functions (parse, accept, sax_parse, from_cbor, from_msgpack, from_ubjson, and from_bson) via initializer lists is deprecated since 3.8.0. Instead, pass two iterators; for instance, call from_cbor(ptr, ptr+len) instead of from_cbor({ptr, len}). Likewise, passing a pointer and a length as two separate arguments to from_cbor, from_msgpack, from_ubjson, and from_bson is deprecated since 3.8.0, and to from_bjdata and from_bon8 since 3.13.0; call from_cbor(ptr, ptr+len) instead of from_cbor(ptr, len). These overloads will not be removed in version 4.0.0, but deleted, so a call like from_cbor(ptr, len) cannot compile and convert len to the strict parameter.

  === "Deprecated"

      ```cpp
      const char* s = "[1,2,3]";
      bool ok = nlohmann::json::accept({s, s + std::strlen(s)});
      ```
  

  === "Future-proof"

      ```cpp
      const char* s = "[1,2,3]";
      bool ok = nlohmann::json::accept(s, s + std::strlen(s));
      ```
  

JSON Pointers

• Comparing JSON Pointers with strings via operator== and operator!= is deprecated since 3.11.2. To compare a json_pointer p with a string s, convert s to a json_pointer first and use json_pointer::operator== or json_pointer::operator!=.

  === "Deprecated"

    ```cpp
    nlohmann::json::json_pointer lhs("/foo/bar/1");
    assert(lhs == "/foo/bar/1");
    ```
  

  === "Future-proof"

    ```cpp
    nlohmann::json::json_pointer lhs("/foo/bar/1");
    assert(lhs == nlohmann::json::json_pointer("/foo/bar/1"));
    ```
  

• The implicit conversion from JSON Pointers to string (json_pointer::operator string_t) is deprecated since 3.11.0. Use json_pointer::to_string instead.

  === "Deprecated"

      ```cpp
      nlohmann::json::json_pointer ptr("/foo/bar/1");
      std::string s = ptr;
      ```
  

  === "Future-proof"

      ```cpp
      nlohmann::json::json_pointer ptr("/foo/bar/1");
      std::string s = ptr.to_string();
      ```
  

• Passing a basic_json specialization as template parameter RefStringType to json_pointer is deprecated since 3.11.0. The string type can now be directly provided. This also applies to passing such a JSON pointer to at, contains, operator[], and value.

  === "Deprecated"

      ```cpp
      using my_json = nlohmann::json::with_string_t<my_string_type>;
      nlohmann::json_pointer<my_json> ptr("/foo/bar/1");
      ```
  

  === "Future-proof"

      ```cpp
      nlohmann::json_pointer<my_string_type> ptr("/foo/bar/1");
      ```
  

  Thereby, my_json::json_pointer is an alias for nlohmann::json_pointer<my_string_type>; in general, basic_json::json_pointer is always an alias to the json_pointer with the appropriate string type for all specializations of basic_json.

Miscellaneous functions

• The function iterator_wrapper is deprecated since 3.1.0. Please use the member function items instead.

  === "Deprecated"

      ```cpp
      for (auto &x : nlohmann::json::iterator_wrapper(j))
      {
          std::cout << x.key() << ":" << x.value() << std::endl;
      }
      ```
  

  === "Future-proof"

      ```cpp
      for (auto &x : j.items())
      {
          std::cout << x.key() << ":" << x.value() << std::endl;
      }
      ```
  

• Function friend std::ostream& operator>>(const basic_json&, std::ostream&) is deprecated since 3.0.0. Please use friend operator<<(std::ostream&, const basic_json&) instead.

  === "Deprecated"

      ```cpp
      j >> std::cout;
      ```
  

  === "Future-proof"

      ```cpp
      std::cout << j;
      ```
  

• The legacy comparison behavior for discarded values is deprecated since 3.11.0. It is already disabled by default and can still be enabled by defining JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON to 1.

  === "Deprecated"

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

  === "Future-proof"

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

Replace implicit conversions

Implicit conversions via operator ValueType will be switched off by default in the next major release of the library.

You can prepare existing code by already defining JSON_USE_IMPLICIT_CONVERSIONS to 0 and replace any implicit conversions with calls to get, get_to, get_ref, or get_ptr.

!!! tip "Automatic migration"

The community-maintained clang-tidy check `modernize-nlohmann-json-explicit-conversions` rewrites most implicit
conversions into calls to [`get`](../api/basic_json/get.md). It is not part of clang-tidy itself; see
[discussion #4610](https://github.com/nlohmann/json/discussions/4610) for how to build and use it.

=== "Deprecated"

  ```cpp
  nlohmann::json j = "Hello, world!";
  std::string s = j;
  ```

=== "Future-proof"

  ```cpp
  nlohmann::json j = "Hello, world!";
  auto s = j.get<std::string>();
  ```

=== "Future-proof (alternative)"

  ```cpp
  nlohmann::json j = "Hello, world!";
  std::string s;
  j.get_to(s);
  ```

Import namespace literals for UDLs

The user-defined string literals operator""_json and operator""_json_pointer will be removed from the global namespace in the next major release of the library.

=== "Deprecated"

  ```cpp
  nlohmann::json j = "[1,2,3]"_json;
  ```

=== "Future-proof"

  ```cpp
  using namespace nlohmann::literals;
  nlohmann::json j = "[1,2,3]"_json;
  ```

To prepare existing code, define JSON_USE_GLOBAL_UDLS to 0 and bring the string literals into scope where needed.

Do not hard-code the complete library namespace

The nlohmann namespace contains a sub-namespace to avoid problems when different versions or configurations of the library are used in the same project. Always use nlohmann as namespace or, when the exact version and configuration is relevant, use macro NLOHMANN_JSON_NAMESPACE to denote the namespace.

=== "Dangerous"

  ```cpp
  void to_json(nlohmann::json_abi_v3_11_2::json& j, const person& p)
  {
      j["age"] = p.age;
  }
  ```

=== "Future-proof"

  ```cpp
  void to_json(nlohmann::json& j, const person& p)
  {
      j["age"] = p.age;
  }
  ```

=== "Future-proof (alternative)"

  ```cpp
  void to_json(NLOHMANN_JSON_NAMESPACE::json& j, const person& p)
  {
      j["age"] = p.age;
  }
  ```

Do not use the detail namespace

The nlohmann::detail namespace is not part of the public API of the library and can change in any version without an announcement. Do not rely on any function or type in the detail namespace.

See also

• JSON_DELETE_DEPRECATED_FUNCTIONS - remove deprecated functions to check the migration
• JSON_USE_IMPLICIT_CONVERSIONS - control implicit conversions
• NLOHMANN_JSON_NAMESPACE - refer to the library namespace without hard-coding it
• nlohmann Namespace - how the library namespace is structured
• Converting values - explicit conversions with get
• basic_json - the main class and all its member functions