Serialize enum (#5151)

nugentcaillin · nlohmann · web-flow · commit 58cfecf7f745 · 2026-05-18T20:37:07.000+02:00
* Added NLOHNMANN_JSON_SERIALIZE_ENUM_STRICT - duplicate of NLOHMANN_JSON_SERIALIZE_ENUM Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * Added failing tests for NLOHMANN_JSON_SERIALIZE_ENUM_STRICT Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * modified NLOHMANN_JSON_SERIALIZE_STRICT to throw Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * added documentation and changed readme to include NLOHMANN_JSON_SERIALIZE_ENUM_STRICT Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * ran amalgamate Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * docs(macros): add page for JSON_SERIALIZE_ENUM_STRICT - added page to nav - added links to new page where appropriate Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * refactor(macros): make JSON_SERIALIZE_ENUM_STRICT use JSON_THROW - added templated wrapper function to fix scope error in calling JSON_THROW Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * refactor(macros): make NLOHMANN_SERIALIZE_ENUM_STRICT use error code 410 - added error code 410 to docs Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * tests(macros): add test for to_json with enum value not mentioned in mapping for NLOHMANN_JSON_SERIALIZE_ENUM_STRICT Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * Apply suggestions from code review Co-authored-by: Niels Lohmann <niels.lohmann@gmail.com> Signed-off-by: Caillin Nugent <nugentcaillin@gmail.com> * fix(macro): prevent compilation error with -Werror and -Wunused-parameter with NLOHMANN_JSON_SERIALIZE_ENUM_STRICT - casted exception to void to avoid warning Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * fix(docs): add link to NLOHMANN_SERIALIZE_ENUM_STRICT docs to exception page Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * docs(macros): add example of exception throwing for NLOHMANN_JSON_SERIALIZE_ENUM_STRICT Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> * refactor(macros): add more in-depth error message to NLOHMANN_JSON_SERIALIZE_ENUM_STRICT - changed error message to follow style of #4989 - made description of throw wrapper more general - updated tests and example of exceptions Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> --------- Signed-off-by: Caillin Nugent <caillinn@student.unimelb.edu.au> Signed-off-by: Caillin Nugent <nugentcaillin@gmail.com> Co-authored-by: Niels Lohmann <niels.lohmann@gmail.com>
diff --git a/README.md b/README.md
@@ -1105,7 +1105,7 @@ Just as in [Arbitrary Type Conversions](#arbitrary-types-conversions) above,
 
 Other Important points:
 
-- When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this default pair carefully.
+- When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this default pair carefully. If you desire an exception in this circumstance use `NLOHMANN_JSON_SERIALIZE_ENUM_STRICT()` which behaves identically except for throwing an exception on unrecognized values.
 - If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.
 
 ### Binary formats (BSON, CBOR, MessagePack, UBJSON, and BJData)
diff --git a/docs/mkdocs/docs/api/macros/index.md b/docs/mkdocs/docs/api/macros/index.md
@@ -54,6 +54,7 @@ header. See also the [macro overview page](../../features/macros.md).
 ### Enums
 
 - [**NLOHMANN_JSON_SERIALIZE_ENUM**](nlohmann_json_serialize_enum.md) - serialize/deserialize an enum
+- [**NLOHMANN_JSON_SERIALIZE_ENUM_STRICT**](nlohmann_json_serialize_enum_strict.md) - serialize/deserialize an enum with exceptions
 
 ### Classes and structs
 
diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum.md b/docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum.md
@@ -78,6 +78,7 @@ inline void from_json(const BasicJsonType& j, type& e);
 ## See also
 
 - [Specializing enum conversion](../../features/enum_conversion.md)
+- [`NLOHMANN_JSON_SERIALIZE_ENUM_STRICT`](./nlohmann_json_serialize_enum_strict.md)
 - [`JSON_DISABLE_ENUM_SERIALIZATION`](json_disable_enum_serialization.md)
 
 ## Version history
diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum_strict.md b/docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum_strict.md
@@ -0,0 +1,102 @@
+# NLOHMANN_JSON_SERIALIZE_ENUM_STRICT
+
+```cpp
+#define NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(type, conversion...)
+```
+
+By default, enum values are serialized to JSON as integers. In some cases, this could result in undesired behavior. If
+an enum is modified or re-ordered after data has been serialized to JSON, the later deserialized JSON data may be
+undefined or a different enum value than was originally intended.
+
+`NLOHMANN_JSON_SERIALIZE_ENUM_STRICT` allows to define a user-defined serialization for every enumerator that
+throws an exception on undefined input.
+
+## Parameters
+
+`type` (in)
+:   name of the enum to serialize/deserialize
+
+`conversion` (in)
+:   a pair of an enumerator and a JSON serialization; arbitrary pairs can be given as a comma-separated list
+
+## Default definition
+
+The macro adds two functions to the namespace which take care of the serialization and deserialization:
+
+```cpp
+template<typename BasicJsonType>
+inline void to_json(BasicJsonType& j, const type& e);
+template<typename BasicJsonType>
+inline void from_json(const BasicJsonType& j, type& e);
+```
+
+## Notes
+
+!!! info "Prerequisites"
+
+    The macro must be used inside the namespace of the enum.
+
+!!! important "Important notes"
+
+    - When using [`get<ENUM_TYPE>()`](../basic_json/get.md), undefined JSON values will throw an exception.
+    - If an enum or JSON value is specified in multiple conversions, the first matching conversion from the top of the
+      list will be returned when converting to or from JSON. See example 2 below.
+
+## Examples
+
+??? example "Example 1: Basic usage"
+
+    The example shows how `NLOHMANN_JSON_SERIALIZE_ENUM_STRICT` can be used to serialize/deserialize both classical enums and
+    C++11 enum classes:
+
+    ```cpp hl_lines="16 17 18 19 20 21 22 29 30 31 32 33"
+    --8<-- "examples/nlohmann_json_serialize_enum_strict.cpp"
+    ```
+
+    Output:
+    
+    ```json
+    --8<-- "examples/nlohmann_json_serialize_enum_strict.output"
+    ```
+
+??? example "Example 2: Multiple conversions for one enumerator"
+
+    The example shows how to use multiple conversions for a single enumerator. In the example, `Color::red` will always
+    be *serialized* to `"red"`, because the first occurring conversion. The second conversion, however, offers an
+    alternative *deserialization* from `"rot"` to `Color::red`.
+
+    ```cpp hl_lines="17"
+    --8<-- "examples/nlohmann_json_serialize_enum_strict_2.cpp"
+    ```
+
+    Output:
+    
+    ```json
+    --8<-- "examples/nlohmann_json_serialize_enum_strict_2.output"
+    ```
+
+??? example "Example 3: exceptions on invalid serialization"
+    
+    The example shows how an invalid serialization causes an exception to be thrown. In the example,
+    Color::unknown is not defined in the mapping used to call `NLOHMANN_JSON_SERIALIZE_ENUM_STRICT`
+    so causes an exception when used to serialize. Similarly, "what" does not refer to an enum
+    value so also causes an exception when deserialization is attempted.
+
+    ```cpp hl_lines="14 32 33 43 44 45"
+    --8<-- "examples/nlohmann_json_serialize_enum_strict_err.cpp"
+    ```
+
+    Output:
+    ```json
+    --8<-- "examples/nlohmann_json_serialize_enum_strict_err.output"
+    ```
+
+## See also
+
+- [Specializing enum conversion](../../features/enum_conversion.md)
+- [`NLOHMANN_JSON_SERIALIZE_ENUM`](./nlohmann_json_serialize_enum.md)
+- [`JSON_DISABLE_ENUM_SERIALIZATION`](json_disable_enum_serialization.md)
+
+## Version history
+
+Added in version 3.12.0.
diff --git a/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict.cpp b/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict.cpp
@@ -0,0 +1,52 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+enum TaskState
+{
+    TS_STOPPED,
+    TS_RUNNING,
+    TS_COMPLETED,
+    TS_INVALID = -1
+};
+
+NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(TaskState,
+{
+    { TS_INVALID, nullptr },
+    { TS_STOPPED, "stopped" },
+    { TS_RUNNING, "running" },
+    { TS_COMPLETED, "completed" }
+})
+
+enum class Color
+{
+    red, green, blue, unknown
+};
+
+NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(Color,
+{
+    { Color::unknown, "unknown" }, { Color::red, "red" },
+    { Color::green, "green" }, { Color::blue, "blue" }
+})
+} // namespace ns
+
+int main()
+{
+    // serialization
+    json j_stopped = ns::TS_STOPPED;
+    json j_red = ns::Color::red;
+    std::cout << "ns::TS_STOPPED -> " << j_stopped
+              << ", ns::Color::red -> " << j_red << std::endl;
+
+    // deserialization
+    json j_running = "running";
+    json j_blue = "blue";
+    auto running = j_running.get<ns::TaskState>();
+    auto blue = j_blue.get<ns::Color>();
+    std::cout << j_running << " -> " << running
+              << ", " << j_blue << " -> " << static_cast<int>(blue) << std::endl;
+
+}
diff --git a/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict.output b/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict.output
@@ -0,0 +1,2 @@
+ns::TS_STOPPED -> "stopped", ns::Color::red -> "red"
+"running" -> 1, "blue" -> 2
diff --git a/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_2.cpp b/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_2.cpp
@@ -0,0 +1,33 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+enum class Color
+{
+    red, green, blue, unknown
+};
+
+NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(Color,
+{
+    { Color::unknown, "unknown" }, { Color::red, "red" },
+    { Color::green, "green" }, { Color::blue, "blue" },
+    { Color::red, "rot" } // a second conversion for Color::red
+})
+}
+
+int main()
+{
+    // serialization
+    json j_red = ns::Color::red;
+    std::cout << static_cast<int>(ns::Color::red) << " -> " << j_red << std::endl;
+
+    // deserialization
+    json j_rot = "rot";
+    auto rot = j_rot.get<ns::Color>();
+    auto red = j_red.get<ns::Color>();
+    std::cout << j_rot << " -> " << static_cast<int>(rot) << std::endl;
+    std::cout << j_red << " -> " << static_cast<int>(red) << std::endl;
+}
diff --git a/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_2.output b/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_2.output
@@ -0,0 +1,3 @@
+0 -> "red"
+"rot" -> 0
+"red" -> 0
diff --git a/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_err.cpp b/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_err.cpp
@@ -0,0 +1,53 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+
+enum class Color
+{
+    red,
+    green,
+    blue,
+    unknown // not mapped in JSON_SERIALIZE_ENUM_STRICT
+};
+
+NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(Color,
+{
+    {Color::red, "red"},
+    {Color::green, "green"},
+    {Color::blue, "blue"}
+})
+
+} // namespace ns
+
+
+int main()
+{
+    // invalid serialization
+    try
+    {
+        // ns::color::unknown was not mapped in macro
+        json invalid_serialization = ns::Color::unknown;
+    }
+    catch (const json::exception e)
+    {
+        std::cout << "deserialization failed: " << e.what() << std::endl;
+    }
+
+    // invalid deserialization
+    try
+    {
+        // what does not map to an enum
+        json invalid_deserialization("what");
+        ns::Color color = invalid_deserialization.get<ns::Color>();
+    }
+    catch (const json::exception e)
+    {
+        std::cout << "deserialization failed: " << e.what() << std::endl;
+    }
+
+    return 0;
+}
diff --git a/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_err.output b/docs/mkdocs/docs/examples/nlohmann_json_serialize_enum_strict_err.output
@@ -0,0 +1,2 @@
+deserialization failed: [json.exception.out_of_range.410] enum value out of range for Color
+deserialization failed: [json.exception.out_of_range.410] enum value out of range for Color: "what"
diff --git a/docs/mkdocs/docs/features/enum_conversion.md b/docs/mkdocs/docs/features/enum_conversion.md
@@ -55,7 +55,8 @@ Just as in [Arbitrary Type Conversions](arbitrary_types.md) above,
 Other Important points:
 
 - When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this
