https://www.boost.org/doc/libs/release/libs/json/[image:https://raw.githubusercontent.com/CPPAlliance/json/master/doc/images/repo-logo-3.png[Boost.JSON]]

[width="100%",cols="12%,43%,45%",options="header",]
|===
|Branch |https://github.com/boostorg/json/tree/master[`master`]
|https://github.com/boostorg/json/tree/develop[`develop`]
|https://azure.microsoft.com/en-us/services/devops/pipelines/[Azure]
|https://vinniefalco.visualstudio.com/json/_build/latest?definitionId=5&branchName=master[image:https://img.shields.io/azure-devops/build/vinniefalco/2571d415-8cc8-4120-a762-c03a8eda0659/8/master[Build
Status]]
|https://vinniefalco.visualstudio.com/json/_build/latest?definitionId=8&branchName=develop[image:https://img.shields.io/azure-devops/build/vinniefalco/2571d415-8cc8-4120-a762-c03a8eda0659/8/develop[Build
Status]]

|Docs
|https://www.boost.org/doc/libs/master/libs/json/[image:https://img.shields.io/badge/docs-master-brightgreen.svg[Documentation]]
|https://www.boost.org/doc/libs/develop/libs/json/[image:https://img.shields.io/badge/docs-develop-brightgreen.svg[Documentation]]

|https://drone.io/[Drone]
|https://drone.cpp.al/boostorg/json[image:https://drone.cpp.al/api/badges/boostorg/json/status.svg?ref=refs/heads/master[Build
Status]]
|https://drone.cpp.al/boostorg/json[image:https://drone.cpp.al/api/badges/boostorg/json/status.svg?ref=refs/heads/develop[Build
Status]]

|Matrix
|http://www.boost.org/development/tests/master/developer/json.html[image:https://img.shields.io/badge/matrix-master-brightgreen.svg[Matrix]]
|http://www.boost.org/development/tests/develop/developer/json.html[image:https://img.shields.io/badge/matrix-develop-brightgreen.svg[Matrix]]

|Fuzzing |—
|https://github.com/boostorg/json/actions?query=workflow%3Afuzz+branch%3Adevelop[image:https://github.com/boostorg/json/workflows/fuzz/badge.svg?branch=develop[fuzz]]

|https://ci.appveyor.com/[Appveyor]
|https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/master[image:https://ci.appveyor.com/api/projects/status/8csswcnmfm798203?branch=master&svg=true[Build
status]]
|https://ci.appveyor.com/project/vinniefalco/cppalliance-json/branch/develop[image:https://ci.appveyor.com/api/projects/status/8csswcnmfm798203?branch=develop&svg=true[Build
status]]

|https://codecov.io[codecov.io]
|https://codecov.io/gh/boostorg/json/branch/master[image:https://codecov.io/gh/boostorg/json/branch/master/graph/badge.svg[codecov]]
|https://codecov.io/gh/boostorg/json/branch/develop[image:https://codecov.io/gh/boostorg/json/branch/develop/graph/badge.svg[codecov]]
|===

== Boost.JSON

=== Overview

Boost.JSON is a portable C++ library which provides containers and
algorithms that implement https://json.org/[JavaScript Object Notation],
or simply ``JSON'', a lightweight data-interchange format. This format
is easy for humans to read and write, and easy for machines to parse and
generate. It is based on a subset of the JavaScript Programming Language
(https://www.ecma-international.org/ecma-262/10.0/index.html[Standard
ECMA-262]), and is currently standardised in
https://datatracker.ietf.org/doc/html/rfc8259[RFC 8259]. JSON is a text
format that is language-independent but uses conventions that are
familiar to programmers of the C-family of languages, including C, C++,
C#, Java, JavaScript, Perl, Python, and many others. These properties
make JSON an ideal data-interchange language.

This library focuses on a common and popular use-case: parsing and
serializing to and from a container called `value` which holds JSON
types. Any `value` which you build can be serialized and then
deserialized, guaranteeing that the result will be equal to the original
value. Whatever JSON output you produce with this library will be
readable by most common JSON implementations in any language.

The `value` container is designed to be well suited as a vocabulary type
appropriate for use in public interfaces and libraries, allowing them to
be composed. The library restricts the representable data types to the
ranges which are almost universally accepted by most JSON
implementations, especially JavaScript. The parser and serializer are
both highly performant, meeting or exceeding the benchmark performance
of the best comparable libraries. Allocators are very well supported.
Code which uses these types will be easy to understand, flexible, and
performant.

Boost.JSON offers these features:

* Fast compilation
* Require only C++11
* Fast streaming parser and serializer
* Constant-time key lookup for objects
* Options to allow non-standard JSON
* Easy and safe modern API with allocator support
* Optional header-only, without linking to a library

Visit https://boost.org/libs/json for complete documentation.

=== Requirements

* Requires only C++11
* Link to a built static or dynamic Boost library, or use header-only
(see below)
* Supports -fno-exceptions, detected automatically

The library relies heavily on these well known C++ types in its
interfaces (henceforth termed _standard types_):

* `string_view`
* `memory_resource`, `polymorphic_allocator`
* `error_category`, `error_code`, `error_condition`, `system_error`

==== Header-Only

To use as header-only; that is, to eliminate the requirement to link a
program to a static or dynamic Boost.JSON library, simply place the
following line in exactly one new or existing source file in your
project.

....
#include <boost/json/src.hpp>
....

MSVC users must also define the macro `BOOST_JSON_NO_LIB` to disable
auto-linking.

==== Embedded

Boost.JSON works great on embedded devices. The library uses local stack
buffers to increase the performance of some operations. On Intel
platforms these buffers are large (4KB), while on non-Intel platforms
they are small (256 bytes). To adjust the size of the stack buffers for
embedded applications define this macro when building the library or
including the function definitions:

....
#define BOOST_JSON_STACK_BUFFER_SIZE 1024
#include <boost/json/src.hpp>
....

==== Supported Compilers

Boost.JSON has been tested with the following compilers:

* clang: 3.5, 3.6, 3.7, 3.8, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
* gcc: 4.8, 4.9, 5, 6, 7, 8, 9, 10, 11, 12
* msvc: 14.0, 14.1, 14.2, 14.3

==== Supported JSON Text

The library expects input text to be encoded using UTF-8, which is a
requirement put on all JSON exchanged between systems by the
https://datatracker.ietf.org/doc/html/rfc8259#section-8.1[RFC].
Similarly, the text generated by the library is valid UTF-8.

The RFC does not allow byte order marks (BOM) to appear in JSON text, so
the library considers BOM syntax errors.

The library supports several popular JSON extensions. These have to be
explicitly enabled.

==== Visual Studio Solution

....
cmake -G "Visual Studio 16 2019" -A Win32 -B bin -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/msvc.cmake
cmake -G "Visual Studio 16 2019" -A x64 -B bin64 -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/msvc.cmake
....

=== Quality Assurance

The development infrastructure for the library includes these per-commit
analyses:

* Coverage reports
* Benchmark performance comparisons
* Compilation and tests on Drone.io, Azure Pipelines, Appveyor
* Fuzzing using clang-llvm and machine learning

=== License

Distributed under the Boost Software License, Version 1.0. (See
accompanying file LICENSE_1_0.txt or copy at
https://www.boost.org/LICENSE_1_0.txt)
