Document and test type_error.321 for discarded binary values

Add docs for the new exception (home/exceptions.md and the Exceptions
sections of to_cbor/to_msgpack/to_ubjson/to_bjdata/to_bson) and test
coverage for a discarded value nested in an array or object, nested
deeper, and (for UBJSON/BJData) inside an optimized same-type array,
for each of CBOR, MessagePack, UBJSON, BJData, and BSON. Adjust the
three pre-existing "discarded" tests that asserted the old silent
behavior (empty/short output) to expect type_error.321 instead.

Co-authored-by: ameliabarnabyhub <312084480+ameliabarnabyhub@users.noreply.github.com>
Signed-off-by: Niels Lohmann <mail@nlohmann.me>

.github/workflows/macos.yml

@@ -17,11 +17,11 @@ permissions:
   contents: read
 
 jobs:
-  macos-15:
-    runs-on: macos-15 # https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md
+  macos-14:
+    runs-on: macos-14 # https://github.com/actions/runner-images/blob/main/images/macos/macos-14-Readme.md
     strategy:
       matrix:
-        xcode: ['16.0', '16.1', '16.2', '16.3', '16.4', '26.0.1', '26.1.1', '26.2', '26.3']
+        xcode: ['15.0.1', '15.1', '15.2', '15.3', '15.4']
     env:
       DEVELOPER_DIR: /Applications/Xcode_${{ matrix.xcode }}.app/Contents/Developer
 
@@ -36,11 +36,11 @@ jobs:
       - name: Test
         run: cd build ; ctest -j 10 --output-on-failure
 
-  macos-26:
-    runs-on: macos-26 # https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md
+  macos-15:
+    runs-on: macos-15 # https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md
     strategy:
       matrix:
-        xcode: ['26.4.1', '26.5', '26.6']
+        xcode: ['16.0', '16.1', '16.2', '16.3', '16.4', '26.0.1']
     env:
       DEVELOPER_DIR: /Applications/Xcode_${{ matrix.xcode }}.app/Contents/Developer
 

.github/workflows/ubuntu.yml

@@ -209,7 +209,7 @@ jobs:
     strategy:
       matrix:
         # older GCC docker images (4, 5, 6) fail to check out code