-  default pair carefully.
+  default pair carefully. If you desire an exception in this circumstance use [`NLOHMANN_JSON_SERIALIZE_ENUM_STRICT()`](../api/macros/nlohmann_json_serialize_enum_strict.md)
+  which behaves identically except for throwing an exception on unrecognized values.
 - If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the
   map will be returned when converting to or from JSON.
 - To disable the default serialization of enumerators as integers and force a compiler error instead, see [`JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md).
diff --git a/docs/mkdocs/docs/home/exceptions.md b/docs/mkdocs/docs/home/exceptions.md
@@ -868,6 +868,16 @@ Key identifiers to be serialized to BSON cannot contain code point U+0000, since
     BSON key cannot contain code point U+0000 (at byte 2)
     ```
 
+### json.exception.out_of_range.410
+
+Undefined json fields cannot be used with [`NLOHMANN_JSON_SERIALIZE_ENUM_STRICT`](../api/macros/nlohmann_json_serialize_enum_strict.md)
+
+!!! failure "Example message"
+
+    ```
+    enum value out of range
+    ```
+
 ## Further exceptions
 
 This exception is thrown in case of errors that cannot be classified with the
diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml
@@ -294,6 +294,7 @@ nav:
           - 'NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END': api/macros/nlohmann_json_namespace_begin.md
           - 'NLOHMANN_JSON_NAMESPACE_NO_VERSION': api/macros/nlohmann_json_namespace_no_version.md
           - 'NLOHMANN_JSON_SERIALIZE_ENUM': api/macros/nlohmann_json_serialize_enum.md
+          - 'NLOHMANN_JSON_SERIALIZE_ENUM_STRICT': api/macros/nlohmann_json_serialize_enum_strict.md
           - 'NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, NLOHMANN_JSON_VERSION_PATCH': api/macros/nlohmann_json_version_major.md
   - Community:
       - community/index.md
diff --git a/include/nlohmann/detail/macro_scope.hpp b/include/nlohmann/detail/macro_scope.hpp
@@ -253,6 +253,61 @@
         e = ((it != std::end(m)) ? it : std::begin(m))->first;                                  \
     }
 
