diff --git a/docs/api/bsoncxx/examples/bson_documents/access_array.md b/docs/api/bsoncxx/examples/bson_documents/access_array.md
new file mode 100644
index 0000000000..53961db315
--- /dev/null
+++ b/docs/api/bsoncxx/examples/bson_documents/access_array.md
@@ -0,0 +1,25 @@
+# Access an Array Element
+
+## By Iteration
+
+### Basic Example
+
+@snippet api/bsoncxx/examples/bson_documents/access_array/basic.cpp Example
+
+### Using Iterators
+
+@snippet api/bsoncxx/examples/bson_documents/access_array/iterators.cpp Example
+
+### Using Algorithms
+
+@snippet api/bsoncxx/examples/bson_documents/access_array/algorithms.cpp Example
+
+## By Key
+
+### Using find()
+
+@snippet api/bsoncxx/examples/bson_documents/access_array/find.cpp Example
+
+### Using the Subscript Operator
+
+@snippet api/bsoncxx/examples/bson_documents/access_array/subscript.cpp Example
diff --git a/docs/api/bsoncxx/examples/bson_documents/access_doc.md b/docs/api/bsoncxx/examples/bson_documents/access_doc.md
new file mode 100644
index 0000000000..2388edc3d1
--- /dev/null
+++ b/docs/api/bsoncxx/examples/bson_documents/access_doc.md
@@ -0,0 +1,25 @@
+# Access a Document Element
+
+## By Iteration
+
+### Basic Example
+
+@snippet api/bsoncxx/examples/bson_documents/access_doc/basic.cpp Example
+
+### Using Iterators
+
+@snippet api/bsoncxx/examples/bson_documents/access_doc/iterators.cpp Example
+
+### Using Algorithms
+
+@snippet api/bsoncxx/examples/bson_documents/access_doc/algorithms.cpp Example
+
+## By Key
+
+### Using find()
+
+@snippet api/bsoncxx/examples/bson_documents/access_doc/find.cpp Example
+
+### Using the Subscript Operator
+
+@snippet api/bsoncxx/examples/bson_documents/access_doc/subscript.cpp Example
diff --git a/docs/api/bsoncxx/examples/bson_documents/create_array.md b/docs/api/bsoncxx/examples/bson_documents/create_array.md
new file mode 100644
index 0000000000..0a08e21243
--- /dev/null
+++ b/docs/api/bsoncxx/examples/bson_documents/create_array.md
@@ -0,0 +1,79 @@
+# Create an Array
+
+## From a JSON String
+
+### Basic Example
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/json_basic.cpp Example
+
+### With Extended JSON
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/json_extended.cpp Example
+
+### With a Sub-Document
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/json_sub_document.cpp Example
+
+### With a Sub-Array
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/json_sub_array.cpp Example
+
+### With a User-Defined Literal
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/json_udl.cpp Example
+
+## Using the Basic Builder
+
+### Basic Example
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_basic.cpp Example
+
+### With make_document
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_make_document.cpp Example
+
+### With Multiple Appends
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_append.cpp Example
+
+### To Create Multiple Documents
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_reset.cpp Example
+
+### With a Value Type
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_value_type.cpp Example
+
+### With a BSON Type
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_bson_type.cpp Example
+
+### With a BSON Value
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_bson_value.cpp Example
+
+### With a Sub-Document
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_sub_document.cpp Example
+
+### With Multiple Sub-Document Appends
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_sub_document_append.cpp Example
+
+### With a Sub-Array
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_sub_array.cpp Example
+
+### With Multiple Sub-Array Appends
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_sub_array_append.cpp Example
+
+## From Raw Bytes
+
+### As a View
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_raw_view.cpp Example
+
+### As a Value
+
+@snippet api/bsoncxx/examples/bson_documents/create_array/builder_raw_value.cpp Example
diff --git a/docs/api/bsoncxx/examples/bson_documents/create_doc.md b/docs/api/bsoncxx/examples/bson_documents/create_doc.md
new file mode 100644
index 0000000000..34ef4194c5
--- /dev/null
+++ b/docs/api/bsoncxx/examples/bson_documents/create_doc.md
@@ -0,0 +1,79 @@
+# Create a Document
+
+## From a JSON String
+
+### Basic Example
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/json_basic.cpp Example
+
+### With Extended JSON
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/json_extended.cpp Example
+
+### With a Sub-Document
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/json_sub_document.cpp Example
+
+### With a Sub-Array
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/json_sub_array.cpp Example
+
+### With a User-Defined Literal
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/json_udl.cpp Example
+
+## Using the Basic Builder
+
+### Basic Example
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_basic.cpp Example
+
+### With make_document
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_make_document.cpp Example
+
+### With Multiple Appends
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_append.cpp Example
+
+### To Create Multiple Documents
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_reset.cpp Example
+
+### With a Value Type
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_value_type.cpp Example
+
+### With a BSON Type
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_bson_type.cpp Example
+
+### With a BSON Value
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_bson_value.cpp Example
+
+### With a Sub-Document
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_sub_document.cpp Example
+
+### With Multiple Sub-Document Appends
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_sub_document_append.cpp Example
+
+### With a Sub-Array
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_sub_array.cpp Example
+
+### With Multiple Sub-Array Appends
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_sub_array_append.cpp Example
+
+## From Raw Bytes
+
+### As a View
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_raw_view.cpp Example
+
+### As a Value
+
+@snippet api/bsoncxx/examples/bson_documents/create_doc/builder_raw_value.cpp Example
diff --git a/docs/api/bsoncxx/examples/bson_documents/elements.md b/docs/api/bsoncxx/examples/bson_documents/elements.md
new file mode 100644
index 0000000000..6819e767ab
--- /dev/null
+++ b/docs/api/bsoncxx/examples/bson_documents/elements.md
@@ -0,0 +1,31 @@
+# Query an Element
+
+## In a Document
+
+### For a Single Type
+
+@snippet api/bsoncxx/examples/bson_documents/elements/doc_single.cpp Example
+
+### For Multiple Types
+
+@snippet api/bsoncxx/examples/bson_documents/elements/doc_multi.cpp Example
+
+## In an Array
+
+### For Single Type
+
+@snippet api/bsoncxx/examples/bson_documents/elements/arr_single.cpp Example
+
+### For Multiple Types
+
+@snippet api/bsoncxx/examples/bson_documents/elements/arr_multi.cpp Example
+
+## Comparison
+
+### By Type
+
+@snippet api/bsoncxx/examples/bson_documents/elements/cmp_type.cpp Example
+
+### By BSON Value
+
+@snippet api/bsoncxx/examples/bson_documents/elements/cmp_bson_value.cpp Example
diff --git a/docs/api/bsoncxx/examples/bson_documents/json.md b/docs/api/bsoncxx/examples/bson_documents/json.md
new file mode 100644
index 0000000000..e54c2d8efa
--- /dev/null
+++ b/docs/api/bsoncxx/examples/bson_documents/json.md
@@ -0,0 +1,9 @@
+# Convert to a JSON String
+
+## From a Document
+
+@snippet api/bsoncxx/examples/bson_documents/json/document.cpp Example
+
+## From an Array
+
+@snippet api/bsoncxx/examples/bson_documents/json/array.cpp Example
diff --git a/docs/api/bsoncxx/examples/bson_documents/values.md b/docs/api/bsoncxx/examples/bson_documents/values.md
new file mode 100644
index 0000000000..6e864d5adb
--- /dev/null
+++ b/docs/api/bsoncxx/examples/bson_documents/values.md
@@ -0,0 +1,39 @@
+# Obtain a BSON Value
+
+## From a BSON Type
+
+### As a View
+
+@snippet api/bsoncxx/examples/bson_documents/values/bson_type_view.cpp Example
+
+### As a Value
+ 
+@snippet api/bsoncxx/examples/bson_documents/values/bson_type_value.cpp Example
+
+## From a Document Element
+
+### As a View
+
+@snippet api/bsoncxx/examples/bson_documents/values/doc_view.cpp Example
+
+### As a Value
+
+@snippet api/bsoncxx/examples/bson_documents/values/doc_value.cpp Example
+
+## From an Array Element
+
+### As a View
+
+@snippet api/bsoncxx/examples/bson_documents/values/arr_view.cpp Example
+
+### As a Value
+
+@snippet api/bsoncxx/examples/bson_documents/values/arr_value.cpp Example
+
+## From a Value Type
+
+@snippet api/bsoncxx/examples/bson_documents/values/value_type.cpp Example
+
+## With make_value
+
+@snippet api/bsoncxx/examples/bson_documents/values/make_value.cpp Example
diff --git a/docs/api/bsoncxx/examples/bson_errors.md b/docs/api/bsoncxx/examples/bson_errors.md
new file mode 100644
index 0000000000..308a9a0013
--- /dev/null
+++ b/docs/api/bsoncxx/examples/bson_errors.md
@@ -0,0 +1,115 @@
+# Create a BSON Document
+
+## From an Invalid JSON String
+
+@snippet api/bsoncxx/examples/bson_errors/create_json.cpp Example
+
+## Using the Basic Document Builder
+
+### Basic Append Failure
+
+@snippet api/bsoncxx/examples/bson_errors/create_doc_append.cpp Example
+
+### Sub-Document Append Failure
+
+@snippet api/bsoncxx/examples/bson_errors/create_doc_append_sub_document.cpp Example
+
+### Sub-Array Append Failure
+
+@snippet api/bsoncxx/examples/bson_errors/create_doc_append_sub_array.cpp Example
+
+## Using the Basic Array Builder
+
+### Basic Append Failure
+
+@snippet api/bsoncxx/examples/bson_errors/create_arr_append.cpp Example
+
+### Sub-Document Append Failure
+
+@snippet api/bsoncxx/examples/bson_errors/create_arr_append_sub_document.cpp Example
+
+### Sub-Array Append Failure
+
+@snippet api/bsoncxx/examples/bson_errors/create_arr_append_sub_array.cpp Example
+
+# Access a Document Element
+
+## By Iteration
+
+### End Iterators
+
+@snippet api/bsoncxx/examples/bson_errors/access_doc_iter_end.cpp Example
+
+### Invalid BSON Documents
+
+@snippet api/bsoncxx/examples/bson_errors/access_doc_iter_invalid.cpp Example
+
+## By Key
+
+### Missing Element
+
+@snippet api/bsoncxx/examples/bson_errors/access_doc_key_missing.cpp Example
+
+# Access an Array Element
+
+## By Iteration
+
+### End Iterators
+
+@snippet api/bsoncxx/examples/bson_errors/access_arr_iter_end.cpp Example
+
+### Invalid BSON Arrays
+
+@snippet api/bsoncxx/examples/bson_errors/access_arr_iter_invalid.cpp Example
+
+## By Key
+
+### Missing Element
+
+@snippet api/bsoncxx/examples/bson_errors/access_arr_key_missing.cpp Example
+
+# Query an Element
+
+## In a Document
+
+### Invalid Element
+
+@snippet api/bsoncxx/examples/bson_errors/query_element_doc_invalid.cpp Example
+
+### Invalid Type
+
+@snippet api/bsoncxx/examples/bson_errors/query_element_doc_invalid_type.cpp Example
+
+## In an Array
+
+### Invalid Element
+
+@snippet api/bsoncxx/examples/bson_errors/query_element_arr_invalid.cpp Example
+
+### Invalid Type
+
+@snippet api/bsoncxx/examples/bson_errors/query_element_arr_invalid_type.cpp Example
+
+# Use a BSON Value
+
+## Query an Invalid Type
+
+@snippet api/bsoncxx/examples/bson_errors/query_bson_value_invalid_type.cpp Example
+
+## Create an Invalid Value
+
+@snippet api/bsoncxx/examples/bson_errors/create_bson_value_invalid_type.cpp Example
+
+## From an Invalid Element
+
+@snippet api/bsoncxx/examples/bson_errors/create_bson_value_invalid_element.cpp Example
+
+# Convert to a JSON String
+
+## From an Invalid BSON Document
+
+@snippet api/bsoncxx/examples/bson_errors/to_json_invalid_doc.cpp Example
+
+## From an Invalid BSON Array
+
+@snippet api/bsoncxx/examples/bson_errors/to_json_invalid_arr.cpp Example
diff --git a/docs/api/bsoncxx/examples/decimal128.md b/docs/api/bsoncxx/examples/decimal128.md
new file mode 100644
index 0000000000..65bb07d99a
--- /dev/null
+++ b/docs/api/bsoncxx/examples/decimal128.md
@@ -0,0 +1,11 @@
+# Basic Usage
+
+@snippet api/bsoncxx/examples/decimal128/basic_usage.cpp Example
+
+# From Bytes
+
+@snippet api/bsoncxx/examples/decimal128/from_bytes.cpp Example
+
+# Error Handling
+
+@snippet api/bsoncxx/examples/decimal128/errors.cpp Example
diff --git a/docs/api/bsoncxx/examples/oid.md b/docs/api/bsoncxx/examples/oid.md
new file mode 100644
index 0000000000..95705d7fd8
--- /dev/null
+++ b/docs/api/bsoncxx/examples/oid.md
@@ -0,0 +1,7 @@
+# Basic Usage
+
+@snippet api/bsoncxx/examples/oid/basic_usage.cpp Example
+
+# Error Handling
+
+@snippet api/bsoncxx/examples/oid/errors.cpp Example
diff --git a/docs/api/bsoncxx/examples/validation.md b/docs/api/bsoncxx/examples/validation.md
new file mode 100644
index 0000000000..be4e549617
--- /dev/null
+++ b/docs/api/bsoncxx/examples/validation.md
@@ -0,0 +1,7 @@
+# Basic Usage
+
+@snippet api/bsoncxx/examples/validation/basic_usage.cpp Example
+
+# With Validator
+
+@snippet api/bsoncxx/examples/validation/validator.cpp Example
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index bcc3d56f1e..162db903d6 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -101,19 +101,9 @@ function(add_examples_executable source)
 
     if (PARSED_ADD_TO_RUN_EXAMPLES)
         add_dependencies(run-${type}-examples run-examples-${target_name})
-
-        if (${subdir} MATCHES "^api/")
-            add_dependencies(run-${type}-examples run-examples-${target_name})
-        endif ()
     endif ()
 endfunction()
 