-        compiler: ['7', '8', '9', '10', '11', '12', '13', '14', '15', '16', 'latest']
+        compiler: ['7', '8', '9', '10', '11', '12', '13', '14', '15', 'latest']
     container: gcc:${{ matrix.compiler }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

docs/mkdocs/docs/api/basic_json/to_bjdata.md

@@ -68,6 +68,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is
+  discarded; example: `"cannot serialize discarded value to BJData"`
 
 ## Complexity
 
@@ -119,4 +121,6 @@ Linear in the size of the JSON value `j`.
 - BJData version parameter (for draft3 binary encoding) added in version 3.12.0.
 - Added `error_handler` parameter in version 3.13.0. Its default, `keep`, writes the bytes of a string or object key
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
-  [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
+  [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
+- Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
+  array or object was silently skipped, producing invalid BJData.

docs/mkdocs/docs/api/basic_json/to_bson.md

@@ -58,6 +58,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if a value nested in `j` is discarded
+  (the top-level value itself is covered by `type_error.317` above, since it must be an object); example:
+  `"cannot serialize discarded value to BSON"`
 
 ## Complexity
 
@@ -110,6 +113,8 @@ pass before anything is written.
 - Throws `out_of_range.412` and `out_of_range.415` since version 3.13.0.
 - Linear in the size of `j`, and no longer limited by the call stack for deeply nested values, since version 3.13.0.
 - `out_of_range.415` is now detected before anything is written, like the other exceptions above, since version 3.13.0.
+- Throws `type_error.321` for a discarded value nested in `j` since version 3.13.0; previously, it was silently
+  skipped, producing a document whose declared size did not match what was actually written.
 - Added `error_handler` parameter in version 3.13.0. Its default, `keep`, writes the bytes of a string or object key
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316` before anything

docs/mkdocs/docs/api/basic_json/to_cbor.md

@@ -49,6 +49,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is
+  discarded; example: `"cannot serialize discarded value to CBOR"`
 
 ## Complexity
 
@@ -86,3 +88,5 @@ Linear in the size of the JSON value `j`.
 - Added `error_handler` parameter in version 3.13.0. Its default, `keep`, writes the bytes of a string or object key
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
+- Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
+  array or object was silently skipped, producing invalid CBOR.

docs/mkdocs/docs/api/basic_json/to_msgpack.md

@@ -54,6 +54,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
   `"subtype 70000 is too large for the MessagePack ext type (max 255)"`
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict`
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is
+  discarded; example: `"cannot serialize discarded value to MessagePack"`
 
 ## Complexity
 
@@ -108,3 +110,5 @@ Linear in the size of the JSON value `j`.
 - Fixed in version 3.13.0 to serialize `number_integer_t`/`number_unsigned_t` pairs of different width correctly;
   before, integers could be serialized with the wrong value if `number_integer_t` was narrower than
   `number_unsigned_t`.
+- Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
+  array or object was silently skipped, producing invalid MessagePack.

docs/mkdocs/docs/api/basic_json/to_ubjson.md

@@ -61,6 +61,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is
+  discarded; example: `"cannot serialize discarded value to UBJSON"`
 
 ## Complexity
 
@@ -112,3 +114,5 @@ Linear in the size of the JSON value `j`.
 - Added `error_handler` parameter in version 3.13.0. Its default, `keep`, writes the bytes of a string or object key
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
+- Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
+  array or object was silently skipped, producing invalid UBJSON.

docs/mkdocs/docs/community/quality_assurance.md

@@ -21,18 +21,17 @@ Note: Some modern features (like C++20 ranges or filesystem support) may be disa
       
         | Compiler                                     | Architecture | Operating System                  | CI        |
         |----------------------------------------------|--------------|-----------------------------------|-----------|
+        | AppleClang 15.0.0.15000040; Xcode 15.0.1     | arm64        | macOS 14.7.2 (Sonoma)             | GitHub    |
+        | AppleClang 15.0.0.15000100; Xcode 15.1       | arm64        | macOS 14.7.2 (Sonoma)             | GitHub    |
+        | AppleClang 15.0.0.15000100; Xcode 15.2       | arm64        | macOS 14.7.2 (Sonoma)             | GitHub    |
+        | AppleClang 15.0.0.15000309; Xcode 15.3       | arm64        | macOS 14.7.2 (Sonoma)             | GitHub    |
+        | AppleClang 15.0.0.15000309; Xcode 15.4       | arm64        | macOS 14.7.2 (Sonoma)             | GitHub    |
         | AppleClang 16.0.0.16000026; Xcode 16         | arm64        | macOS 15.2 (Sequoia)              | GitHub    |
         | AppleClang 16.0.0.16000026; Xcode 16.1       | arm64        | macOS 15.2 (Sequoia)              | GitHub    |
         | AppleClang 16.0.0.16000026; Xcode 16.2       | arm64        | macOS 15.2 (Sequoia)              | GitHub    |
         | AppleClang 17.0.0.17000013; Xcode 16.3       | arm64        | macOS 15.5 (Sequoia)              | GitHub    |
         | AppleClang 17.0.0.17000013; Xcode 16.4       | arm64        | macOS 15.5 (Sequoia)              | GitHub    |
         | AppleClang 17.0.0.17000319; Xcode 26.0.1     | arm64        | macOS 15.5 (Sequoia)              | GitHub    |
-        | AppleClang 17.0.0.17000404; Xcode 26.1.1     | arm64        | macOS 15.7.9 (Sequoia)            | GitHub    |
-        | AppleClang 17.0.0.17000603; Xcode 26.2       | arm64        | macOS 15.7.9 (Sequoia)            | GitHub    |
-        | AppleClang 17.0.0.17000604; Xcode 26.3       | arm64        | macOS 15.7.9 (Sequoia)            | GitHub    |
-        | AppleClang 21.0.0.21000099; Xcode 26.4.1     | arm64        | macOS 26.6.2 (Tahoe)              | GitHub    |
-        | AppleClang 21.0.0.21000101; Xcode 26.5       | arm64        | macOS 26.6.2 (Tahoe)              | GitHub    |
-        | AppleClang 21.0.0.21000101; Xcode 26.6       | arm64        | macOS 26.6.2 (Tahoe)              | GitHub    |
         | Clang 3.4.2                                  | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
         | Clang 3.5.2                                  | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
         | Clang 3.6.2                                  | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
@@ -90,7 +89,7 @@ Note: Some modern features (like C++20 ranges or filesystem support) may be disa
         | GNU 13.3.0                                   | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
         | GNU 14.2.0                                   | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
         | GNU 15.1.0                                   | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
-        | GNU 16.2.0                                   | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
+        | GNU 16.1.0                                   | x86_64       | Ubuntu 22.04.1 LTS                | GitHub    |
         | GNU 16.1.0                                   | arm64        | Ubuntu 24.04                      | GitHub    |
         | icpc (ICC) 2021.10.0 20230609                | x86_64       | Ubuntu 22.04 LTS                  | GitHub    |
         | icpx (Intel oneAPI DPC++/C++) 2025.3.2       | x86_64       | Ubuntu 24.04 LTS                  | GitHub    |

docs/mkdocs/docs/home/exceptions.md

@@ -804,6 +804,20 @@ does not list an enumerator and it is therefore converted like the first listed
     [json.exception.type_error.318] duplicate object key 'red'
     ```
 
+### json.exception.type_error.321
+
+A discarded value (one created by [`parse()`](../api/basic_json/parse.md) with a callback that returns `false` for the
+value, or by default-constructing a [`basic_json`](../api/basic_json/index.md) with
+[`value_t::discarded`](../api/basic_json/value_t.md)) was passed to a binary serialization function, either directly or
+nested in an array or object. There is no way to represent a discarded value in CBOR, MessagePack, UBJSON, BJData, or BSON.
+
+!!! failure "Example message"
+
+    Serializing `#!json [1, 2]` to CBOR, where the second element was discarded by a parser callback:
+    ```
+    [json.exception.type_error.321] cannot serialize discarded value to CBOR
+    ```
+
 ## Out of range
 
 This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for instance, in the case of array indices or nonexisting object keys.

include/nlohmann/detail/output/binary_writer.hpp

@@ -127,6 +127,7 @@ class binary_writer
     @throw type_error.316 if a string value or an object key is not valid
            UTF-8
     @throw type_error.317 if @a j is not an object
+    @throw type_error.321 if a value nested in @a j is discarded
     */
     void write_bson(const BasicJsonType& j)
     {
@@ -158,6 +159,7 @@ class binary_writer
     @param[in] j  JSON value to serialize
     @throw type_error.316 if a string value or an object key is not valid
            UTF-8
+    @throw type_error.321 if @a j or a value nested in it is discarded
     */
     void write_cbor(const BasicJsonType& j)
     {
@@ -322,7 +324,7 @@ class binary_writer
 
             case value_t::discarded:
             default:
-                break;
+                throw_on_discarded(j, "CBOR");
         }
     }
 
@@ -382,6 +384,7 @@ class binary_writer
 
     /*!
     @param[in] j  JSON value to serialize
+    @throw type_error.321 if @a j or a value nested in it is discarded
     */
     void write_msgpack(const BasicJsonType& j)
     {
@@ -655,7 +658,7 @@ class binary_writer
 
             case value_t::discarded:
             default:
-                break;
+                throw_on_discarded(j, "MessagePack");
         }
     }
 
@@ -668,6 +671,7 @@ class binary_writer
     @param[in] bjdata_version  which BJData version to use, default is draft2
     @throw type_error.316 if a string value or an object key is not valid
            UTF-8
+    @throw type_error.321 if @a j or a value nested in it is discarded
     */
     void write_ubjson(const BasicJsonType& j, const bool use_count,
                       const bool use_type, const bool add_prefix = true,
@@ -901,7 +905,7 @@ class binary_writer
 
             case value_t::discarded:
             default:
-                break;
+                throw_on_discarded(j, use_bjdata ? "BJData" : "UBJSON");
         }
     }
 
@@ -921,6 +925,15 @@ class binary_writer
     }
 
   private:
