Skip to content


Defined in header <json.hpp>

    template<typename U, typename V, typename... Args> class ObjectType = std::map,
    template<typename U, typename... Args> class ArrayType = std::vector,
    class StringType = std::string,
    class BooleanType = bool,
    class NumberIntegerType = std::int64_t,
    class NumberUnsignedType = std::uint64_t,
    class NumberFloatType = double,
    template<typename U> class AllocatorType = std::allocator,
    template<typename T, typename SFINAE = void> class JSONSerializer = adl_serializer,
    class BinaryType = std::vector<std::uint8_t>
class basic_json;


  • json - default specialization
  • ordered_json - specialization that maintains the insertion order of object keys

Template parameters

Template parameter Description Derived type
ObjectType type for JSON objects object_t
ArrayType type for JSON arrays array_t
StringType type for JSON strings and object keys string_t
BooleanType type for JSON booleans boolean_t
NumberIntegerType type for JSON integer numbers number_integer_t
NumberUnsignedType type for JSON unsigned integer numbers number_unsigned_t
NumberFloatType type for JSON floating-point numbers number_float_t
AllocatorType type of the allocator to use
JSONSerializer the serializer to resolve internal calls to to_json() and from_json() json_serializer
BinaryType type for binary arrays binary_t

Iterator invalidation


Member types


  • exception - general exception of the basic_json class
    • parse_error - exception indicating a parse error
    • invalid_iterator - exception indicating errors with iterators
    • type_error - exception indicating executing a member function with a wrong type
    • out_of_range - exception indicating access out of the defined range
    • other_error - exception indicating other library errors

Container types

Type Definition
value_type basic_json
reference value_type&
const_reference const value_type&
difference_type std::ptrdiff_t
size_type std::size_t
allocator_type AllocatorType<basic_json>
pointer std::allocator_traits<allocator_type>::pointer
const_pointer std::allocator_traits<allocator_type>::const_pointer
iterator LegacyBidirectionalIterator
const_iterator constant LegacyBidirectionalIterator
reverse_iterator reverse iterator, derived from iterator
const_reverse_iterator reverse iterator, derived from const_iterator
iteration_proxy helper type for items function

JSON value data types

Parser callback

Member functions

Object inspection

Functions to inspect the type of a JSON value.

Value access

Direct access to the stored value of a JSON value.

Element access

Access to the JSON value

  • at - access specified element with bounds checking
  • operator[] - access specified element
  • value - access specified object element with default value
  • front - access the first element
  • back - access the last element


  • find - find an element in a JSON object
  • count - returns the number of occurrences of a key in a JSON object
  • contains - check the existence of an element in a JSON object


  • begin - returns an iterator to the first element
  • cbegin - returns a const iterator to the first element
  • end - returns an iterator to one past the last element
  • cend - returns a const iterator to one past the last element
  • rbegin - returns an iterator to the reverse-beginning
  • rend - returns an iterator to the reverse-end
  • crbegin - returns a const iterator to the reverse-beginning
  • crend - returns a const iterator to the reverse-end
  • items - wrapper to access iterator member functions in range-based for


  • empty - checks whether the container is empty
  • size - returns the number of elements
  • max_size - returns the maximum possible number of elements


  • clear - clears the contents
  • push_back - add a value to an array/object
  • operator+= - add a value to an array/object
  • emplace_back - add a value to an array
  • emplace - add a value to an object if key does not exist
  • erase - remove elements
  • insert - inserts elements
  • update - updates a JSON object from another object, overwriting existing keys
  • swap - exchanges the values

Lexicographical comparison operators

Serialization / Dumping

  • dump - serialization
  • to_string - user-defined to_string function for JSON values

Deserialization / Parsing

  • parse (static) - deserialize from a compatible input
  • accept (static) - check if the input is valid JSON
  • sax_parse (static) - generate SAX events

JSON Pointer functions

  • flatten - return flattened JSON value
  • unflatten - unflatten a previously flattened JSON value

JSON Patch functions

  • patch - applies a JSON patch
  • diff (static) - creates a diff as a JSON patch

JSON Merge Patch functions

Static functions

  • meta - returns version information on the library
  • get_allocator - returns the allocator associated with the container

Binary formats

  • from_bson (static) - create a JSON value from an input in BSON format
  • from_cbor (static) - create a JSON value from an input in CBOR format
  • from_msgpack (static) - create a JSON value from an input in MessagePack format
  • from_ubjson (static) - create a JSON value from an input in UBJSON format
  • to_bson (static) - create a BSON serialization of a given JSON value
  • to_cbor (static) - create a CBOR serialization of a given JSON value
  • to_msgpack (static) - create a MessagePack serialization of a given JSON value
  • to_ubjson (static) - create a UBJSON serialization of a given JSON value

Non-member functions

  • operator<<(std::ostream&) - serialize to stream
  • operator>>(std::istream&) - deserialize from stream


Helper classes

  • std::hash<nlohmann::json>
  • std::less<nlohmann::value_t>
  • std::swap<nlohmann::json>