-file(GLOB_RECURSE api_examples_sources
-    RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
-    CONFIGURE_DEPENDS
-    "api/*.cpp"
-)
-
 file(GLOB_RECURSE bsoncxx_examples_sources
     RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
     CONFIGURE_DEPENDS
@@ -134,6 +124,16 @@ file(GLOB_RECURSE examples_headers
 
 foreach(source ${api_examples_sources})
     add_examples_executable(${source} LIBRARIES mongocxx_target)
+
+    # Silence warnings for common patterns in API examples.
+    set_property (SOURCE ${source} APPEND PROPERTY COMPILE_OPTIONS
+        # Allow unused variables.
+        $<$<CXX_COMPILER_ID:AppleClang,Clang,GNU>:-Wno-unused>
+        $<$<CXX_COMPILER_ID:MSVC>:/wd4189>
+
+        # Allow simpler switch statements.
+        $<$<CXX_COMPILER_ID:AppleClang,Clang,GNU>:-Wno-switch>
+    )
 endforeach()
 
 foreach(source ${bsoncxx_examples_sources})
@@ -159,6 +159,46 @@ foreach(source ${mongocxx_examples_sources})
     )
 endforeach()
 
+file(GLOB_RECURSE api_examples_sources
+    RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
+    CONFIGURE_DEPENDS
+    "api/*.cpp"
+)
+list(REMOVE_ITEM api_examples_sources "api/runner.cpp")
+
+function (add_abi_examples)
+    # Avoid MAX_PATH errors on Windows due to long target names by using a single `api-runner` .
+    add_examples_executable(api/runner.cpp LIBRARIES mongocxx_target Threads::Threads)
+
+    # Define a unique entry function name per component.
+    foreach (source ${api_examples_sources})
+        target_sources (api-runner PRIVATE ${source})
+
+        # path/to/source.cpp -> source
+        get_filename_component(name ${source} NAME_WE)
+
+        # path/to/source.cpp -> path/to
+        get_filename_component(subdir ${source} DIRECTORY)
+
+        # path/to/source -> path_to_source
+        string(REPLACE "/" "_" component_name "${subdir}/${name}")
+
+        # Define a unique component name for each component to be registered with the runner.
+        set_property (SOURCE ${source} APPEND PROPERTY COMPILE_DEFINITIONS "EXAMPLES_COMPONENT_NAME=${component_name}")
+    endforeach ()
+
+    # Silence warnings for common patterns in API examples.
+    set_property (TARGET api-runner APPEND PROPERTY COMPILE_OPTIONS
+        # Allow unused variables.
+        $<$<CXX_COMPILER_ID:AppleClang,Clang,GNU>:-Wno-unused>
+        $<$<CXX_COMPILER_ID:MSVC>:/wd4189>
+
+        # Allow simpler switch statements.
+        $<$<CXX_COMPILER_ID:AppleClang,Clang,GNU>:-Wno-switch>
+    )
+endfunction ()
+add_abi_examples ()
+
 set_local_dist (examples_DIST_local
    CMakeLists.txt
    ${api_examples_sources}
@@ -169,6 +209,7 @@ set_local_dist (examples_DIST_local
    add_subdirectory/.gitignore
    add_subdirectory/CMakeLists.txt
    add_subdirectory/hello_mongocxx.cpp
+   api/runner.cpp
    projects/bsoncxx/cmake/shared/build.sh
    projects/bsoncxx/cmake/shared/build/.gitignore
    projects/bsoncxx/cmake/shared/CMakeLists.txt
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_array/algorithms.cpp b/examples/api/bsoncxx/examples/bson_documents/access_array/algorithms.cpp
new file mode 100644
index 0000000000..e0897f7151
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_array/algorithms.cpp
@@ -0,0 +1,50 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <algorithm>
+#include <vector>
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2.0, "three"]
+void example(bsoncxx::array::view arr) {
+    ASSERT(std::distance(arr.begin(), arr.end()) == 3);
+
+    std::vector<bsoncxx::array::element> elements;
+
+    std::copy_if(
+        arr.begin(), arr.end(), std::back_inserter(elements), [](const bsoncxx::array::element& e) {
+            return e.key().compare("0") == 0 || e.type() == bsoncxx::type::k_string;
+        });
+
+    ASSERT(elements.size() == 2u);
+    ASSERT(elements[0].key().compare("0") == 0);
+    ASSERT(elements[1].key().compare("2") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})")["v"].get_array().value);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_array/basic.cpp b/examples/api/bsoncxx/examples/bson_documents/access_array/basic.cpp
new file mode 100644
index 0000000000..eb0dad5a65
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_array/basic.cpp
@@ -0,0 +1,52 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2.0, "three"]
+void example(bsoncxx::array::view arr) {
+    for (bsoncxx::array::element e : arr) {
+        switch (e.type()) {
+            case bsoncxx::type::k_int32:
+                ASSERT(e.key().compare("0") == 0);
+                ASSERT(e.get_int32().value == 1);
+                break;
+            case bsoncxx::type::k_double:
+                ASSERT(e.key().compare("1") == 0);
+                ASSERT(e.get_double().value == 2.0);
+                break;
+            case bsoncxx::type::k_string:
+                ASSERT(e.key().compare("2") == 0);
+                ASSERT(e.get_string().value.compare("three") == 0);
+                break;
+        }
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {  // clang-format off
+    example(bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})")["v"].get_array().value);
+
+}  // clang-format on
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_array/find.cpp b/examples/api/bsoncxx/examples/bson_documents/access_array/find.cpp
new file mode 100644
index 0000000000..94fbefcbf9
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_array/find.cpp
@@ -0,0 +1,45 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2]
+void example(bsoncxx::array::view arr) {
+    ASSERT(arr.find(0) == arr.begin());
+
+    {
+        auto iter = arr.find(1);
+
+        ASSERT(iter != arr.end());
+        ASSERT(iter->key().compare("1") == 0);
+        ASSERT(iter->get_int32().value == 2);
+    }
+
+    ASSERT(arr.find(2) == arr.end());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"v": [1, 2]})")["v"].get_array().value);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_array/iterators.cpp b/examples/api/bsoncxx/examples/bson_documents/access_array/iterators.cpp
new file mode 100644
index 0000000000..30c3f9532f
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_array/iterators.cpp
@@ -0,0 +1,61 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2]
+void example(bsoncxx::array::view arr) {
+    ASSERT(arr.begin() != arr.end());
+
+    auto iter = arr.begin();
+    ASSERT(iter == arr.begin());
+
+    {
+        bsoncxx::array::element e = *iter;
+
+        ASSERT(e.key().compare("0") == 0);
+        ASSERT(e.get_int32().value == 1);
+    }
+
+    ++iter;
+
+    ASSERT(iter->key().compare("1") == 0);
+    ASSERT(iter->get_int32().value == 2);
+
+    {
+        auto iter_copy = iter++;
+
+        ASSERT(iter_copy != iter);
+        ASSERT(iter_copy->key().compare("1") == 0);
+        ASSERT(iter_copy->get_int32() == 2);
+    }
+
+    ASSERT(iter == arr.end());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"v": [1, 2]})")["v"].get_array().value);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_array/subscript.cpp b/examples/api/bsoncxx/examples/bson_documents/access_array/subscript.cpp
new file mode 100644
index 0000000000..db1bfdab51
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_array/subscript.cpp
@@ -0,0 +1,45 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2]
+void example(bsoncxx::array::view arr) {
+    ASSERT(arr[0]);
+
+    {
+        bsoncxx::array::element e = arr[1];
+
+        ASSERT(e.key().compare("1") == 0);
+        ASSERT(e.get_int32().value == 2);
+    }
+
+    ASSERT(!arr[2]);  // Invalid element.
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"v": [1, 2]})")["v"].get_array().value);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_doc/algorithms.cpp b/examples/api/bsoncxx/examples/bson_documents/access_doc/algorithms.cpp
new file mode 100644
index 0000000000..f24e42a98d
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_doc/algorithms.cpp
@@ -0,0 +1,53 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <algorithm>
+#include <iterator>
+#include <vector>
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2.0, "c": "three"}
+void example(bsoncxx::document::view doc) {
+    ASSERT(std::distance(doc.begin(), doc.end()) == 3);
+
+    std::vector<bsoncxx::document::element> elements;
+
+    std::copy_if(doc.begin(),
+                 doc.end(),
+                 std::back_inserter(elements),
+                 [](const bsoncxx::document::element& e) {
+                     return e.key().compare("a") == 0 || e.type() == bsoncxx::type::k_string;
+                 });
+
+    ASSERT(elements.size() == 2u);
+    ASSERT(elements[0].key().compare("a") == 0);
+    ASSERT(elements[1].key().compare("c") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"a": 1, "b": 2.0, "c": "three"})"));
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_doc/basic.cpp b/examples/api/bsoncxx/examples/bson_documents/access_doc/basic.cpp
new file mode 100644
index 0000000000..95aa123912
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_doc/basic.cpp
@@ -0,0 +1,51 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2.0, "c": "three"}
+void example(bsoncxx::document::view doc) {
+    for (bsoncxx::document::element e : doc) {
+        switch (e.type()) {
+            case bsoncxx::type::k_int32:
+                ASSERT(e.key().compare("a") == 0);
+                ASSERT(e.get_int32().value == 1);
+                break;
+            case bsoncxx::type::k_double:
+                ASSERT(e.key().compare("b") == 0);
+                ASSERT(e.get_double().value == 2.0);
+                break;
+            case bsoncxx::type::k_string:
+                ASSERT(e.key().compare("c") == 0);
+                ASSERT(e.get_string().value.compare("three") == 0);
+                break;
+        }
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"a": 1, "b": 2.0, "c": "three"})"));
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_doc/find.cpp b/examples/api/bsoncxx/examples/bson_documents/access_doc/find.cpp
new file mode 100644
index 0000000000..03afcb3af7
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_doc/find.cpp
@@ -0,0 +1,45 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2}
+void example(bsoncxx::document::view doc) {
+    ASSERT(doc.find("a") == doc.begin());
+
+    {
+        auto iter = doc.find("b");
+
+        ASSERT(iter != doc.end());
+        ASSERT(iter->key().compare("b") == 0);
+        ASSERT(iter->get_int32().value == 2);
+    }
+
+    ASSERT(doc.find("x") == doc.end());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"a": 1, "b": 2})"));
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_doc/iterators.cpp b/examples/api/bsoncxx/examples/bson_documents/access_doc/iterators.cpp
new file mode 100644
index 0000000000..ff8cbcc5ce
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_doc/iterators.cpp
@@ -0,0 +1,61 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2}
+void example(bsoncxx::document::view doc) {
+    ASSERT(doc.begin() != doc.end());
+
+    auto iter = doc.begin();
+    ASSERT(iter == doc.begin());
+
+    {
+        bsoncxx::document::element e = *iter;
+
+        ASSERT(e.key().compare("a") == 0);
+        ASSERT(e.get_int32().value == 1);
+    }
+
+    ++iter;
+
+    ASSERT(iter->key().compare("b") == 0);
+    ASSERT(iter->get_int32().value == 2);
+
+    {
+        auto iter_copy = iter++;
+
+        ASSERT(iter_copy != iter);
+        ASSERT(iter_copy->key().compare("b") == 0);
+        ASSERT(iter_copy->get_int32() == 2);
+    }
+
+    ASSERT(iter == doc.end());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"a": 1, "b": 2})"));
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/access_doc/subscript.cpp b/examples/api/bsoncxx/examples/bson_documents/access_doc/subscript.cpp
new file mode 100644
index 0000000000..398558dd52
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/access_doc/subscript.cpp
@@ -0,0 +1,45 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2}
+void example(bsoncxx::document::view doc) {
+    ASSERT(doc["a"]);
+
+    {
+        bsoncxx::document::element e = doc["b"];
+
+        ASSERT(e.key().compare("b") == 0);
+        ASSERT(e.get_int32().value == 2);
+    }
+
+    ASSERT(!doc["c"]);  // Invalid element.
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"a": 1, "b": 2})"));
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_append.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_append.cpp
new file mode 100644
index 0000000000..ad56ae3c5a
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_append.cpp
@@ -0,0 +1,46 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::builder::basic::array builder;
+    builder.append(std::int32_t{1});
+    builder.append(2.0);
+    builder.append("three");
+    bsoncxx::array::value owner = builder.extract();
+    bsoncxx::array::view arr = owner.view();
+
+    ASSERT(arr[0].get_int32().value == 1);
+    ASSERT(arr[1].get_double().value == 2.0);
+    ASSERT(arr[2].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_basic.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_basic.cpp
new file mode 100644
index 0000000000..53ffd5facf
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_basic.cpp
@@ -0,0 +1,44 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::builder::basic::array builder;
+    builder.append(std::int32_t{1}, 2.0, "three");
+    bsoncxx::array::value owner = builder.extract();
+    bsoncxx::array::view arr = owner.view();
+
+    ASSERT(arr[0].get_int32().value == 1);
+    ASSERT(arr[1].get_double().value == 2.0);
+    ASSERT(arr[2].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_bson_type.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_bson_type.cpp
new file mode 100644
index 0000000000..f15f76e480
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_bson_type.cpp
@@ -0,0 +1,48 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::types::b_int32 a{1};
+    bsoncxx::types::b_double b{2.0};
+    bsoncxx::types::b_string c{"three"};
+
+    bsoncxx::array::value owner = bsoncxx::builder::basic::make_array(a, b, c);
+    bsoncxx::array::view arr = owner.view();
+
+    ASSERT(arr[0].type() == bsoncxx::type::k_int32);
+    ASSERT(arr[1].type() == bsoncxx::type::k_double);
+    ASSERT(arr[2].type() == bsoncxx::type::k_string);
+
+    ASSERT(arr[0].get_int32().value == 1);
+    ASSERT(arr[1].get_double().value == 2.0);
+    ASSERT(arr[2].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_bson_value.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_bson_value.cpp
new file mode 100644
index 0000000000..4a66341d01
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_bson_value.cpp
@@ -0,0 +1,57 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/value.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::types::bson_value::value values[]{
+        std::int32_t{1},
+        2.0,
+        "three",
+    };
+
+    bsoncxx::array::value owner =
+        bsoncxx::builder::basic::make_array(values[0], values[1], values[2]);
+    bsoncxx::array::view arr = owner.view();
+
+    ASSERT(arr[0].type() == bsoncxx::type::k_int32);
+    ASSERT(arr[1].type() == bsoncxx::type::k_double);
+    ASSERT(arr[2].type() == bsoncxx::type::k_string);
+
+    ASSERT(arr[0].get_value() == values[0]);
+    ASSERT(arr[1].get_value() == values[1]);
+    ASSERT(arr[2].get_value() == values[2]);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_make_document.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_make_document.cpp
new file mode 100644
index 0000000000..b36ade8f15
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_make_document.cpp
@@ -0,0 +1,43 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::array::value owner =
+        bsoncxx::builder::basic::make_array(std::int32_t{1}, 2.0, "three");
+    bsoncxx::array::view arr = owner.view();
+
+    ASSERT(arr[0].get_int32().value == 1);
+    ASSERT(arr[1].get_double().value == 2.0);
+    ASSERT(arr[2].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_raw_value.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_raw_value.cpp
new file mode 100644
index 0000000000..aa7777425d
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_raw_value.cpp
@@ -0,0 +1,54 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2]
+void example(const std::uint8_t* data, std::size_t length) {
+    using deleter_type = bsoncxx::array::value::deleter_type;
+
+    std::uint8_t* raw = new std::uint8_t[length];
+    std::copy_n(data, length, raw);
+
+    deleter_type deleter = [](std::uint8_t* data) { delete[] data; };
+    bsoncxx::array::value owner{raw, length, deleter};
+    bsoncxx::array::view arr = owner.view();
+
+    ASSERT(arr[0].get_int32().value == 1);
+    ASSERT(arr[1].get_int32().value == 2);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"({"v": [1, 2]})");
+    bsoncxx::array::view arr = owner.view()["v"].get_array().value;
+
+    example(arr.data(), arr.length());
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_raw_view.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_raw_view.cpp
new file mode 100644
index 0000000000..4c1c194482
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_raw_view.cpp
@@ -0,0 +1,46 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstddef>
+#include <cstdint>
+
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2]
+void example(const std::uint8_t* data, std::size_t length) {
+    bsoncxx::array::view arr{data, length};
+
+    ASSERT(arr[0].get_int32().value == 1);
+    ASSERT(arr[1].get_int32().value == 2);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"({"v": [1, 2]})");
+    bsoncxx::array::view arr = owner.view()["v"].get_array().value;
+
+    example(arr.data(), arr.length());
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_reset.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_reset.cpp
new file mode 100644
index 0000000000..20938e8b48
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_reset.cpp
@@ -0,0 +1,54 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::builder::basic::array builder;
+
+    builder.append(std::int32_t{1});
+    bsoncxx::array::value a_owner = builder.extract();
+
+    builder.clear();
+
+    builder.append(std::int64_t{2});
+    bsoncxx::array::value b_owner = builder.extract();
+
+    bsoncxx::array::view a = a_owner.view();
+    bsoncxx::array::view b = b_owner.view();
+
+    ASSERT(a[0].type() == bsoncxx::type::k_int32);
+    ASSERT(b[0].type() == bsoncxx::type::k_int64);
+
+    ASSERT(a[0].get_int32().value == 1);
+    ASSERT(b[0].get_int64().value == 2);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_array.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_array.cpp
new file mode 100644
index 0000000000..84698f7cdd
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_array.cpp
@@ -0,0 +1,45 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::make_array;
+
+    bsoncxx::array::value owner = make_array(make_array(std::int32_t{1}, std::int64_t{2}));
+    bsoncxx::array::view v = owner.view()[0].get_array().value;
+
+    ASSERT(v[0].type() == bsoncxx::type::k_int32);
+    ASSERT(v[1].type() == bsoncxx::type::k_int64);
+
+    ASSERT(v[0].get_int32().value == 1);
+    ASSERT(v[1].get_int64().value == 2);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_array_append.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_array_append.cpp
new file mode 100644
index 0000000000..aea40ad1ea
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_array_append.cpp
@@ -0,0 +1,48 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    std::int32_t values[] = {1, 2, 3};
+
+    bsoncxx::array::value owner =
+        bsoncxx::builder::basic::make_array([&](bsoncxx::builder::basic::sub_array arr) {
+            for (int i = 0; i < 3; ++i) {
+                arr.append(values[i]);
+            }
+        });
+    bsoncxx::array::view v = owner.view()[0].get_array().value;
+
+    ASSERT(v[0].get_int32().value == 1);
+    ASSERT(v[1].get_int32().value == 2);
+    ASSERT(v[2].get_int32().value == 3);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_document.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_document.cpp
new file mode 100644
index 0000000000..412eab43dd
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_document.cpp
@@ -0,0 +1,42 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+    using bsoncxx::builder::basic::make_array;
+    using bsoncxx::builder::basic::make_document;
+
+    bsoncxx::array::value owner = make_array(make_document(kvp("key", "value")));
+    bsoncxx::document::view v = owner.view()[0].get_document().value;
+
+    ASSERT(v["key"].get_string().value.compare("value") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_document_append.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_document_append.cpp
new file mode 100644
index 0000000000..77f158152f
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_sub_document_append.cpp
@@ -0,0 +1,53 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+#include <string>
+
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/builder/basic/sub_document.hpp>
+#include <bsoncxx/document/view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    std::string keys[] = {"a", "b", "c"};
+    std::int32_t values[] = {1, 2, 3};
+
+    bsoncxx::array::value owner =
+        bsoncxx::builder::basic::make_array([&](bsoncxx::builder::basic::sub_document doc) {
+            for (int i = 0; i < 3; ++i) {
+                doc.append(kvp(keys[i], values[i]));
+            }
+        });
+    bsoncxx::document::view v = owner.view()[0].get_document().value;
+
+    ASSERT(v["a"].get_int32().value == 1);
+    ASSERT(v["b"].get_int32().value == 2);
+    ASSERT(v["c"].get_int32().value == 3);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/builder_value_type.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_value_type.cpp
new file mode 100644
index 0000000000..d577099be6
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/builder_value_type.cpp
@@ -0,0 +1,47 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::array::value owner =
+        bsoncxx::builder::basic::make_array(std::int32_t{1}, 2.0, "three");
+    bsoncxx::array::view arr = owner.view();
+
+    ASSERT(arr[0].type() == bsoncxx::type::k_int32);
+    ASSERT(arr[1].type() == bsoncxx::type::k_double);
+    ASSERT(arr[2].type() == bsoncxx::type::k_string);
+
+    ASSERT(arr[0].get_int32().value == 1);
+    ASSERT(arr[1].get_double().value == 2.0);
+    ASSERT(arr[2].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/json_basic.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/json_basic.cpp
new file mode 100644
index 0000000000..b52cdfb24b
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/json_basic.cpp
@@ -0,0 +1,42 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"(
+        [1, 2.0, "three"]
+    )");
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["0"].get_int32().value == 1);
+    ASSERT(doc["1"].get_double().value == 2.0);
+    ASSERT(doc["2"].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/json_extended.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/json_extended.cpp
new file mode 100644
index 0000000000..1cbb9cddb0
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/json_extended.cpp
@@ -0,0 +1,46 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"(
+        [
+            {"$numberInt":    "1"},
+            {"$numberLong":   "2"},
+            {"$numberDouble": "3"}
+        ]
+    )");
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["0"].get_int32().value == 1);
+    ASSERT(doc["1"].get_int64().value == 2);
+    ASSERT(doc["2"].get_double().value == 3.0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/json_sub_array.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/json_sub_array.cpp
new file mode 100644
index 0000000000..ab5f41743a
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/json_sub_array.cpp
@@ -0,0 +1,43 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"(
+        [
+            [1, 2]
+        ]
+    )");
+    bsoncxx::array::view sub = owner.view()["0"].get_array().value;
+
+    ASSERT(sub[0].get_int32().value == 1);
+    ASSERT(sub[1].get_int32().value == 2);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/json_sub_document.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/json_sub_document.cpp
new file mode 100644
index 0000000000..4efcb1c9fd
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/json_sub_document.cpp
@@ -0,0 +1,42 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"(
+        [
+            {"key": "value"}
+        ]
+    )");
+    bsoncxx::document::view v = owner.view()["0"].get_document().value;
+
+    ASSERT(v["key"].get_string().value.compare("value") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_array/json_udl.cpp b/examples/api/bsoncxx/examples/bson_documents/create_array/json_udl.cpp
new file mode 100644
index 0000000000..544674d790
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_array/json_udl.cpp
@@ -0,0 +1,38 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/json.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using namespace bsoncxx;
+
+    bsoncxx::document::value a = R"([1, 2])"_bson;
+    bsoncxx::document::value b = bsoncxx::from_json(R"([1, 2])");
+
+    ASSERT(a == b);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_append.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_append.cpp
new file mode 100644
index 0000000000..fc7aea9fc2
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_append.cpp
@@ -0,0 +1,49 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::builder::basic::document builder;
+    builder.append(kvp("a", std::int32_t{1}));
+    builder.append(kvp("b", 2.0));
+    builder.append(kvp("c", "three"));
+    bsoncxx::document::value owner = builder.extract();
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["a"].get_int32().value == 1);
+    ASSERT(doc["b"].get_double().value == 2.0);
+    ASSERT(doc["c"].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_basic.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_basic.cpp
new file mode 100644
index 0000000000..c523665e4d
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_basic.cpp
@@ -0,0 +1,47 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::builder::basic::document builder;
+    builder.append(kvp("a", std::int32_t{1}), kvp("b", 2.0), kvp("c", "three"));
+    bsoncxx::document::value owner = builder.extract();
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["a"].get_int32().value == 1);
+    ASSERT(doc["b"].get_double().value == 2.0);
+    ASSERT(doc["c"].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_bson_type.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_bson_type.cpp
new file mode 100644
index 0000000000..3beeaa2eeb
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_bson_type.cpp
@@ -0,0 +1,54 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::types::b_int32 a{1};
+    bsoncxx::types::b_double b{2.0};
+    bsoncxx::types::b_string c{"three"};
+
+    bsoncxx::document::value owner =
+        bsoncxx::builder::basic::make_document(kvp("a", a), kvp("b", b), kvp("c", c));
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["a"].type() == bsoncxx::type::k_int32);
+    ASSERT(doc["b"].type() == bsoncxx::type::k_double);
+    ASSERT(doc["c"].type() == bsoncxx::type::k_string);
+
+    ASSERT(doc["a"].get_int32() == a);
+    ASSERT(doc["b"].get_double() == b);
+    ASSERT(doc["c"].get_string() == c);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_bson_value.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_bson_value.cpp
new file mode 100644
index 0000000000..eec1f9a05e
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_bson_value.cpp
@@ -0,0 +1,57 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/value.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::types::bson_value::value values[]{
+        std::int32_t{1},
+        2.0,
+        "three",
+    };
+
+    bsoncxx::document::value owner = bsoncxx::builder::basic::make_document(
+        kvp("a", values[0]), kvp("b", values[1]), kvp("c", values[2]));
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["a"].type() == bsoncxx::type::k_int32);
+    ASSERT(doc["b"].type() == bsoncxx::type::k_double);
+    ASSERT(doc["c"].type() == bsoncxx::type::k_string);
+
+    ASSERT(doc["a"].get_value() == values[0]);
+    ASSERT(doc["b"].get_value() == values[1]);
+    ASSERT(doc["c"].get_value() == values[2]);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_make_document.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_make_document.cpp
new file mode 100644
index 0000000000..36440ddcba
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_make_document.cpp
@@ -0,0 +1,46 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::document::value owner = bsoncxx::builder::basic::make_document(
+        kvp("a", std::int32_t{1}), kvp("b", 2.0), kvp("c", "three"));
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["a"].get_int32().value == 1);
+    ASSERT(doc["b"].get_double().value == 2.0);
+    ASSERT(doc["c"].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_raw_value.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_raw_value.cpp
new file mode 100644
index 0000000000..90d263daa1
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_raw_value.cpp
@@ -0,0 +1,52 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"key": "value"}
+void example(const std::uint8_t* data, std::size_t length) {
+    using deleter_type = bsoncxx::document::value::deleter_type;
+
+    std::uint8_t* raw = new std::uint8_t[length];
+    std::copy_n(data, length, raw);
+
+    deleter_type deleter = [](std::uint8_t* data) { delete[] data; };
+    bsoncxx::document::value owner{raw, length, deleter};
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["key"].get_string().value.compare("value") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"({"key": "value"})");
+    bsoncxx::document::view doc = owner.view();
+
+    example(doc.data(), doc.length());
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_raw_view.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_raw_view.cpp
new file mode 100644
index 0000000000..0f45aa72c1
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_raw_view.cpp
@@ -0,0 +1,44 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstddef>
+#include <cstdint>
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"key": "value"}
+void example(const std::uint8_t* data, std::size_t length) {
+    bsoncxx::document::view doc{data, length};
+
+    ASSERT(doc["key"].get_string().value.compare("value") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"({"key": "value"})");
+    bsoncxx::document::view doc = owner.view();
+
+    example(doc.data(), doc.length());
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_reset.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_reset.cpp
new file mode 100644
index 0000000000..a508694604
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_reset.cpp
@@ -0,0 +1,57 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::builder::basic::document builder;
+
+    builder.append(kvp("v", std::int32_t{1}));
+    bsoncxx::document::value a_owner = builder.extract();
+
+    builder.clear();
+
+    builder.append(kvp("v", std::int64_t{2}));
+    bsoncxx::document::value b_owner = builder.extract();
+
+    bsoncxx::document::view a = a_owner.view();
+    bsoncxx::document::view b = b_owner.view();
+
+    ASSERT(a["v"].type() == bsoncxx::type::k_int32);
+    ASSERT(b["v"].type() == bsoncxx::type::k_int64);
+
+    ASSERT(a["v"].get_int32().value == 1);
+    ASSERT(b["v"].get_int64().value == 2);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_array.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_array.cpp
new file mode 100644
index 0000000000..94f2ac8639
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_array.cpp
@@ -0,0 +1,51 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+    using bsoncxx::builder::basic::make_array;
+    using bsoncxx::builder::basic::make_document;
+
+    bsoncxx::document::value owner =
+        make_document(kvp("v", make_array(std::int32_t{1}, std::int64_t{2})));
+    bsoncxx::array::view v = owner.view()["v"].get_array().value;
+
+    ASSERT(v[0].type() == bsoncxx::type::k_int32);
+    ASSERT(v[1].type() == bsoncxx::type::k_int64);
+
+    ASSERT(v[0].get_int32().value == 1);
+    ASSERT(v[1].get_int64().value == 2);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_array_append.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_array_append.cpp
new file mode 100644
index 0000000000..f5c62e1967
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_array_append.cpp
@@ -0,0 +1,53 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/builder/basic/sub_array.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    std::int32_t values[] = {1, 2, 3};
+
+    bsoncxx::document::value owner = bsoncxx::builder::basic::make_document(
+        kvp("v", [&](bsoncxx::builder::basic::sub_array arr) {
+            for (int i = 0; i < 3; ++i) {
+                arr.append(values[i]);
+            }
+        }));
+    bsoncxx::array::view v = owner.view()["v"].get_array().value;
+
+    ASSERT(v[0].get_int32().value == 1);
+    ASSERT(v[1].get_int32().value == 2);
+    ASSERT(v[2].get_int32().value == 3);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_document.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_document.cpp
new file mode 100644
index 0000000000..c5b2da0cec
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_document.cpp
@@ -0,0 +1,42 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+    using bsoncxx::builder::basic::make_document;
+
+    bsoncxx::document::value owner = make_document(kvp("v", make_document(kvp("key", "value"))));
+    bsoncxx::document::view v = owner.view()["v"].get_document().value;
+
+    ASSERT(v["key"].get_string().value.compare("value") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_document_append.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_document_append.cpp
new file mode 100644
index 0000000000..6537488a0b
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_sub_document_append.cpp
@@ -0,0 +1,53 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    std::string keys[] = {"a", "b", "c"};
+    std::int32_t values[] = {1, 2, 3};
+
+    bsoncxx::document::value owner = bsoncxx::builder::basic::make_document(
+        kvp("v", [&](bsoncxx::builder::basic::sub_document doc) {
+            for (int i = 0; i < 3; ++i) {
+                doc.append(kvp(keys[i], values[i]));
+            }
+        }));
+    bsoncxx::document::view v = owner.view()["v"].get_document().value;
+
+    ASSERT(v["a"].get_int32().value == 1);
+    ASSERT(v["b"].get_int32().value == 2);
+    ASSERT(v["c"].get_int32().value == 3);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_value_type.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_value_type.cpp
new file mode 100644
index 0000000000..22398aa81a
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/builder_value_type.cpp
@@ -0,0 +1,50 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::document::value owner = bsoncxx::builder::basic::make_document(
+        kvp("a", std::int32_t{1}), kvp("b", 2.0), kvp("c", "three"));
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["a"].type() == bsoncxx::type::k_int32);
+    ASSERT(doc["b"].type() == bsoncxx::type::k_double);
+    ASSERT(doc["c"].type() == bsoncxx::type::k_string);
+
+    ASSERT(doc["a"].get_int32().value == 1);
+    ASSERT(doc["b"].get_double().value == 2.0);
+    ASSERT(doc["c"].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/json_basic.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_basic.cpp
new file mode 100644
index 0000000000..c9eccc453e
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_basic.cpp
@@ -0,0 +1,46 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"(
+        {
+            "a": 1,
+            "b": 2.0,
+            "c": "three"
+        }
+    )");
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["a"].get_int32().value == 1);
+    ASSERT(doc["b"].get_double().value == 2.0);
+    ASSERT(doc["c"].get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/json_extended.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_extended.cpp
new file mode 100644
index 0000000000..0cad361a20
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_extended.cpp
@@ -0,0 +1,46 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"(
+        {
+            "a": {"$numberInt":    "1"},
+            "b": {"$numberLong":   "2"},
+            "c": {"$numberDouble": "3"}
+        }
+    )");
+    bsoncxx::document::view doc = owner.view();
+
+    ASSERT(doc["a"].get_int32().value == 1);
+    ASSERT(doc["b"].get_int64().value == 2);
+    ASSERT(doc["c"].get_double().value == 3.0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/json_sub_array.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_sub_array.cpp
new file mode 100644
index 0000000000..07c4e74d24
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_sub_array.cpp
@@ -0,0 +1,43 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value owner = bsoncxx::from_json(R"(
+        {
+            "v": [1, 2]
+        }
+    )");
+    bsoncxx::array::view sub = owner.view()["v"].get_array().value;
+
+    ASSERT(sub[0].get_int32().value == 1);
+    ASSERT(sub[1].get_int32().value == 2);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/json_sub_document.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_sub_document.cpp
new file mode 100644
index 0000000000..3296d7c2c0
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_sub_document.cpp
@@ -0,0 +1,42 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value doc = bsoncxx::from_json(R"(
+        {
+            "v": {"key": "value"}
+        }
+    )");
+    bsoncxx::document::view v = doc["v"].get_document().value;
+
+    ASSERT(v["key"].get_string().value.compare("value") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/create_doc/json_udl.cpp b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_udl.cpp
new file mode 100644
index 0000000000..28753a48fd
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/create_doc/json_udl.cpp
@@ -0,0 +1,38 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/json.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using namespace bsoncxx;
+
+    bsoncxx::document::value a = R"({"key": "value"})"_bson;
+    bsoncxx::document::value b = bsoncxx::from_json(R"({"key": "value"})");
+
+    ASSERT(a == b);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/elements/arr_multi.cpp b/examples/api/bsoncxx/examples/bson_documents/elements/arr_multi.cpp
new file mode 100644
index 0000000000..1008a846ff
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/elements/arr_multi.cpp
@@ -0,0 +1,71 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2.0, "three"]
+void example(bsoncxx::array::element e) {
+    switch (e.type()) {
+        case bsoncxx::type::k_int32: {
+            ASSERT(e.key().compare("0") == 0);
+
+            bsoncxx::types::b_int32 v = e.get_int32();
+
+            ASSERT(v.type_id == bsoncxx::type::k_int32);
+            ASSERT(v.value == 1);
+
+            break;
+        }
+        case bsoncxx::type::k_double: {
+            ASSERT(e.key().compare("1") == 0);
+
+            bsoncxx::types::b_double v = e.get_double();
+
+            ASSERT(v.type_id == bsoncxx::type::k_double);
+            ASSERT(v.value == 2.0);
+
+            break;
+        }
+        case bsoncxx::type::k_string: {
+            ASSERT(e.key().compare("2") == 0);
+
+            bsoncxx::types::b_string v = e.get_string();
+
+            ASSERT(v.type_id == bsoncxx::type::k_string);
+            ASSERT(v.value.compare("three") == 0);
+
+            break;
+        }
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    const auto doc = bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})");
+    const auto arr = doc["v"].get_array().value;
+
+    example(arr[0]);
+    example(arr[1]);
+    example(arr[2]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/elements/arr_single.cpp b/examples/api/bsoncxx/examples/bson_documents/elements/arr_single.cpp
new file mode 100644
index 0000000000..fce3eb4b4c
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/elements/arr_single.cpp
@@ -0,0 +1,49 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2.0, "three"]
+void example(bsoncxx::array::element e) {
+    if (e.type() == bsoncxx::type::k_int32) {
+        ASSERT(e.key().compare("0") == 0);
+
+        bsoncxx::types::b_int32 v = e.get_int32();
+
+        ASSERT(v.type_id == bsoncxx::type::k_int32);
+        ASSERT(v.value == 1);
+    } else {
+        ASSERT(e.key().compare("0") != 0);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    const auto doc = bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})");
+    const auto arr = doc["v"].get_array().value;
+
+    example(arr[0]);
+    example(arr[1]);
+    example(arr[2]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/elements/cmp_bson_value.cpp b/examples/api/bsoncxx/examples/bson_documents/elements/cmp_bson_value.cpp
new file mode 100644
index 0000000000..44c2d9dba6
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/elements/cmp_bson_value.cpp
@@ -0,0 +1,55 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": {"$numberInt": "1"}, "b": {"$numberLong": "2"}}
+void example(bsoncxx::document::element e) {
+    bsoncxx::types::b_int32 a{1};
+    bsoncxx::types::b_int64 b{2};
+
+    if (e.get_value() == a) {
+        ASSERT(e.key().compare("a") == 0);
+    } else if (e.get_value() == b) {
+        ASSERT(e.key().compare("b") == 0);
+    }
+
+    bsoncxx::types::bson_value::view va{a};
+    bsoncxx::types::bson_value::view vb{b};
+
+    if (e == va) {
+        ASSERT(e.key().compare("a") == 0);
+    } else if (e == vb) {
+        ASSERT(e.key().compare("b") == 0);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    const auto doc = bsoncxx::from_json(R"({"a": {"$numberInt": "1"}, "b": {"$numberLong": "2"}})");
+
+    example(doc["a"]);
+    example(doc["b"]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/elements/cmp_type.cpp b/examples/api/bsoncxx/examples/bson_documents/elements/cmp_type.cpp
new file mode 100644
index 0000000000..29c7a0b1ea
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/elements/cmp_type.cpp
@@ -0,0 +1,49 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": {"$numberInt": "1"}, "b": {"$numberLong": "2"}}
+void example(bsoncxx::document::element e) {
+    std::int32_t a{1};
+    std::int64_t b{2};
+
+    if (e.type() == bsoncxx::type::k_int32) {
+        ASSERT(e.key().compare("a") == 0);
+        ASSERT(e.get_int32().value == a);
+    } else if (e.type() == bsoncxx::type::k_int64) {
+        ASSERT(e.key().compare("b") == 0);
+        ASSERT(e.get_int64().value == b);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    const auto doc = bsoncxx::from_json(R"({"a": {"$numberInt": "1"}, "b": {"$numberLong": "2"}})");
+
+    example(doc["a"]);
+    example(doc["b"]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/elements/doc_multi.cpp b/examples/api/bsoncxx/examples/bson_documents/elements/doc_multi.cpp
new file mode 100644
index 0000000000..fe5c323736
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/elements/doc_multi.cpp
@@ -0,0 +1,70 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2.0, "c": "three"}
+void example(bsoncxx::document::element e) {
+    switch (e.type()) {
+        case bsoncxx::type::k_int32: {
+            ASSERT(e.key().compare("a") == 0);
+
+            bsoncxx::types::b_int32 v = e.get_int32();
+
+            ASSERT(v.type_id == bsoncxx::type::k_int32);
+            ASSERT(v.value == 1);
+
+            break;
+        }
+        case bsoncxx::type::k_double: {
+            ASSERT(e.key().compare("b") == 0);
+
+            bsoncxx::types::b_double v = e.get_double();
+
+            ASSERT(v.type_id == bsoncxx::type::k_double);
+            ASSERT(v.value == 2.0);
+
+            break;
+        }
+        case bsoncxx::type::k_string: {
+            ASSERT(e.key().compare("c") == 0);
+
+            bsoncxx::types::b_string v = e.get_string();
+
+            ASSERT(v.type_id == bsoncxx::type::k_string);
+            ASSERT(v.value.compare("three") == 0);
+
+            break;
+        }
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    const auto doc = bsoncxx::from_json(R"({"a": 1, "b": 2.0, "c": "three"})");
+
+    example(doc["a"]);
+    example(doc["b"]);
+    example(doc["c"]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/elements/doc_single.cpp b/examples/api/bsoncxx/examples/bson_documents/elements/doc_single.cpp
new file mode 100644
index 0000000000..c8bf3ac940
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/elements/doc_single.cpp
@@ -0,0 +1,48 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2.0, "c": "three"}
+void example(bsoncxx::document::element e) {
+    if (e.type() == bsoncxx::type::k_int32) {
+        ASSERT(e.key().compare("a") == 0);
+
+        bsoncxx::types::b_int32 v = e.get_int32();
+
+        ASSERT(v.type_id == bsoncxx::type::k_int32);
+        ASSERT(v.value == 1);
+    } else {
+        ASSERT(e.key().compare("a") != 0);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    const auto doc = bsoncxx::from_json(R"({"a": 1, "b": 2.0, "c": "three"})");
+
+    example(doc["a"]);
+    example(doc["b"]);
+    example(doc["c"]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/json/array.cpp b/examples/api/bsoncxx/examples/bson_documents/json/array.cpp
new file mode 100644
index 0000000000..f74104ecb4
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/json/array.cpp
@@ -0,0 +1,105 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+#include <string>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::ExtendedJsonMode;
+
+    std::uint8_t data[]{"three"};  // Base64: dGhyZWU=
+    std::uint32_t data_len{5u};    // Exclude null terminator.
+    bsoncxx::types::b_binary binary{bsoncxx::binary_sub_type::k_binary, data_len, data};
+
+    bsoncxx::array::value owner = bsoncxx::builder::basic::make_array(
+        std::int32_t{1},  // "$numberInt": "1"
+        std::int64_t{2},  // "$numberLong": "2"
+        binary            // "$binary": { "$base64": "dGhyZWU=", "subType": 00 }
+    );
+    bsoncxx::array::view arr = owner.view();
+
+    {
+        // Canonical Extended JSON:
+        // [
+        //     { "$numberInt": "1" },
+        //     { "$numberLong": "2" },
+        //     {
+        //         "$binary": {
+        //             "base64": "dGhyZWU=",
+        //             "subType": "00"
+        //         }
+        //     }
+        // ]
+        std::string json = bsoncxx::to_json(arr, ExtendedJsonMode::k_canonical);
+        ASSERT(
+            json ==
+            R"([ { "$numberInt" : "1" }, { "$numberLong" : "2" }, { "$binary" : { "base64" : "dGhyZWU=", "subType" : "00" } } ])");
+    }
+
+    {
+        // Relaxed Extended JSON
+        // [
+        //     1,
+        //     2,
+        //     {
+        //         "$binary": {
+        //             "base64": "dGhyZWU=",
+        //             "subType": "00"
+        //         }
+        //     }
+        // ]
+        std::string json = bsoncxx::to_json(arr, ExtendedJsonMode::k_relaxed);
+        ASSERT(json == R"([ 1, 2, { "$binary" : { "base64" : "dGhyZWU=", "subType" : "00" } } ])");
+    }
+
+    {
+        // Legacy Extended JSON
+        // [
+        //     1,
+        //     2,
+        //     {
+        //         "$binary": "dGhyZWU=",
+        //         "$type": "00"
+        //     }
+        // ]
+        std::string json = bsoncxx::to_json(arr);
+        ASSERT(json == R"([ 1, 2, { "$binary" : "dGhyZWU=", "$type" : "00" } ])");
+    }
+
+    {
+        std::string a = bsoncxx::to_json(arr);
+        std::string b = bsoncxx::to_json(arr, ExtendedJsonMode::k_legacy);
+
+        ASSERT(a == b);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/json/document.cpp b/examples/api/bsoncxx/examples/bson_documents/json/document.cpp
new file mode 100644
index 0000000000..d7055e6a98
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/json/document.cpp
@@ -0,0 +1,109 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+#include <string>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::ExtendedJsonMode;
+    using bsoncxx::builder::basic::kvp;
+
+    std::uint8_t data[]{"three"};                                   // Base64: dGhyZWU=
+    auto data_len = static_cast<std::uint32_t>(sizeof(data) - 1u);  // Exclude null terminator.
+    bsoncxx::types::b_binary binary{bsoncxx::binary_sub_type::k_binary, data_len, data};
+
+    bsoncxx::document::value owner = bsoncxx::builder::basic::make_document(
+        kvp("a", std::int32_t{1}),  // "$numberInt": "1"
+        kvp("b", std::int64_t{2}),  // "$numberLong": "2"
+        kvp("c", binary)            // "$binary": { "$base64": "dGhyZWU=", "subType": 00 }
+    );
+    bsoncxx::document::view doc = owner.view();
+
+    {
+        // Canonical Extended JSON:
+        // {
+        //     "a": { "$numberInt": "1" },
+        //     "b": { "$numberLong": "2" },
+        //     "c": {
+        //         "$binary": {
+        //             "base64": "dGhyZWU=",
+        //             "subType": "00"
+        //         }
+        //     }
+        // }
+        std::string json = bsoncxx::to_json(doc, ExtendedJsonMode::k_canonical);
+        ASSERT(
+            json ==
+            R"({ "a" : { "$numberInt" : "1" }, "b" : { "$numberLong" : "2" }, "c" : { "$binary" : { "base64" : "dGhyZWU=", "subType" : "00" } } })");
+    }
+
+    {
+        // Relaxed Extended JSON
+        // {
+        //     "a": 1,
+        //     "b": 2,
+        //     "c": {
+        //         "$binary": {
+        //             "base64": "dGhyZWU=",
+        //             "subType": "00"
+        //         }
+        //     }
+        // }
+        std::string json = bsoncxx::to_json(doc, ExtendedJsonMode::k_relaxed);
+        ASSERT(
+            json ==
+            R"({ "a" : 1, "b" : 2, "c" : { "$binary" : { "base64" : "dGhyZWU=", "subType" : "00" } } })");
+    }
+
+    {
+        // Legacy Extended JSON
+        // {
+        //     "a": 1,
+        //     "b": 2,
+        //     "c": {
+        //         "$binary": "dGhyZWU=",
+        //         "$type": "00"
+        //     }
+        // }
+        std::string json = bsoncxx::to_json(doc);
+        ASSERT(json == R"({ "a" : 1, "b" : 2, "c" : { "$binary" : "dGhyZWU=", "$type" : "00" } })");
+    }
+
+    {
+        std::string a = bsoncxx::to_json(doc);
+        std::string b = bsoncxx::to_json(doc, ExtendedJsonMode::k_legacy);
+
+        ASSERT(a == b);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/values/arr_value.cpp b/examples/api/bsoncxx/examples/bson_documents/values/arr_value.cpp
new file mode 100644
index 0000000000..979bb557a0
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/values/arr_value.cpp
@@ -0,0 +1,48 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/value.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::types::bson_value::value v = nullptr;
+
+    ASSERT(v.view().type() == bsoncxx::type::k_null);
+    ASSERT(v.view().get_null() == bsoncxx::types::b_null{});
+
+    v = bsoncxx::from_json(R"({"v": ["value"]})")  // Temporary object.
+            ["v"]
+                .get_owning_value();  // Copy: no dangling.
+
+    ASSERT(v.view().type() == bsoncxx::type::k_array);
+
+    v = v.view().get_array().value[0].get_string();  // Copy: no dangling.
+
+    ASSERT(v.view().type() == bsoncxx::type::k_string);
+    ASSERT(v.view().get_string().value.compare("value") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/values/arr_view.cpp b/examples/api/bsoncxx/examples/bson_documents/values/arr_view.cpp
new file mode 100644
index 0000000000..5af43844fc
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/values/arr_view.cpp
@@ -0,0 +1,57 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2.0, "three"]
+void example(bsoncxx::array::element e) {
+    bsoncxx::types::bson_value::view v = e.get_value();
+    ASSERT(v.type() == e.type());
+
+    switch (v.type()) {
+        case bsoncxx::type::k_int32:
+            ASSERT(e.key().compare("0") == 0);
+            ASSERT(v.get_int32() == e.get_int32());
+            break;
+        case bsoncxx::type::k_double:
+            ASSERT(e.key().compare("1") == 0);
+            ASSERT(v.get_double() == e.get_double());
+            break;
+        case bsoncxx::type::k_string:
+            ASSERT(e.key().compare("2") == 0);
+            ASSERT(v.get_string() == e.get_string());
+            break;
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    const auto doc = bsoncxx::from_json(R"({"v": [1, 2.0, "three"]})");
+    const auto arr = doc["v"].get_array().value;
+
+    example(arr[0]);
+    example(arr[1]);
+    example(arr[2]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/values/bson_type_value.cpp b/examples/api/bsoncxx/examples/bson_documents/values/bson_type_value.cpp
new file mode 100644
index 0000000000..51ce072c61
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/values/bson_type_value.cpp
@@ -0,0 +1,48 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/value.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::types::bson_value::value v = nullptr;
+
+    ASSERT(v.view().type() == bsoncxx::type::k_null);
+    ASSERT(v.view().get_null() == bsoncxx::types::b_null{});
+
+    v = bsoncxx::types::b_int32{1};
+    ASSERT(v.view().type() == bsoncxx::type::k_int32);
+    ASSERT(v.view().get_int32().value == 1);
+
+    v = bsoncxx::types::b_double{2.0};
+    ASSERT(v.view().type() == bsoncxx::type::k_double);
+    ASSERT(v.view().get_double().value == 2.0);
+
+    v = bsoncxx::types::b_string{"three"};
+    ASSERT(v.view().type() == bsoncxx::type::k_string);
+    ASSERT(v.view().get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/values/bson_type_view.cpp b/examples/api/bsoncxx/examples/bson_documents/values/bson_type_view.cpp
new file mode 100644
index 0000000000..1d66ac44ee
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/values/bson_type_view.cpp
@@ -0,0 +1,53 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using view_type = bsoncxx::types::bson_value::view;
+
+    bsoncxx::types::b_int32 v0{1};
+    bsoncxx::types::b_double v1{2.0};
+    bsoncxx::types::b_string v2{"three"};
+
+    view_type v;
+    ASSERT(v.type() == bsoncxx::type::k_null);
+    ASSERT(v.get_null() == bsoncxx::types::b_null{});
+
+    v = view_type(v0);
+    ASSERT(v.type() == v0.type_id);
+    ASSERT(v.get_int32() == v0);
+
+    v = view_type(v1);
+    ASSERT(v.type() == v1.type_id);
+    ASSERT(v.get_double() == v1);
+
+    v = view_type(v2);
+    ASSERT(v.type() == v2.type_id);
+    ASSERT(v.get_string() == v2);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/values/doc_value.cpp b/examples/api/bsoncxx/examples/bson_documents/values/doc_value.cpp
new file mode 100644
index 0000000000..ead44f8128
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/values/doc_value.cpp
@@ -0,0 +1,48 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/value.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::types::bson_value::value v = nullptr;
+
+    ASSERT(v.view().type() == bsoncxx::type::k_null);
+    ASSERT(v.view().get_null() == bsoncxx::types::b_null{});
+
+    v = bsoncxx::from_json(R"({"v": {"key": "value"}})")  // Temporary object.
+            ["v"]
+                .get_owning_value();  // Copy: no dangling.
+
+    ASSERT(v.view().type() == bsoncxx::type::k_document);
+
+    v = v.view().get_document().value["key"].get_string();  // Copy: no dangling.
+
+    ASSERT(v.view().type() == bsoncxx::type::k_string);
+    ASSERT(v.view().get_string().value.compare("value") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/values/doc_view.cpp b/examples/api/bsoncxx/examples/bson_documents/values/doc_view.cpp
new file mode 100644
index 0000000000..362c233f38
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/values/doc_view.cpp
@@ -0,0 +1,56 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2.0, "c": "three"}
+void example(bsoncxx::document::element e) {
+    bsoncxx::types::bson_value::view v = e.get_value();
+    ASSERT(v.type() == e.type());
+
+    switch (v.type()) {
+        case bsoncxx::type::k_int32:
+            ASSERT(e.key().compare("a") == 0);
+            ASSERT(v.get_int32() == e.get_int32());
+            break;
+        case bsoncxx::type::k_double:
+            ASSERT(e.key().compare("b") == 0);
+            ASSERT(v.get_double() == e.get_double());
+            break;
+        case bsoncxx::type::k_string:
+            ASSERT(e.key().compare("c") == 0);
+            ASSERT(v.get_string() == e.get_string());
+            break;
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    const auto doc = bsoncxx::from_json(R"({"a": 1, "b": 2.0, "c": "three"})");
+
+    example(doc["a"]);
+    example(doc["b"]);
+    example(doc["c"]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/values/make_value.cpp b/examples/api/bsoncxx/examples/bson_documents/values/make_value.cpp
new file mode 100644
index 0000000000..f2837d5e42
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/values/make_value.cpp
@@ -0,0 +1,62 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <string>
+
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/make_value.hpp>
+#include <bsoncxx/types/bson_value/value.hpp>
+#include <bsoncxx/types/bson_value/view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using value_type = bsoncxx::types::bson_value::value;
+    using view_type = bsoncxx::types::bson_value::view;
+
+    {
+        value_type owner = bsoncxx::types::bson_value::make_value(1);
+        view_type v = owner.view();
+
+        ASSERT(v.type() == bsoncxx::type::k_int32);
+        ASSERT(v.get_int32().value == 1);
+    }
+
+    {
+        value_type owner = bsoncxx::types::bson_value::make_value(bsoncxx::types::b_int64{2});
+        view_type v = owner.view();
+
+        ASSERT(v.type() == bsoncxx::type::k_int64);
+        ASSERT(v.get_int64().value == 2);
+    }
+
+    {
+        value_type owner = bsoncxx::types::bson_value::make_value(std::string("three"));
+        view_type v = owner.view();
+
+        ASSERT(v.type() == bsoncxx::type::k_string);
+        ASSERT(v.get_string().value.compare("three") == 0);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_documents/values/value_type.cpp b/examples/api/bsoncxx/examples/bson_documents/values/value_type.cpp
new file mode 100644
index 0000000000..34f17aaa18
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_documents/values/value_type.cpp
@@ -0,0 +1,53 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <string>
+
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/value.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::types::bson_value::value v = nullptr;
+
+    ASSERT(v.view().type() == bsoncxx::type::k_null);
+    ASSERT(v.view().get_null() == bsoncxx::types::b_null{});
+
+    v = std::int32_t{1};
+
+    ASSERT(v.view().type() == bsoncxx::type::k_int32);
+    ASSERT(v.view().get_int32().value == 1);
+
+    v = 2.0;
+
+    ASSERT(v.view().type() == bsoncxx::type::k_double);
+    ASSERT(v.view().get_double().value == 2.0);
+
+    v = std::string("three");
+
+    ASSERT(v.view().type() == bsoncxx::type::k_string);
+    ASSERT(v.view().get_string().value.compare("three") == 0);
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/access_arr_iter_end.cpp b/examples/api/bsoncxx/examples/bson_errors/access_arr_iter_end.cpp
new file mode 100644
index 0000000000..a6d37f260e
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/access_arr_iter_end.cpp
@@ -0,0 +1,52 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2, 3]
+void example(bsoncxx::array::view arr) {
+    ASSERT(arr.begin() != arr.end());
+
+    auto iter = arr.begin();  // 1
+
+    ++iter;  // 2
+    ++iter;  // 3
+    ++iter;  // End iterator.
+
+    ASSERT(iter == arr.end());
+
+    ++iter;  // DO NOT DO THIS
+
+    ASSERT(iter == arr.end());  // Incrementing an end iterator results in an end iterator.
+
+    bsoncxx::array::element e = *iter;  // DO NOT DO THIS
+
+    ASSERT(!e);  // An end iterator returns an invalid element.
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"v": [1, 2, 3]})")["v"].get_array().value);
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/access_arr_iter_invalid.cpp b/examples/api/bsoncxx/examples/bson_errors/access_arr_iter_invalid.cpp
new file mode 100644
index 0000000000..92d5ef7f24
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/access_arr_iter_invalid.cpp
@@ -0,0 +1,49 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/json.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::array::value::deleter_type deleter = [](std::uint8_t*) {};
+    std::uint8_t data[] = {0u};  // An invalid BSON array.
+
+    bsoncxx::array::value owner{data, sizeof(data), deleter};
+    bsoncxx::array::view arr = owner.view();
+
+    auto iter = arr.begin();
+
+    ASSERT(iter == arr.end());  // An invalid BSON document returns an end iterator.
+
+    bsoncxx::array::element e = *iter;  // DO NOT DO THIS
+
+    ASSERT(!e);  // An end iterator returns an invalid element.
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/access_arr_key_missing.cpp b/examples/api/bsoncxx/examples/bson_errors/access_arr_key_missing.cpp
new file mode 100644
index 0000000000..99f8749e35
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/access_arr_key_missing.cpp
@@ -0,0 +1,42 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <algorithm>
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1, 2, 3]
+void example(bsoncxx::array::view arr) {
+    ASSERT(std::distance(arr.begin(), arr.end()) == 3);
+
+    bsoncxx::array::element e = arr[3];
+
+    ASSERT(!e);  // A missing element is represented as an invalid element.
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"v": [1, 2, 3]})")["v"].get_array().value);
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/access_doc_iter_end.cpp b/examples/api/bsoncxx/examples/bson_errors/access_doc_iter_end.cpp
new file mode 100644
index 0000000000..27f235a654
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/access_doc_iter_end.cpp
@@ -0,0 +1,51 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2}
+void example(bsoncxx::document::view doc) {
+    ASSERT(doc.begin() != doc.end());
+
+    auto iter = doc.begin();  // "a": 1
+
+    ++iter;  // "b": 2
+    ++iter;  // End iterator.
+
+    ASSERT(iter == doc.end());
+
+    ++iter;  // DO NOT DO THIS
+
+    ASSERT(iter == doc.end());  // Incrementing an end iterator results in an end iterator.
+
+    bsoncxx::document::element e = *iter;  // DO NOT DO THIS
+
+    ASSERT(!e);  // An end iterator returns an invalid element.
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"a": 1, "b": 2})"));
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/access_doc_iter_invalid.cpp b/examples/api/bsoncxx/examples/bson_errors/access_doc_iter_invalid.cpp
new file mode 100644
index 0000000000..5079e48ee1
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/access_doc_iter_invalid.cpp
@@ -0,0 +1,50 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value::deleter_type deleter = [](std::uint8_t*) {};
+    std::uint8_t data[] = {0u};  // An invalid BSON document.
+
+    bsoncxx::document::value owner{data, sizeof(data), deleter};
+    bsoncxx::document::view doc = owner.view();
+
+    auto iter = doc.begin();
+
+    ASSERT(iter == doc.end());  // An invalid BSON document returns an end iterator.
+
+    bsoncxx::document::element e = *iter;  // DO NOT DO THIS
+
+    ASSERT(!e);  // An end iterator returns an invalid element.
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/access_doc_key_missing.cpp b/examples/api/bsoncxx/examples/bson_errors/access_doc_key_missing.cpp
new file mode 100644
index 0000000000..e7a3db6268
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/access_doc_key_missing.cpp
@@ -0,0 +1,41 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"a": 1, "b": 2}
+void example(bsoncxx::document::view doc) {
+    ASSERT(doc["a"]);
+    ASSERT(doc["b"]);
+
+    bsoncxx::document::element e = doc["c"];
+
+    ASSERT(!e);  // A missing element is represented as an invalid element.
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"a": 1, "b": 2})"));
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/big_string.hh b/examples/api/bsoncxx/examples/bson_errors/big_string.hh
new file mode 100644
index 0000000000..f97e4b6060
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/big_string.hh
@@ -0,0 +1,41 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+#include <memory>
+
+#include <bsoncxx/stdx/string_view.hpp>
+
+namespace examples {
+
+// Used to trigger builder append failure.
+struct big_string {
+    // BSON_SIZE_MAX == 0x7FFFFFFF
+    std::size_t length{static_cast<std::size_t>(std::numeric_limits<std::int32_t>::max())};
+
+    // Allocate an UNINITIALIZED blob of data that will not be accessed due to length checks.
+    // Leaving memory unitialized (rather than zero-init) should hopefully avoid slow and expensive
+    // physical memory allocation at runtime.
+    std::unique_ptr<char[]> data{new char[length]};
+
+    bsoncxx::stdx::string_view view() const {
+        return bsoncxx::stdx::string_view(data.get(), length);
+    }
+};
+
+}  // namespace examples
diff --git a/examples/api/bsoncxx/examples/bson_errors/create_arr_append.cpp b/examples/api/bsoncxx/examples/bson_errors/create_arr_append.cpp
new file mode 100644
index 0000000000..48e2be60f6
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/create_arr_append.cpp
@@ -0,0 +1,56 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "big_string.hh"
+
+//
+
+#include <cstddef>
+#include <limits>
+#include <memory>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/stdx/string_view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example(bsoncxx::stdx::string_view big_string) {
+    bsoncxx::builder::basic::array builder;
+    builder.append("element");
+    bsoncxx::array::value original{builder.view()};
+
+    try {
+        builder.append(big_string);  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_cannot_append_string);
+    }
+
+    ASSERT(builder.view() == original.view());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(examples::big_string().view());
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/create_arr_append_sub_array.cpp b/examples/api/bsoncxx/examples/bson_errors/create_arr_append_sub_array.cpp
new file mode 100644
index 0000000000..7f8c019919
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/create_arr_append_sub_array.cpp
@@ -0,0 +1,74 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "big_string.hh"
+
+//
+
+#include <cstddef>
+#include <limits>
+#include <memory>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/stdx/string_view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example(bsoncxx::stdx::string_view big_string) {
+    bsoncxx::builder::basic::array builder;
+    builder.append("element");
+    bsoncxx::array::value original{builder.view()};  // Copy of current state.
+
+    try {
+        builder.append([&](bsoncxx::builder::basic::sub_array arr) {
+            arr.append(big_string);  // Throws.
+        });
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_cannot_append_string);
+    }
+
+    // Builder is in an erroneous state.
+    try {
+        builder.view();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_unmatched_key_in_builder);
+    }
+
+    // Reset builder to a usable state.
+    builder.clear();
+    ASSERT(builder.view().empty());
+
+    // Restore the original state prior to the append failure.
+    builder.append(bsoncxx::builder::concatenate_array{original.view()});
+
+    ASSERT(builder.view() == original.view());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(examples::big_string().view());
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/create_arr_append_sub_document.cpp b/examples/api/bsoncxx/examples/bson_errors/create_arr_append_sub_document.cpp
new file mode 100644
index 0000000000..acc2ddb3d1
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/create_arr_append_sub_document.cpp
@@ -0,0 +1,77 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "big_string.hh"
+
+//
+
+#include <cstddef>
+#include <limits>
+#include <memory>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/builder/basic/array.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/stdx/string_view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example(bsoncxx::stdx::string_view big_string) {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::builder::basic::array builder;
+    builder.append("element");
+    bsoncxx::array::value original{builder.view()};  // Copy of current state.
+
+    try {
+        builder.append([&](bsoncxx::builder::basic::sub_document doc) {
+            doc.append(kvp("too big", big_string));  // Throws.
+        });
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_cannot_append_string);
+    }
+
+    // Builder is in an erroneous state.
+    try {
+        builder.view();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_unmatched_key_in_builder);
+    }
+
+    // Reset builder to a usable state.
+    builder.clear();
+    ASSERT(builder.view().empty());
+
+    // Restore the original state prior to the append failure.
+    builder.append(bsoncxx::builder::concatenate_array{original.view()});
+
+    ASSERT(builder.view() == original.view());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(examples::big_string().view());
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/create_bson_value_invalid_element.cpp b/examples/api/bsoncxx/examples/bson_errors/create_bson_value_invalid_element.cpp
new file mode 100644
index 0000000000..b47eac9c3a
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/create_bson_value_invalid_element.cpp
@@ -0,0 +1,42 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/value.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    try {
+        bsoncxx::document::element e;
+        bsoncxx::types::bson_value::view v = e.get_value();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_unset_element);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/create_bson_value_invalid_type.cpp b/examples/api/bsoncxx/examples/bson_errors/create_bson_value_invalid_type.cpp
new file mode 100644
index 0000000000..c02b75331d
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/create_bson_value_invalid_type.cpp
@@ -0,0 +1,41 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/value.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    try {
+        bsoncxx::types::bson_value::value value{bsoncxx::type::k_null};  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_invalid_bson_type_id);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/create_doc_append.cpp b/examples/api/bsoncxx/examples/bson_errors/create_doc_append.cpp
new file mode 100644
index 0000000000..cd97ea327b
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/create_doc_append.cpp
@@ -0,0 +1,59 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "big_string.hh"
+
+//
+
+#include <cstddef>
+#include <limits>
+#include <memory>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/stdx/string_view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example(bsoncxx::stdx::string_view big_string) {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::builder::basic::document builder;
+    builder.append(kvp("key", "value"));
+    bsoncxx::document::value original{builder.view()};
+
+    try {
+        builder.append(kvp("too big", big_string));  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_cannot_append_string);
+    }
+
+    ASSERT(builder.view() == original.view());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(examples::big_string().view());
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/create_doc_append_sub_array.cpp b/examples/api/bsoncxx/examples/bson_errors/create_doc_append_sub_array.cpp
new file mode 100644
index 0000000000..8e5ea16e21
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/create_doc_append_sub_array.cpp
@@ -0,0 +1,79 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "big_string.hh"
+
+//
+
+#include <cstddef>
+#include <limits>
+#include <memory>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/builder/basic/sub_array.hpp>
+#include <bsoncxx/builder/concatenate.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/stdx/string_view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example(bsoncxx::stdx::string_view big_string) {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::builder::basic::document builder;
+    builder.append(kvp("key", "value"));
+    bsoncxx::document::value original{builder.view()};  // Copy of current state.
+
+    try {
+        builder.append(kvp("bad", [&](bsoncxx::builder::basic::sub_array arr) {
+            arr.append(big_string);  // Throws.
+        }));
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_cannot_append_string);
+    }
+
+    // Builder is in an erroneous state.
+    try {
+        builder.view();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_unmatched_key_in_builder);
+    }
+
+    // Reset builder to a usable state.
+    builder.clear();
+    ASSERT(builder.view().empty());
+
+    // Restore the original state prior to the append failure.
+    builder.append(bsoncxx::builder::concatenate_doc{original.view()});
+
+    ASSERT(builder.view() == original.view());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(examples::big_string().view());
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/create_doc_append_sub_document.cpp b/examples/api/bsoncxx/examples/bson_errors/create_doc_append_sub_document.cpp
new file mode 100644
index 0000000000..e45ebb5cd0
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/create_doc_append_sub_document.cpp
@@ -0,0 +1,78 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "big_string.hh"
+
+//
+
+#include <cstddef>
+#include <limits>
+#include <memory>
+
+#include <bsoncxx/builder/basic/document.hpp>
+#include <bsoncxx/builder/basic/kvp.hpp>
+#include <bsoncxx/builder/concatenate.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/stdx/string_view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example(bsoncxx::stdx::string_view big_string) {
+    using bsoncxx::builder::basic::kvp;
+
+    bsoncxx::builder::basic::document builder;
+    builder.append(kvp("key", "value"));
+    bsoncxx::document::value original{builder.view()};  // Copy of current state.
+
+    try {
+        builder.append(kvp("bad", [&](bsoncxx::builder::basic::sub_document doc) {
+            doc.append(kvp("too big", big_string));  // Throws.
+        }));
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_cannot_append_string);
+    }
+
+    // Builder is in an erroneous state.
+    try {
+        builder.view();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_unmatched_key_in_builder);
+    }
+
+    // Reset builder to a usable state.
+    builder.clear();
+    ASSERT(builder.view().empty());
+
+    // Restore the original state prior to the append failure.
+    builder.append(bsoncxx::builder::concatenate_doc{original.view()});
+
+    ASSERT(builder.view() == original.view());
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(examples::big_string().view());
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/create_json.cpp b/examples/api/bsoncxx/examples/bson_errors/create_json.cpp
new file mode 100644
index 0000000000..3621351f5e
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/create_json.cpp
@@ -0,0 +1,40 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/json.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    try {
+        const auto doc = bsoncxx::from_json(R"(invalid json)");
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_json_parse_failure);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/query_bson_value_invalid_type.cpp b/examples/api/bsoncxx/examples/bson_errors/query_bson_value_invalid_type.cpp
new file mode 100644
index 0000000000..b89f67d7ab
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/query_bson_value_invalid_type.cpp
@@ -0,0 +1,53 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/types.hpp>
+#include <bsoncxx/types/bson_value/view.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::types::bson_value::view v;
+    ASSERT(v.type() == bsoncxx::type::k_null);
+    ASSERT(v.get_null() == bsoncxx::types::b_null{});
+
+    try {
+        bsoncxx::types::b_int32 i = v.get_int32();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_need_element_type_k_int32);
+    }
+
+    try {
+        bsoncxx::types::b_int64 i = v.get_int64();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_need_element_type_k_int64);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/query_element_arr_invalid.cpp b/examples/api/bsoncxx/examples/bson_errors/query_element_arr_invalid.cpp
new file mode 100644
index 0000000000..a1dd6a6af0
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/query_element_arr_invalid.cpp
@@ -0,0 +1,62 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::array::value::deleter_type deleter = [](std::uint8_t*) {};
+    std::uint8_t data[] = {0u};  // An invalid BSON array.
+
+    bsoncxx::array::value owner{data, sizeof(data), deleter};
+    bsoncxx::array::view arr = owner.view();
+
+    bsoncxx::array::element e = arr[0];
+
+    ASSERT(!e);  // An invalid BSON array returns an invalid element.
+
+    try {
+        bsoncxx::stdx::string_view key = e.key();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_unset_element);
+    }
+
+    try {
+        bsoncxx::type type = e.type();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_unset_element);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/query_element_arr_invalid_type.cpp b/examples/api/bsoncxx/examples/bson_errors/query_element_arr_invalid_type.cpp
new file mode 100644
index 0000000000..3ccb657a74
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/query_element_arr_invalid_type.cpp
@@ -0,0 +1,55 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/array/element.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// [1]
+void example(bsoncxx::array::element e) {
+    ASSERT(e.key().compare("0") == 0);
+    ASSERT(e.type() == bsoncxx::type::k_int32);
+    ASSERT(e.get_int32().value == 1);
+
+    try {
+        bsoncxx::types::b_double d = e.get_double();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_need_element_type_k_double);
+    }
+
+    try {
+        bsoncxx::types::b_string str = e.get_string();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_need_element_type_k_string);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example(bsoncxx::from_json(R"({"v": [1]})")["v"].get_array().value[0]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/query_element_doc_invalid.cpp b/examples/api/bsoncxx/examples/bson_errors/query_element_doc_invalid.cpp
new file mode 100644
index 0000000000..987e607833
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/query_element_doc_invalid.cpp
@@ -0,0 +1,65 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/stdx/string_view.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    bsoncxx::document::value::deleter_type deleter = [](std::uint8_t*) {};
+    std::uint8_t data[] = {0u};  // An invalid BSON document.
+
+    bsoncxx::document::value owner{data, sizeof(data), deleter};
+    bsoncxx::document::view doc = owner.view();
+
+    bsoncxx::document::element e = doc["x"];
+
+    ASSERT(!e);  // An invalid BSON document returns an invalid element.
+
+    try {
+        bsoncxx::stdx::string_view key = e.key();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_unset_element);
+    }
+
+    try {
+        bsoncxx::type type = e.type();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_unset_element);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/query_element_doc_invalid_type.cpp b/examples/api/bsoncxx/examples/bson_errors/query_element_doc_invalid_type.cpp
new file mode 100644
index 0000000000..58b8abd72e
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/query_element_doc_invalid_type.cpp
@@ -0,0 +1,57 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/document/element.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {"x": 1}
+void example(bsoncxx::document::element e) {
+    ASSERT(e.key().compare("x") == 0);
+    ASSERT(e.type() == bsoncxx::type::k_int32);
+    ASSERT(e.get_int32().value == 1);
+
+    try {
+        bsoncxx::types::b_double d = e.get_double();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_need_element_type_k_double);
+    }
+
+    try {
+        bsoncxx::types::b_string str = e.get_string();  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_need_element_type_k_string);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    const auto doc = bsoncxx::from_json(R"({"x": 1})");
+
+    example(doc["x"]);
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/to_json_invalid_arr.cpp b/examples/api/bsoncxx/examples/bson_errors/to_json_invalid_arr.cpp
new file mode 100644
index 0000000000..afc36e1fd4
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/to_json_invalid_arr.cpp
@@ -0,0 +1,54 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+#include <string>
+
+#include <bsoncxx/array/value.hpp>
+#include <bsoncxx/array/view.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::ExtendedJsonMode;
+
+    bsoncxx::array::value::deleter_type deleter = [](std::uint8_t*) {};
+    std::uint8_t data[] = {0u};  // Invalid BSON array.
+
+    bsoncxx::array::value owner{data, sizeof(data), deleter};
+    bsoncxx::array::view doc = owner.view();
+
+    try {
+        std::string json = bsoncxx::to_json(doc);  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_failed_converting_bson_to_json);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/bson_errors/to_json_invalid_doc.cpp b/examples/api/bsoncxx/examples/bson_errors/to_json_invalid_doc.cpp
new file mode 100644
index 0000000000..85eee021a0
--- /dev/null
+++ b/examples/api/bsoncxx/examples/bson_errors/to_json_invalid_doc.cpp
@@ -0,0 +1,54 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+#include <string>
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/types.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using bsoncxx::ExtendedJsonMode;
+
+    bsoncxx::document::value::deleter_type deleter = [](std::uint8_t*) {};
+    std::uint8_t data[] = {0u};  // Invalid BSON document.
+
+    bsoncxx::document::value owner{data, sizeof(data), deleter};
+    bsoncxx::document::view doc = owner.view();
+
+    try {
+        std::string json = bsoncxx::to_json(doc);  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_failed_converting_bson_to_json);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/decimal128/basic_usage.cpp b/examples/api/bsoncxx/examples/decimal128/basic_usage.cpp
new file mode 100644
index 0000000000..db2ae6c899
--- /dev/null
+++ b/examples/api/bsoncxx/examples/decimal128/basic_usage.cpp
@@ -0,0 +1,104 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/decimal128.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using d128 = bsoncxx::decimal128;  // For brevity.
+
+    // Default ctor.
+    ASSERT(d128{}.to_string() == "0E-6176");
+
+    ASSERT(d128{"0"}.to_string() == "0");
+    ASSERT(d128{"12"}.to_string() == "12");
+    ASSERT(d128{"-76"}.to_string() == "-76");
+    ASSERT(d128{"12.70"}.to_string() == "12.70");
+    ASSERT(d128{"+0.003"}.to_string() == "0.003");
+    ASSERT(d128{"017."}.to_string() == "17");
+    ASSERT(d128{".5"}.to_string() == "0.5");
+    ASSERT(d128{"4E+9"}.to_string() == "4E+9");
+    ASSERT(d128{"0.73e-7"}.to_string() == "7.3E-8");
+    ASSERT(d128{"Inf"}.to_string() == "Infinity");
+    ASSERT(d128{"-infinity"}.to_string() == "-Infinity");
+    ASSERT(d128{"NaN"}.to_string() == "NaN");
+    // "NaN8275" is not a supported string representation.
+
+    ASSERT(d128{"123"}.to_string() == "123");
+    ASSERT(d128{"-123"}.to_string() == "-123");
+    ASSERT(d128{"1.23E+3"}.to_string() == "1.23E+3");
+    ASSERT(d128{"1.23E+5"}.to_string() == "1.23E+5");
+    ASSERT(d128{"12.3"}.to_string() == "12.3");
+    ASSERT(d128{"0.00123"}.to_string() == "0.00123");
+    ASSERT(d128{"1.23E-8"}.to_string() == "1.23E-8");
+    ASSERT(d128{"-1.23E-10"}.to_string() == "-1.23E-10");
+    ASSERT(d128{"0"}.to_string() == "0");
+    ASSERT(d128{"0.00"}.to_string() == "0.00");
+    ASSERT(d128{"0E+2"}.to_string() == "0E+2");
+    ASSERT(d128{"-0"}.to_string() == "-0");
+    ASSERT(d128{"0.000005"}.to_string() == "0.000005");
+    ASSERT(d128{"0.0000050"}.to_string() == "0.0000050");
+    ASSERT(d128{"5E-7"}.to_string() == "5E-7");
+    ASSERT(d128{"Infinity"}.to_string() == "Infinity");
+    ASSERT(d128{"-Infinity"}.to_string() == "-Infinity");
+    ASSERT(d128{"NaN"}.to_string() == "NaN");
+    // "NaN123" is not a supported string representation.
+    // "-sNaN" is not a supported string representation.
+
+    ASSERT(d128{"1.23E+3"}.to_string() == "1.23E+3");
+    ASSERT(d128{"123E+3"}.to_string() == "1.23E+5");
+    ASSERT(d128{"12.3E-9"}.to_string() == "1.23E-8");
+    ASSERT(d128{"-123E-12"}.to_string() == "-1.23E-10");
+    ASSERT(d128{"700E-9"}.to_string() == "7.00E-7");
+    ASSERT(d128{"70"}.to_string() == "70");
+    ASSERT(d128{"0.00E+3"}.to_string() == "0E+1");
+
+    ASSERT(d128{"0"}.to_string() == "0");
+    ASSERT(d128{"0.00"}.to_string() == "0.00");
+    ASSERT(d128{"123"}.to_string() == "123");
+    ASSERT(d128{"-123"}.to_string() == "-123");
+    ASSERT(d128{"1.23E3"}.to_string() == "1.23E+3");
+    ASSERT(d128{"1.23E+3"}.to_string() == "1.23E+3");
+    ASSERT(d128{"12.3E+7"}.to_string() == "1.23E+8");
+    ASSERT(d128{"12.0"}.to_string() == "12.0");
+    ASSERT(d128{"12.3"}.to_string() == "12.3");
+    ASSERT(d128{"0.00123"}.to_string() == "0.00123");
+    ASSERT(d128{"-1.23E-12"}.to_string() == "-1.23E-12");
+    ASSERT(d128{"1234.5E-4"}.to_string() == "0.12345");
+    ASSERT(d128{"-0"}.to_string() == "-0");
+    ASSERT(d128{"-0.00"}.to_string() == "-0.00");
+    ASSERT(d128{"0E+7"}.to_string() == "0E+7");
+    ASSERT(d128{"-0E-7"}.to_string() == "-0E-7");
+    ASSERT(d128{"inf"}.to_string() == "Infinity");
+    ASSERT(d128{"+inFiniTy"}.to_string() == "Infinity");
+    ASSERT(d128{"-Infinity"}.to_string() == "-Infinity");
+    ASSERT(d128{"NaN"}.to_string() == "NaN");
+    ASSERT(d128{"-NAN"}.to_string() == "NaN");
+    // "SNaN" is not a supported string representation.
+    // "Fred" is not a supported string representation.
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/decimal128/errors.cpp b/examples/api/bsoncxx/examples/decimal128/errors.cpp
new file mode 100644
index 0000000000..da6c1f24e0
--- /dev/null
+++ b/examples/api/bsoncxx/examples/decimal128/errors.cpp
@@ -0,0 +1,40 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/decimal128.hpp>
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    try {
+        bsoncxx::decimal128 d{"invalid"};  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_invalid_decimal128);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/decimal128/from_bytes.cpp b/examples/api/bsoncxx/examples/decimal128/from_bytes.cpp
new file mode 100644
index 0000000000..86f1ec0999
--- /dev/null
+++ b/examples/api/bsoncxx/examples/decimal128/from_bytes.cpp
@@ -0,0 +1,85 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstdint>
+
+#include <bsoncxx/decimal128.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    using d128 = bsoncxx::decimal128;  // For brevity.
+
+    // Default ctor.
+    ASSERT((d128{0u, 0u}) == d128{});
+
+    // [0,0,0]
+    ASSERT((d128{0x3040000000000000, 0x0000000000000000}) == d128{"0"});
+
+    // [1,0,0]
+    ASSERT((d128{0xb040000000000000, 0x0000000000000000}) == d128{"-0"});
+
+    // [0,0,1]
+    ASSERT((d128{0x3040000000000000, 0x0000000000000000}) == d128{"00E0"});
+
+    // [0,0,-1]
+    ASSERT((d128{0x303e000000000000, 0x0000000000000000}) == d128{"0.0E0"});
+
+    // [0,123,0]
+    ASSERT((d128{0x3040000000000000, 0x000000000000007b}) == d128{"123"});
+
+    // [1,123,0]
+    ASSERT((d128{0xb040000000000000, 0x000000000000007b}) == d128{"-123"});
+
+    // [0,123,1]
+    ASSERT((d128{0x3042000000000000, 0x000000000000007b}) == d128{"1.23E3"});
+
+    // [1,123,1]
+    ASSERT((d128{0xb042000000000000, 0x000000000000007b}) == d128{"-1.23E3"});
+
+    // [0,123,-1]
+    ASSERT((d128{0x303e000000000000, 0x000000000000007b}) == d128{"12.3"});
+
+    // [1,123,-1]
+    ASSERT((d128{0xb03e000000000000, 0x000000000000007b}) == d128{"-12.3"});
+
+    // [0,inf]
+    ASSERT((d128{0x7800000000000000, 0x0000000000000000}) == d128{"Infinity"});
+
+    // [1,inf]
+    ASSERT((d128{0xf800000000000000, 0x0000000000000000}) == d128{"-Infinity"});
+
+    // [0,qNaN]
+    ASSERT((d128{0x7c00000000000000, 0x0000000000000000}) == d128{"NaN"});
+
+    // [1,qNaN]: Negative NaN is string-represented as NaN.
+    ASSERT((d128{0xfc00000000000000, 0x0000000000000000}).to_string() == "NaN");
+
+    // [0,sNaN]: Signaling NaN is string-represented as NaN.
+    ASSERT((d128{0x7e00000000000000, 0x0000000000000000}).to_string() == "NaN");
+
+    // [1,sNaN]: Negative Signaling NaN is string-represented as NaN.
+    ASSERT((d128{0x7e00000000000000, 0x0000000000000000}).to_string() == "NaN");
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/oid/basic_usage.cpp b/examples/api/bsoncxx/examples/oid/basic_usage.cpp
new file mode 100644
index 0000000000..6599104d4c
--- /dev/null
+++ b/examples/api/bsoncxx/examples/oid/basic_usage.cpp
@@ -0,0 +1,84 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstring>
+#include <ctime>
+#include <string>
+
+#include <bsoncxx/oid.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    {
+        bsoncxx::oid a;
+        bsoncxx::oid b;
+
+        ASSERT(a != b);  // Random and unique per process.
+    }
+
+    {
+        char bytes[bsoncxx::oid::k_oid_length]{};
+
+        bsoncxx::oid oid{bytes, sizeof(bytes)};
+
+        {
+            std::time_t time = oid.get_time_t();
+            char str[sizeof("YYYY-MM-DD HH:MM:SS")];
+            ASSERT(std::strftime(str, sizeof(str), "%F %T", std::gmtime(&time)) ==
+                   sizeof(str) - 1u);
+            ASSERT(std::string(str) == "1970-01-01 00:00:00");
+        }
+
+        ASSERT(oid.bytes() != bytes);  // Seperate storage.
+        ASSERT(oid.size() == bsoncxx::oid::k_oid_length);
+        ASSERT(std::memcmp(bytes, oid.bytes(), oid.size()) == 0);
+
+        ASSERT(oid.to_string() == "000000000000000000000000");
+        ASSERT(oid == bsoncxx::oid{"000000000000000000000000"});
+    }
+
+    {
+        // Timestamp: 946771199 (0x386e94ff)
+        // Value:     286462997 (0x11131415)
+        // Counter:   2171427   (0x212223)
+        bsoncxx::oid oid{"386e94ff1112131415212223"};
+
+        {
+            std::time_t time = oid.get_time_t();
+            char str[sizeof("YYYY-MM-DD HH:MM:SS")];
+            ASSERT(std::strftime(str, sizeof(str), "%F %T", std::gmtime(&time)) ==
+                   sizeof(str) - 1u);
+            ASSERT(std::string(str) == "2000-01-01 23:59:59");
+        }
+
+        ASSERT(oid < bsoncxx::oid{"389622001112131415212223"});  // Timestamp: 2000-02-01 00:00:00
+        ASSERT(oid > bsoncxx::oid{"386d43801112131415212223"});  // Timestamp: 2000-01-01 00:00:00
+        ASSERT(oid < bsoncxx::oid{"386e94ffffffffffff212223"});  // Value: 1099511627775
+        ASSERT(oid > bsoncxx::oid{"386e94ff0000000000212223"});  // Value: 0
+        ASSERT(oid < bsoncxx::oid{"386e94ff1112131415ffffff"});  // Counter: 16777215
+        ASSERT(oid > bsoncxx::oid{"386e94ff1112131415000000"});  // Counter: 0
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/oid/errors.cpp b/examples/api/bsoncxx/examples/oid/errors.cpp
new file mode 100644
index 0000000000..856adcb182
--- /dev/null
+++ b/examples/api/bsoncxx/examples/oid/errors.cpp
@@ -0,0 +1,50 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <bsoncxx/exception/error_code.hpp>
+#include <bsoncxx/exception/exception.hpp>
+#include <bsoncxx/oid.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    try {
+        bsoncxx::oid oid{"invalid"};  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_invalid_oid);
+    }
+
+    try {
+        char bytes[1]{};
+
+        bsoncxx::oid oid{bytes, sizeof(bytes)};  // Throws.
+
+        ASSERT(false && "should not reach this point");
+    } catch (const bsoncxx::exception& ex) {
+        ASSERT(ex.code() == bsoncxx::error_code::k_invalid_oid);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/validation/basic_usage.cpp b/examples/api/bsoncxx/examples/validation/basic_usage.cpp
new file mode 100644
index 0000000000..41f3198cdd
--- /dev/null
+++ b/examples/api/bsoncxx/examples/validation/basic_usage.cpp
@@ -0,0 +1,75 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstddef>
+#include <cstdint>
+
+#include <bsoncxx/document/value.hpp>
+#include <bsoncxx/document/view.hpp>
+#include <bsoncxx/json.hpp>
+#include <bsoncxx/validate.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+void example() {
+    {
+        std::uint8_t bytes[1]{};  // Invalid.
+
+        ASSERT(!bsoncxx::validate(bytes, sizeof(bytes)));
+
+        std::size_t offset;
+
+        ASSERT(!bsoncxx::validate(bytes, sizeof(bytes), bsoncxx::validator{}, &offset));
+
+        // Set to `0` for an invalid BSON document.
+        ASSERT(offset == 0u);
+    }
+
+    bsoncxx::document::value owner = bsoncxx::from_json(R"({"x": 1})");
+    const std::uint8_t* data = owner.data();
+    const std::size_t length = owner.length();
+
+    {
+        auto doc_opt = bsoncxx::validate(data, length);
+        ASSERT(doc_opt);
+
+        bsoncxx::document::view doc = *doc_opt;
+
+        ASSERT(doc.data() == data);
+        ASSERT(doc.length() == length);
+        ASSERT(doc == owner.view());
+    }
+
+    {
+        bsoncxx::validator options;
+        std::size_t offset = 123u;
+
+        ASSERT(bsoncxx::validate(data, length) ==
+               bsoncxx::validate(data, length, options, &offset));
+
+        // Not set when valid.
+        ASSERT(offset == 123u);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    example();
+}
diff --git a/examples/api/bsoncxx/examples/validation/validator.cpp b/examples/api/bsoncxx/examples/validation/validator.cpp
new file mode 100644
index 0000000000..04ea221a0b
--- /dev/null
+++ b/examples/api/bsoncxx/examples/validation/validator.cpp
@@ -0,0 +1,120 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cstddef>
+
+#include <bsoncxx/validate.hpp>
+
+#include <examples/api/runner.hh>
+#include <examples/macros.hh>
+
+namespace {
+
+// [Example]
+// {
+//     "x": "a\0b",
+//     "a.b": 1,
+//     "v": {
+//         "$numberInt": "123"
+//     }
+// }
+void example(const std::uint8_t* bytes, std::size_t length) {
+    // Default options.
+    {
+        bsoncxx::validator options;
+        std::size_t offset;
+
+        ASSERT(bsoncxx::validate(bytes, length, options, &offset));
+    }
+
+    // Validate UTF-8 strings.
+    {
+        bsoncxx::validator options;
+        std::size_t offset;
+
+        options.check_utf8(true);
+
+        ASSERT(!bsoncxx::validate(bytes, length, options, &offset));
+
+        // Offset of `"x": "\0"` relative to start of the document.
+        ASSERT(offset == 4u);
+
+        options.check_utf8_allow_null(true);
+
+        ASSERT(bsoncxx::validate(bytes, length, options, &offset));
+    }
+
+    // Validate dot keys.
+    {
+        bsoncxx::validator options;
+        std::size_t offset;
+
+        options.check_dot_keys(true);
+
+        ASSERT(!bsoncxx::validate(bytes, length, options, &offset));
+
+        // Offset of `"a.b": 1` relative to start of the document.
+        ASSERT(offset == 15u);
+    }
+
+    // Validate dollar keys.
+    {
+        bsoncxx::validator options;
+        std::size_t offset;
+
+        options.check_dollar_keys(true);
+
+        ASSERT(!bsoncxx::validate(bytes, length, options, &offset));
+
+        // Offset of `"$numberInt": "123"` relative to start of the sub-document. (CDRIVER-5710)
+        ASSERT(offset == 4u);
+    }
+}
+// [Example]
+
+}  // namespace
+
+RUNNER_REGISTER_COMPONENT() {
+    // clang-format off
+    std::uint8_t bytes[] = {
+        // Total Bytes: 53
+        0x35, 0x00, 0x00, 0x00,
+            // Element: String (Offset: 4)
+            0x02,
+                0x78, 0x00,             // Key: "x"
+                0x04, 0x00, 0x00, 0x00, // Length: 4
+                0x61, 0x00, 0x62, 0x00, // Value: "a\0b"
+
+            // Element: Int32 (Offset: 15)
+            0x10,
+                0x61, 0x2e, 0x62, 0x00, // Key: "a.b"
+                0x01, 0x00, 0x00, 0x00, // Value: 1
+
+            // Element: Document (Offset: 24)
+            0x03,
+                0x76, 0x00,             // Key: "v"
+                0x19, 0x00, 0x00, 0x00, // Total Bytes: 25
+                    // Element: String (Offset: 31)
+                    0x02,
+                        // Key: "$numberInt"
+                        0x24, 0x6e, 0x75, 0x6d, 0x62, 0x65, 0x72, 0x49, 0x6e, 0x74, 0x00,
+                        0x04, 0x00, 0x00, 0x00, // Length: 4
+                        0x31, 0x32, 0x33, 0x00, // Value: "123"
+                0x00, // End of Document.
+        0x00, // End of Document.
+    };
+    // clang-format on
+
+    example(bytes, sizeof(bytes));
+}
diff --git a/examples/api/runner.cpp b/examples/api/runner.cpp
new file mode 100644
index 0000000000..abf80fa6c0
--- /dev/null
+++ b/examples/api/runner.cpp
@@ -0,0 +1,167 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Disable macro definition check: this is not a component.
+#define EXAMPLES_COMPONENT_NAME
+
+#include <examples/api/runner.hh>
+
+//
+
+#include <algorithm>
+#include <climits>
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <iostream>
+#include <queue>
+#include <random>
+#include <thread>
+#include <vector>
+
+#include <examples/macros.hh>
+
+namespace {
+
+class runner_type {
+   public:
+    using fn_type = void (*)();
+
+   private:
+    std::vector<fn_type> fns;
+    std::minstd_rand::result_type seed = 0u;
+    std::minstd_rand gen;
+    unsigned int jobs = 0;
+
+   public:
+    void add(fn_type fn) {
+        fns.push_back(fn);
+    }
+
+    void set_seed(std::minstd_rand::result_type seed) {
+        this->seed = seed;
+    }
+
+    void set_jobs(unsigned int jobs) {
+        if (jobs == 0u) {
+            this->jobs = std::thread::hardware_concurrency();
+        } else {
+            this->jobs = jobs;
+        }
+    }
+
+    int run() {
+        ASSERT(jobs > 0u);
+
+        std::cout << "seed: " << seed << std::endl;
+
+        gen.seed(seed);
+
+        // Prevent ordering dependencies across examples.
+        std::shuffle(fns.begin(), fns.end(), gen);
+
+        std::queue<std::thread> threads;
+
+        // Rudimentary job scheduler.
+        for (auto fn : fns) {
+            while (threads.size() >= jobs) {
+                threads.front().join();
+                threads.pop();
+            }
+
+            threads.emplace(fn);
+        }
+
+        while (!threads.empty()) {
+            threads.front().join();
+            threads.pop();
+        }
+
+        return 0;
+    }
+};
+
+runner_type runner;
+
+}  // namespace
+
+void runner_register_fn(void (*fn)()) {
+    runner.add(fn);
+}
+
+int EXAMPLES_CDECL main(int argc, char** argv) {
+    bool set_seed = false;
+    bool set_jobs = false;
+
+    // Simple command-line argument parser.
+    for (int i = 1; i < argc; ++i) {
+        // Permit using a custom seed for reproducibility.
+        if (strcmp(argv[i], "--seed") == 0) {
+            if (i + 1 >= argc) {
+                std::cerr << "missing argument to --seed" << std::endl;
+                return 1;
+            }
+
+            char* const seed_str = argv[++i];  // Next argument.
+            char* end = nullptr;
+
+            const auto seed =
+                static_cast<std::minstd_rand::result_type>(std::strtoul(seed_str, &end, 10));
+
+            if (static_cast<std::size_t>(end - seed_str) != std::strlen(seed_str)) {
+                std::cerr << "invalid seed string: " << seed_str << std::endl;
+                return 1;
+            }
+
+            runner.set_seed(seed);
+            set_seed = true;
+        }
+
+        if (strcmp(argv[i], "--jobs") == 0) {
+            if (i + 1 >= argc) {
+                std::cerr << "missing argument to --jobs" << std::endl;
+                return 1;
+            }
+
+            char* const jobs_str = argv[++i];  // Next argument.
+            char* end = nullptr;
+
+            const auto jobs = std::strtoul(jobs_str, &end, 10);
+
+            if (static_cast<std::size_t>(end - jobs_str) != std::strlen(jobs_str)) {
+                std::cerr << "invalid jobs string: " << jobs_str << std::endl;
+                return 1;
+            }
+
+            if (jobs >= UINT_MAX) {
+                std::cerr << "invalid jobs string (too large): " << jobs_str << std::endl;
+            }
+
+            runner.set_jobs(static_cast<unsigned int>(jobs));
+            set_jobs = true;
+        }
+    }
+
+    // Default: use a random seed.
+    if (!set_seed) {
+        runner.set_seed(static_cast<std::minstd_rand::result_type>(std::random_device()()));
+    }
+
+    // Default: request maximum job count.
+    if (!set_jobs) {
+        runner.set_jobs(0);
+    }
+
+    return runner.run();  // Return directly from forked processes.
+}
diff --git a/examples/api/runner.hh b/examples/api/runner.hh
new file mode 100644
index 0000000000..0d4a5d6811
--- /dev/null
+++ b/examples/api/runner.hh
@@ -0,0 +1,30 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <examples/macros.hh>
+
+void runner_register_fn(void (*fn)());
+
+// Defined by examples/CMakeLists.txt.
+#if !defined(EXAMPLES_COMPONENT_NAME)
+#error "EXAMPLES_COMPONENT_NAME is not defined!"
+#endif  // !defined(EXAMPLES_COMPONENT_NAME)
+
+#define RUNNER_REGISTER_COMPONENT()                                                         \
+    static void EXAMPLES_CONCAT(EXAMPLES_COMPONENT_NAME, _entry_point)(void);               \
+    static int EXAMPLES_CONCAT(EXAMPLES_COMPONENT_NAME, _registerator) =                    \
+        (::runner_register_fn(&EXAMPLES_CONCAT(EXAMPLES_COMPONENT_NAME, _entry_point)), 0); \
+    static void EXAMPLES_CONCAT(EXAMPLES_COMPONENT_NAME, _entry_point)(void)
diff --git a/examples/macros.hh b/examples/macros.hh
index 2b477ea889..f11b9e1f47 100644
--- a/examples/macros.hh
+++ b/examples/macros.hh
@@ -14,8 +14,24 @@
 
 #pragma once
 
+#include <cstdio>
+#include <cstdlib>
+
 #if defined(_MSC_VER)
 #define EXAMPLES_CDECL __cdecl
 #else
 #define EXAMPLES_CDECL
 #endif
+
+#define EXAMPLES_CONCAT(a, b) EXAMPLES_CONCAT_1(a, b)
+#define EXAMPLES_CONCAT_1(a, b) a##b
+
+// Unconditionally define `assert()` for examples.
+#define ASSERT(...)                                                                           \
+    if (!static_cast<bool>(__VA_ARGS__)) {                                                    \
+        std::printf(                                                                          \
+            "%s:%d: %s: assertion failed: %s\n", __FILE__, __LINE__, __func__, #__VA_ARGS__); \
+        std::fflush(stdout);                                                                  \
+        std::abort();                                                                         \
+    } else                                                                                    \
+        ((void)0)
diff --git a/src/bsoncxx/include/bsoncxx/doc.hpp b/src/bsoncxx/include/bsoncxx/doc.hpp
index 4d42d18b1d..d091ac0f79 100644
--- a/src/bsoncxx/include/bsoncxx/doc.hpp
+++ b/src/bsoncxx/include/bsoncxx/doc.hpp
@@ -88,3 +88,72 @@
 /// @namespace std
 /// The top-level namespace reserved for the C++ standard library.
 ///
+
+///
+/// @page topic-bsoncxx The bsoncxx Library
+/// @brief Topics relating to the bsoncxx library.
+/// @li @subpage topic-bsoncxx-examples
+/// @li @subpage topic-bsoncxx-about
+///
+
+///
+/// @page topic-bsoncxx-examples How-To Guides
+/// @brief Examples of how to use the bsoncxx library.
+/// @li @subpage topic-bsoncxx-examples-bson-documents
+/// @li @subpage topic-bsoncxx-examples-bson-errors
+/// @li @subpage topic-bsoncxx-examples-decimal128
+/// @li @subpage topic-bsoncxx-examples-oid
+/// @li @subpage topic-bsoncxx-examples-validation
+///
+
+///
+/// @page topic-bsoncxx-examples-bson-documents BSON Documents
+/// @brief How to create and use BSON documents.
+/// @tableofcontents
+/// @include{doc} api/bsoncxx/examples/bson_documents/create_doc.md
+/// @include{doc} api/bsoncxx/examples/bson_documents/create_array.md
+/// @include{doc} api/bsoncxx/examples/bson_documents/access_doc.md
+/// @include{doc} api/bsoncxx/examples/bson_documents/access_array.md
+/// @include{doc} api/bsoncxx/examples/bson_documents/elements.md
+/// @include{doc} api/bsoncxx/examples/bson_documents/values.md
+/// @include{doc} api/bsoncxx/examples/bson_documents/json.md
+///
+
+///
+/// @page topic-bsoncxx-examples-bson-errors BSON Error Handling
+/// @brief How to handle BSON document failures, errors, and exceptions.
+/// @tableofcontents
+/// @include{doc} api/bsoncxx/examples/bson_errors.md
+///
+
+///
+/// @page topic-bsoncxx-examples-decimal128 Decimal128
+/// @brief How to use Decimal128 interfaces.
+/// @tableofcontents
+/// @see @parblock
+/// @li [BSON Decimal128 Type Handling in Drivers (MongoDB
+/// Specifications)](https://specifications.readthedocs.io/en/latest/bson-decimal128/decimal128/)
+/// @li [Conversions (General Decimal Arithmetic
+/// Specification)](https://speleotrove.com/decimal/daconvs.html)
+/// @endparblock
+/// @include{doc} api/bsoncxx/examples/decimal128.md
+///
+
+///
+/// @page topic-bsoncxx-examples-oid ObjectID
+/// @brief How to use ObjectID (OID) interfaces.
+/// @tableofcontents
+/// @include{doc} api/bsoncxx/examples/oid.md
+///
+
+///
+/// @page topic-bsoncxx-examples-validation Validation
+/// @brief How to use BSON document validation interfaces.
+/// @tableofcontents
+/// @include{doc} api/bsoncxx/examples/validation.md
+///
+
+///
+/// @page topic-bsoncxx-about Explanation
+/// @brief Design decisions, history, and other technical details about the bsoncxx library.
+///
diff --git a/src/mongocxx/include/mongocxx/doc.hpp b/src/mongocxx/include/mongocxx/doc.hpp
index bf16832ead..5ea25b9f2d 100644
--- a/src/mongocxx/include/mongocxx/doc.hpp
+++ b/src/mongocxx/include/mongocxx/doc.hpp
@@ -84,3 +84,20 @@
 /// @warning These redeclarations are for internal use only! Users should reference entities
 /// declared in @ref bsoncxx directly, not through @ref mongocxx.
 ///
+
+///
+/// @page topic-mongocxx The mongocxx Library
+/// @brief Topics relating to the mongocxx library.
+/// @li @subpage topic-mongocxx-examples
+/// @li @subpage topic-mongocxx-about
+///
+
+///
+/// @page topic-mongocxx-examples How-To Guides
+/// @brief Examples of how to use the mongocxx library.
+///
+
+///
+/// @page topic-mongocxx-about Explanation
+/// @brief Design decisions, history, and other technical details about the mongocxx library.
+///