+    /*!
+    @brief throws because @a j is discarded and cannot be serialized
+    @throw type_error.321 always
+    */
+    JSON_HEDLEY_NO_RETURN static void throw_on_discarded(const BasicJsonType& j, const char* format_name)
+    {
+        JSON_THROW(type_error::create(321, concat("cannot serialize discarded value to ", format_name), &j));
+    }
+
     //////////
     // BSON //
     //////////
@@ -1172,6 +1185,7 @@ class binary_writer
            into a byte, before anything is written
     @throw type_error.316 if @a j is a string that is not valid UTF-8, before
            anything is written
+    @throw type_error.321 if @a j is discarded
     */
     std::size_t calc_bson_value_size(const BasicJsonType& j)
     {
@@ -1198,10 +1212,12 @@ class binary_writer
             case value_t::null:
                 return 0ul;
 
+            case value_t::discarded:
+                throw_on_discarded(j, "BSON");
+
             // LCOV_EXCL_START
             case value_t::object:
             case value_t::array:
-            case value_t::discarded:
             default:
                 JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert)
                 return 0ul;
@@ -1238,10 +1254,12 @@ class binary_writer
             case value_t::null:
                 return write_bson_null(name);
 
+            case value_t::discarded:
+                throw_on_discarded(j, "BSON");
+
             // LCOV_EXCL_START
             case value_t::object:
             case value_t::array:
-            case value_t::discarded:
             default:
                 JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert)
                 return;
@@ -1308,6 +1326,8 @@ class binary_writer
            byte, before anything is written
     @throw type_error.316 if a string value or a key is not valid UTF-8,
            before anything is written
+    @throw type_error.321 if a value nested in @a document is discarded,
+           before anything is written
     */
     std::size_t calc_bson_sizes(const BasicJsonType& document, std::vector<std::size_t>& nested_sizes)
     {

single_include/nlohmann/json.hpp

@@ -21529,6 +21529,7 @@ class binary_writer
     @throw type_error.316 if a string value or an object key is not valid
            UTF-8
     @throw type_error.317 if @a j is not an object
+    @throw type_error.321 if a value nested in @a j is discarded
     */
     void write_bson(const BasicJsonType& j)
     {
@@ -21560,6 +21561,7 @@ class binary_writer
     @param[in] j  JSON value to serialize
     @throw type_error.316 if a string value or an object key is not valid
            UTF-8
+    @throw type_error.321 if @a j or a value nested in it is discarded
     */
     void write_cbor(const BasicJsonType& j)
     {
@@ -21724,7 +21726,7 @@ class binary_writer
 
             case value_t::discarded:
             default:
-                break;
+                throw_on_discarded(j, "CBOR");
         }
     }
 
@@ -21784,6 +21786,7 @@ class binary_writer
 
     /*!
     @param[in] j  JSON value to serialize
+    @throw type_error.321 if @a j or a value nested in it is discarded
     */
     void write_msgpack(const BasicJsonType& j)
     {
@@ -22057,7 +22060,7 @@ class binary_writer
 
             case value_t::discarded:
             default:
-                break;
+                throw_on_discarded(j, "MessagePack");
         }
     }
 
@@ -22070,6 +22073,7 @@ class binary_writer
     @param[in] bjdata_version  which BJData version to use, default is draft2
     @throw type_error.316 if a string value or an object key is not valid
            UTF-8
+    @throw type_error.321 if @a j or a value nested in it is discarded
     */
     void write_ubjson(const BasicJsonType& j, const bool use_count,
                       const bool use_type, const bool add_prefix = true,
@@ -22303,7 +22307,7 @@ class binary_writer
 
             case value_t::discarded:
             default:
-                break;
+                throw_on_discarded(j, use_bjdata ? "BJData" : "UBJSON");
         }
     }
 
@@ -22323,6 +22327,15 @@ class binary_writer
     }
 
   private:
+    /*!
+    @brief throws because @a j is discarded and cannot be serialized
+    @throw type_error.321 always
+    */
+    JSON_HEDLEY_NO_RETURN static void throw_on_discarded(const BasicJsonType& j, const char* format_name)
+    {
+        JSON_THROW(type_error::create(321, concat("cannot serialize discarded value to ", format_name), &j));
+    }
+
     //////////
     // BSON //
     //////////
@@ -22574,6 +22587,7 @@ class binary_writer
            into a byte, before anything is written
     @throw type_error.316 if @a j is a string that is not valid UTF-8, before
            anything is written
