Skip to content


// (1)
template<typename InputType>
static basic_json from_bson(InputType&& i,
                            const bool strict = true,
                            const bool allow_exceptions = true);
// (2)
template<typename IteratorType>
static basic_json from_bson(IteratorType first, IteratorType last,
                            const bool strict = true,
                            const bool allow_exceptions = true);

Deserializes a given input to a JSON value using the BSON (Binary JSON) serialization format.

  1. Reads from a compatible input.
  2. Reads from an iterator range.

Template parameters


A compatible input, for instance:

  • an std::istream object
  • a FILE pointer
  • a C-style array of characters
  • a pointer to a null-terminated string of single byte characters
  • an object obj for which begin(obj) and end(obj) produces a valid pair of iterators.
a compatible iterator type


i (in)
an input in BSON format convertible to an input adapter
first (in)
iterator to start of the input
last (in)
iterator to end of the input
strict (in)
whether to expect the input to be consumed until EOF (true by default)
allow_exceptions (in)
whether to throw exceptions in case of a parse error (optional, true by default)

Return value

deserialized JSON value; in case of a parse error and allow_exceptions set to false, the return value will be value_t::discarded. The latter can be checked with is_discarded.

Exception safety

Strong guarantee: if an exception is thrown, there are no changes in the JSON value.


Linear in the size of the input.



The example shows the deserialization of a byte vector in BSON format to a JSON value.

#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
    // create byte vector
    std::vector<uint8_t> v = {0x1b, 0x00, 0x00, 0x00, 0x08, 0x63, 0x6f, 0x6d,
                              0x70, 0x61, 0x63, 0x74, 0x00, 0x01, 0x10, 0x73,
                              0x63, 0x68, 0x65, 0x6d, 0x61, 0x00, 0x00, 0x00,
                              0x00, 0x00, 0x00

    // deserialize it with BSON
    json j = json::from_bson(v);

    // print the deserialized JSON value
    std::cout << std::setw(2) << j << std::endl;


  "compact": true,
  "schema": 0

Version history

  • Added in version 3.4.0.