+
+
+/*!
+@brief function to wrap JSON_THROW_MACRO - there can be compilation errors about
+       there being no arguments to JSON_THROW that depend on template arguments
+       if this is not used to call JSON_THROW
+*/
+template<typename ExceptionType>
+void templated_json_throw(ExceptionType exception)
+{
+    JSON_THROW(exception);
+
+    /* JSON_THROW(exception) discards exception and aborts - void cast needed to supress
+       compilation error if compiled with -Werror and Wunused-parameter */
+    (void)exception;
+}
+
+/*!
+@brief macro to briefly define a mapping between an enum and JSON with exception
+       on invalid input
+@def NLOHMANN_JSON_SERIALIZE_ENUM_STRICT
+@since version 3.12.0
+*/
+#define NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(ENUM_TYPE, ...)                                     \
+    template<typename BasicJsonType>                                                            \
+    inline void to_json(BasicJsonType& j, const ENUM_TYPE& e)                                   \
+    {                                                                                           \
+        /* NOLINTNEXTLINE(modernize-type-traits) we use C++11 */                                \
+        static_assert(std::is_enum<ENUM_TYPE>::value, #ENUM_TYPE " must be an enum!");          \
+        /* NOLINTNEXTLINE(modernize-avoid-c-arrays) we don't want to depend on <array> */       \
+        static const std::pair<ENUM_TYPE, BasicJsonType> m[] = __VA_ARGS__;                     \
+        auto it = std::find_if(std::begin(m), std::end(m),                                      \
+                               [e](const std::pair<ENUM_TYPE, BasicJsonType>& ej_pair) -> bool  \
+        {                                                                                       \
+            return ej_pair.first == e;                                                          \
+        });                                                                                     \
+        if (it != std::end(m)) j = it->second;                                                  \
+        else templated_json_throw<nlohmann::detail::out_of_range>(nlohmann::detail::out_of_range::create(410,"enum value out of range for " #ENUM_TYPE, nullptr)); \
+    }                                                                                           \
+    template<typename BasicJsonType>                                                            \
+    inline void from_json(const BasicJsonType& j, ENUM_TYPE& e)                                 \
+    {                                                                                           \
+        /* NOLINTNEXTLINE(modernize-type-traits) we use C++11 */                                \
+        static_assert(std::is_enum<ENUM_TYPE>::value, #ENUM_TYPE " must be an enum!");          \
+        /* NOLINTNEXTLINE(modernize-avoid-c-arrays) we don't want to depend on <array> */       \
+        static const std::pair<ENUM_TYPE, BasicJsonType> m[] = __VA_ARGS__;                     \
+        auto it = std::find_if(std::begin(m), std::end(m),                                      \
+                               [&j](const std::pair<ENUM_TYPE, BasicJsonType>& ej_pair) -> bool \
+        {                                                                                       \
+            return ej_pair.second == j;                                                         \
+        });                                                                                     \
+        if (it != std::end(m)) e = it->first;                                                   \
+        else templated_json_throw<nlohmann::detail::out_of_range>(nlohmann::detail::out_of_range::create(410,"enum value out of range for " #ENUM_TYPE ": " + j.dump(), &j)); \
+    }
+
 // Ugly macros to avoid uglier copy-paste when specializing basic_json. They
 // may be removed in the future once the class is split.
 
diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp
diff --git a/tests/src/unit-conversions.cpp b/tests/src/unit-conversions.cpp

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+ns::TS_STOPPED -> "stopped", ns::Color::red -> "red"`
	`2`	`+"running" -> 1, "blue" -> 2`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+0 -> "red"`
	`2`	`+"rot" -> 0`
	`3`	`+"red" -> 0`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+deserialization failed: [json.exception.out_of_range.410] enum value out of range for Color`
	`2`	`+deserialization failed: [json.exception.out_of_range.410] enum value out of range for Color: "what"`