+    @throw type_error.321 if @a j is discarded
     */
     std::size_t calc_bson_value_size(const BasicJsonType& j)
     {
@@ -22600,10 +22614,12 @@ class binary_writer
             case value_t::null:
                 return 0ul;
 
+            case value_t::discarded:
+                throw_on_discarded(j, "BSON");
+
             // LCOV_EXCL_START
             case value_t::object:
             case value_t::array:
-            case value_t::discarded:
             default:
                 JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert)
                 return 0ul;
@@ -22640,10 +22656,12 @@ class binary_writer
             case value_t::null:
                 return write_bson_null(name);
 
+            case value_t::discarded:
+                throw_on_discarded(j, "BSON");
+
             // LCOV_EXCL_START
             case value_t::object:
             case value_t::array:
-            case value_t::discarded:
             default:
                 JSON_ASSERT(false); // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert)
                 return;
@@ -22710,6 +22728,8 @@ class binary_writer
            byte, before anything is written
     @throw type_error.316 if a string value or a key is not valid UTF-8,
            before anything is written
+    @throw type_error.321 if a value nested in @a document is discarded,
+           before anything is written
     */
     std::size_t calc_bson_sizes(const BasicJsonType& document, std::vector<std::size_t>& nested_sizes)
     {

tests/src/unit-bjdata.cpp

@@ -106,10 +106,59 @@ TEST_CASE("BJData")
     {
         SECTION("discarded")
         {
-            // discarded values are not serialized
+            // a discarded value cannot be serialized to BJData
             json const j = json::value_t::discarded;
-            const auto result = json::to_bjdata(j);
-            CHECK(result.empty());
+            CHECK_THROWS_WITH_AS(json::to_bjdata(j), "[json.exception.type_error.321] cannot serialize discarded value to BJData", json::type_error&);
+        }
+
+        SECTION("discarded values nested in a container")
+        {
+            json const discarded = json::value_t::discarded;
+
+            SECTION("in an array")
+            {
+                json const j = {1, discarded, 2};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_bjdata(j), "[json.exception.type_error.321] (/1) cannot serialize discarded value to BJData", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_bjdata(j), "[json.exception.type_error.321] cannot serialize discarded value to BJData", json::type_error&);
+#endif
+            }
+
+            SECTION("as an object value")
+            {
+                json j;
+                j["a"] = 1;
+                j["b"] = discarded;
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_bjdata(j), "[json.exception.type_error.321] (/b) cannot serialize discarded value to BJData", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_bjdata(j), "[json.exception.type_error.321] cannot serialize discarded value to BJData", json::type_error&);
+#endif
+            }
+
+            SECTION("nested deeper (array in object in array)")
+            {
+                json inner_array = {1, discarded};
+                json middle_object;
+                middle_object["x"] = inner_array;
+                json const j = {middle_object};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_bjdata(j), "[json.exception.type_error.321] (/0/x/1) cannot serialize discarded value to BJData", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_bjdata(j), "[json.exception.type_error.321] cannot serialize discarded value to BJData", json::type_error&);
+#endif
+            }
+
+            SECTION("optimized array of all-discarded elements")
+            {
+                json const j = {discarded, discarded};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_bjdata(j, true, true), "[json.exception.type_error.321] (/0) cannot serialize discarded value to BJData", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_bjdata(j, true, true), "[json.exception.type_error.321] cannot serialize discarded value to BJData", json::type_error&);
+#endif
+            }
         }
 
         SECTION("null")

tests/src/unit-bson.cpp

@@ -141,6 +141,54 @@ TEST_CASE("BSON")
             json const j = std::vector<int> {1, 2, 3, 4, 5, 6, 7};
             CHECK_THROWS_WITH_AS(json::to_bson(j), "[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is array", json::type_error&);
         }
+
+        SECTION("discarded")
+        {
+            json const j = json::value_t::discarded;
+            CHECK_THROWS_WITH_AS(json::to_bson(j), "[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is discarded", json::type_error&);
+        }
+    }
+
+    SECTION("discarded values nested in a container cannot be serialized to BSON")
+    {
+        json const discarded = json::value_t::discarded;
+
+        SECTION("as an object value")
+        {
+            json j;
+            j["a"] = 1;
+            j["b"] = discarded;
+#if JSON_DIAGNOSTICS
+            CHECK_THROWS_WITH_AS(json::to_bson(j), "[json.exception.type_error.321] (/b) cannot serialize discarded value to BSON", json::type_error&);
+#else
+            CHECK_THROWS_WITH_AS(json::to_bson(j), "[json.exception.type_error.321] cannot serialize discarded value to BSON", json::type_error&);
+#endif
+        }
+
+        SECTION("in an array that is an object value")
+        {
+            json j;
+            j["a"] = json::array({1, discarded, 2});
+#if JSON_DIAGNOSTICS
+            CHECK_THROWS_WITH_AS(json::to_bson(j), "[json.exception.type_error.321] (/a/1) cannot serialize discarded value to BSON", json::type_error&);
+#else
+            CHECK_THROWS_WITH_AS(json::to_bson(j), "[json.exception.type_error.321] cannot serialize discarded value to BSON", json::type_error&);
+#endif
+        }
+
+        SECTION("nested deeper (array in object in object)")
+        {
+            json inner_array = {1, discarded};
+            json middle_object;
+            middle_object["x"] = inner_array;
+            json j;
+            j["outer"] = middle_object;
+#if JSON_DIAGNOSTICS
+            CHECK_THROWS_WITH_AS(json::to_bson(j), "[json.exception.type_error.321] (/outer/x/1) cannot serialize discarded value to BSON", json::type_error&);
+#else
+            CHECK_THROWS_WITH_AS(json::to_bson(j), "[json.exception.type_error.321] cannot serialize discarded value to BSON", json::type_error&);
+#endif
+        }
     }
 
     SECTION("keys containing code-point U+0000 cannot be serialized to BSON")

tests/src/unit-cbor.cpp

@@ -30,10 +30,49 @@ TEST_CASE("CBOR")
     {
         SECTION("discarded")
         {
-            // discarded values are not serialized
+            // a discarded value cannot be serialized to CBOR
             json const j = json::value_t::discarded;
-            const auto result = json::to_cbor(j);
-            CHECK(result.empty());
+            CHECK_THROWS_WITH_AS(json::to_cbor(j), "[json.exception.type_error.321] cannot serialize discarded value to CBOR", json::type_error&);
+        }
+
+        SECTION("discarded values nested in a container")
+        {
+            json const discarded = json::value_t::discarded;
+
+            SECTION("in an array")
+            {
+                json const j = {1, discarded, 2};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_cbor(j), "[json.exception.type_error.321] (/1) cannot serialize discarded value to CBOR", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_cbor(j), "[json.exception.type_error.321] cannot serialize discarded value to CBOR", json::type_error&);
+#endif
+            }
+
+            SECTION("as an object value")
+            {
+                json j;
+                j["a"] = 1;
+                j["b"] = discarded;
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_cbor(j), "[json.exception.type_error.321] (/b) cannot serialize discarded value to CBOR", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_cbor(j), "[json.exception.type_error.321] cannot serialize discarded value to CBOR", json::type_error&);
+#endif
+            }
+
+            SECTION("nested deeper (array in object in array)")
+            {
+                json inner_array = {1, discarded};
+                json middle_object;
+                middle_object["x"] = inner_array;
+                json const j = {middle_object};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_cbor(j), "[json.exception.type_error.321] (/0/x/1) cannot serialize discarded value to CBOR", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_cbor(j), "[json.exception.type_error.321] cannot serialize discarded value to CBOR", json::type_error&);
+#endif
+            }
         }
 
         SECTION("NaN")

tests/src/unit-msgpack.cpp

@@ -33,10 +33,49 @@ TEST_CASE("MessagePack")
     {
         SECTION("discarded")
         {
-            // discarded values are not serialized
+            // a discarded value cannot be serialized to MessagePack
             json const j = json::value_t::discarded;
-            const auto result = json::to_msgpack(j);
-            CHECK(result.empty());
+            CHECK_THROWS_WITH_AS(json::to_msgpack(j), "[json.exception.type_error.321] cannot serialize discarded value to MessagePack", json::type_error&);
+        }
+
+        SECTION("discarded values nested in a container")
+        {
+            json const discarded = json::value_t::discarded;
+
+            SECTION("in an array")
+            {
+                json const j = {1, discarded, 2};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_msgpack(j), "[json.exception.type_error.321] (/1) cannot serialize discarded value to MessagePack", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_msgpack(j), "[json.exception.type_error.321] cannot serialize discarded value to MessagePack", json::type_error&);
+#endif
+            }
+
+            SECTION("as an object value")
+            {
+                json j;
+                j["a"] = 1;
+                j["b"] = discarded;
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_msgpack(j), "[json.exception.type_error.321] (/b) cannot serialize discarded value to MessagePack", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_msgpack(j), "[json.exception.type_error.321] cannot serialize discarded value to MessagePack", json::type_error&);
+#endif
+            }
+
+            SECTION("nested deeper (array in object in array)")
+            {
+                json inner_array = {1, discarded};
+                json middle_object;
+                middle_object["x"] = inner_array;
+                json const j = {middle_object};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_msgpack(j), "[json.exception.type_error.321] (/0/x/1) cannot serialize discarded value to MessagePack", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_msgpack(j), "[json.exception.type_error.321] cannot serialize discarded value to MessagePack", json::type_error&);
+#endif
+            }
         }
 
         SECTION("null")

tests/src/unit-ubjson.cpp

@@ -27,10 +27,59 @@ TEST_CASE("UBJSON")
     {
         SECTION("discarded")
         {
-            // discarded values are not serialized
+            // a discarded value cannot be serialized to UBJSON
             json const j = json::value_t::discarded;
-            const auto result = json::to_ubjson(j);
-            CHECK(result.empty());
+            CHECK_THROWS_WITH_AS(json::to_ubjson(j), "[json.exception.type_error.321] cannot serialize discarded value to UBJSON", json::type_error&);
+        }
+
+        SECTION("discarded values nested in a container")
+        {
+            json const discarded = json::value_t::discarded;
+
+            SECTION("in an array")
+            {
+                json const j = {1, discarded, 2};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_ubjson(j), "[json.exception.type_error.321] (/1) cannot serialize discarded value to UBJSON", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_ubjson(j), "[json.exception.type_error.321] cannot serialize discarded value to UBJSON", json::type_error&);
+#endif
+            }
+
+            SECTION("as an object value")
+            {
+                json j;
+                j["a"] = 1;
+                j["b"] = discarded;
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_ubjson(j), "[json.exception.type_error.321] (/b) cannot serialize discarded value to UBJSON", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_ubjson(j), "[json.exception.type_error.321] cannot serialize discarded value to UBJSON", json::type_error&);
+#endif
+            }
+
+            SECTION("nested deeper (array in object in array)")
+            {
+                json inner_array = {1, discarded};
+                json middle_object;
+                middle_object["x"] = inner_array;
+                json const j = {middle_object};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_ubjson(j), "[json.exception.type_error.321] (/0/x/1) cannot serialize discarded value to UBJSON", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_ubjson(j), "[json.exception.type_error.321] cannot serialize discarded value to UBJSON", json::type_error&);
+#endif
+            }
+
+            SECTION("optimized array of all-discarded elements")
+            {
+                json const j = {discarded, discarded};
+#if JSON_DIAGNOSTICS
+                CHECK_THROWS_WITH_AS(json::to_ubjson(j, true, true), "[json.exception.type_error.321] (/0) cannot serialize discarded value to UBJSON", json::type_error&);
+#else
+                CHECK_THROWS_WITH_AS(json::to_ubjson(j, true, true), "[json.exception.type_error.321] cannot serialize discarded value to UBJSON", json::type_error&);
+#endif
+            }
         }
 
         SECTION("null")
@@ -2091,9 +2140,14 @@ TEST_CASE("UBJSON")
 
         SECTION("discarded")
         {
+            // a discarded value cannot be serialized to UBJSON, even as part
+            // of an optimized array of a single (here: valueless) type
             json const j = {json::value_t::discarded, json::value_t::discarded};
-            std::vector<uint8_t> expected = {'[', '$', 'N', '#', 'i', 2};
-            CHECK(json::to_ubjson(j, true, true) == expected);
+#if JSON_DIAGNOSTICS
+            CHECK_THROWS_WITH_AS(json::to_ubjson(j, true, true), "[json.exception.type_error.321] (/0) cannot serialize discarded value to UBJSON", json::type_error&);
+#else
+            CHECK_THROWS_WITH_AS(json::to_ubjson(j, true, true), "[json.exception.type_error.321] cannot serialize discarded value to UBJSON", json::type_error&);
+#endif
         }
     }
 }