Store maps with enum keys as objects (opt-in) (#5600)

* Store maps with enum keys as objects (opt-in)

Maps with enum keys, such as std::map<E, T>, are stored as arrays of
[key, value] pairs, because enums are not convertible to the string type
of object keys - even if NLOHMANN_JSON_SERIALIZE_ENUM maps them to
strings (#4378).

The new JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS macro stores them as objects
instead, converting each key with the enum's to_json. It applies to any
map-like type with enum keys (std::map with any comparator,
std::unordered_map, ...). A key that does not convert to a string throws
type_error.302, and two keys converting to the same string throw the new
type_error.318, rather than losing an entry. The macro changes the output
of inline functions, so it is part of the ABI tag (_ekmo).

Reading needs no macro: std::map and std::unordered_map with enum keys
are now also read from objects, converting each key with the enum's
from_json. That input was rejected before, and arrays of pairs are still
read, so data written either way can be read.

This supersedes #4531, which first proposed storing these maps as
objects.

Co-authored-by: Muhammad Amir bin Mohamad Ghazaly <amirghaz@umich.edu>
Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Keep multimaps with enum keys as arrays of pairs

With JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS, is_enum_keyed_map also matched
std::multimap and std::unordered_multimap. Storing them as objects throws
type_error.318 as soon as a key occurs twice, which is the normal case for
a multimap, so such values could no longer be serialized at all once the
macro was enabled, although they are stored losslessly as arrays of
[key, value] pairs without it.

Exclude maps with non-unique keys from is_enum_keyed_map. They are
detected by insert(value_type) returning an iterator rather than a
pair<iterator, bool>. Map-like types without such an insert() are still
treated as before.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Move the default enum-keyed map tests out of unit-conversions.cpp

The Windows clang 20.1.8 job (MinGW, Debug) failed to link
test-conversions_cpp17 with "relocation truncated to fit:
IMAGE_REL_AMD64_REL32 against .rdata": the object file of
unit-conversions.cpp was already close to the limit, and the new
"maps with enum keys" test case pushed it over. windows.yml asks to keep
these objects small by splitting test files.

Move the test case unchanged into unit-enum_keyed_maps_default.cpp,
with the three enums it needs. It still honors a -D flag for
JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS, as before. unit-conversions.cpp
is back to its state on develop.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Build the enum-keyed map test object instead of parsing it

ci_test_diagnostic_positions failed in unit-enum_keyed_maps_default.cpp:
with JSON_DIAGNOSTIC_POSITIONS, a parsed value adds its byte range to
the exception message ("(bytes 0-7) type must be array, but is
object"), so the exact-message checks did not match. Build the object
in memory, like unit-custom-array-type.cpp does.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Co-authored-by: Muhammad Amir bin Mohamad Ghazaly <amirghaz@umich.edu>

tests/abi/config/default.cpp

@@ -48,6 +48,10 @@ TEST_CASE("default namespace")
         expected += "_sbu8";
 #endif
 
+#if JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
+        expected += "_ekmo";
+#endif
+
         expected += "_v" STRINGIZE(NLOHMANN_JSON_VERSION_MAJOR);
         expected += "_" STRINGIZE(NLOHMANN_JSON_VERSION_MINOR);
         expected += "_" STRINGIZE(NLOHMANN_JSON_VERSION_PATCH) "::basic_json";

tests/abi/config/noversion.cpp

@@ -49,6 +49,10 @@ TEST_CASE("default namespace without version component")
         expected += "_sbu8";
 #endif
 
+#if JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
+        expected += "_ekmo";
+#endif
+
         expected += "::basic_json";
 
         // fallback for Clang

tests/src/unit-enum_keyed_maps.cpp

@@ -0,0 +1,246 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#include "doctest_compatibility.h"
+
+// skip tests if JSON_DisableEnumSerialization=ON (#4384)
+#if defined(JSON_DISABLE_ENUM_SERIALIZATION) && (JSON_DISABLE_ENUM_SERIALIZATION == 1)
+    #define SKIP_TESTS_FOR_ENUM_SERIALIZATION
+#endif
+
+// This file tests the opt-in JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS, so it defines
+// the macro itself rather than relying on a -D flag, and runs in every build.
+// The default behavior is tested in unit-enum_keyed_maps_default.cpp.
+#ifdef JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
+    #undef JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
+#endif
+
+#define JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS 1
+
+#include <nlohmann/json.hpp>
+using nlohmann::json;
+using nlohmann::ordered_json;
+
+#include <cstddef>
+#include <functional>
+#include <map>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#define STRINGIZE_EX(x) #x
+#define STRINGIZE(x) STRINGIZE_EX(x)
+
+// NLOHMANN_JSON_SERIALIZE_ENUM uses a static std::pair
+DOCTEST_CLANG_SUPPRESS_WARNING_PUSH
+DOCTEST_CLANG_SUPPRESS_WARNING("-Wexit-time-destructors")
+
+namespace
+{
+// std::hash is only required for enums since C++14
+struct enum_hash
+{
+    template<typename T>
+    std::size_t operator()(T t) const noexcept
+    {
+        return static_cast<std::size_t>(t);
+    }
+};
+} // namespace
+
+// the example from #4378
+enum TaskState // NOLINT(cert-int09-c,readability-enum-initial-value,cppcoreguidelines-use-enum-class)
+{
+    TS_STOPPED,
+    TS_RUNNING,
+    TS_COMPLETED,
+    TS_INVALID = -1,
+};
+
+// NOLINTNEXTLINE(misc-const-correctness,misc-use-internal-linkage,cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays) - false positive
+NLOHMANN_JSON_SERIALIZE_ENUM(TaskState,
+{
+    {TS_INVALID, nullptr},
+    {TS_STOPPED, "stopped"},
+    {TS_RUNNING, "running"},
+    {TS_COMPLETED, "completed"},
+})
+
+enum class color {red, green, blue}; // blue is not mapped and falls back to "red"
+
+// NOLINTNEXTLINE(misc-const-correctness,misc-use-internal-linkage,cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays) - false positive
+NLOHMANN_JSON_SERIALIZE_ENUM(color,
+{
+    {color::red, "red"},
+    {color::green, "green"},
+})
+
+enum class strict_color {red, green, blue}; // blue is not mapped
+
+// NOLINTNEXTLINE(misc-const-correctness,misc-use-internal-linkage,cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays) - false positive
+NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(strict_color,
+{
+    {strict_color::red, "red"},
+    {strict_color::green, "green"},
+})
+
+enum class digit {zero, one};
+
+// NOLINTNEXTLINE(misc-const-correctness,misc-use-internal-linkage,cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays) - false positive
+NLOHMANN_JSON_SERIALIZE_ENUM(digit,
+{
+    {digit::zero, 0},
+    {digit::one, 1},
+})
+
+#ifndef SKIP_TESTS_FOR_ENUM_SERIALIZATION
+enum class plain {zero, one}; // serialized as integer
+#endif
+
+TEST_CASE("JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS")
+{
+    SECTION("the macro is part of the ABI tag")
+    {
+        const std::string ns = STRINGIZE(NLOHMANN_JSON_NAMESPACE);
+        CHECK(ns.find("_ekmo") != std::string::npos);
+    }
+
+    SECTION("std::map (#4378)")
+    {
+        using task_map = std::map<TaskState, std::string>;
+        const task_map m = {{TS_STOPPED, "aa"}, {TS_COMPLETED, "bb"}};
+        const json j = m;
+        CHECK(j == json::parse(R"({"stopped":"aa","completed":"bb"})"));
+        CHECK(j.get<task_map>() == m);
+
+        json j2;
+        j2["x"] = m;
+        CHECK(j2.dump() == R"({"x":{"completed":"bb","stopped":"aa"}})");
+    }
+
+    SECTION("std::map with custom comparator")
+    {
+        using task_map = std::map<TaskState, int, std::greater<TaskState>>;
+        const task_map m = {{TS_STOPPED, 1}, {TS_RUNNING, 2}};
+        const json j = m;
+        CHECK(j == json::parse(R"({"stopped":1,"running":2})"));
+        CHECK(j.get<task_map>() == m);
+    }
+
+    SECTION("std::unordered_map")
+    {
+        using task_map = std::unordered_map<TaskState, int, enum_hash>;
+        const task_map m = {{TS_STOPPED, 1}, {TS_RUNNING, 2}};
+        const json j = m;
+        CHECK(j == json::parse(R"({"stopped":1,"running":2})"));
+        CHECK(j.get<task_map>() == m);
+    }
+
+    SECTION("nested maps")
+    {
+        using nested_map = std::map<color, std::map<TaskState, int>>;
+        const nested_map m = {{color::green, {{TS_RUNNING, 1}}}, {color::red, {}}};
+        const json j = m;
+        CHECK(j == json::parse(R"({"green":{"running":1},"red":{}})"));
+        CHECK(j.get<nested_map>() == m);
+    }
+
+    SECTION("ordered_json keeps the order of the map")
+    {
+        using task_map = std::map<TaskState, int>;
+        const task_map m = {{TS_STOPPED, 1}, {TS_RUNNING, 2}, {TS_COMPLETED, 3}};
+        const ordered_json j = m;
+        CHECK(j.dump() == R"({"stopped":1,"running":2,"completed":3})");
+        CHECK(j.get<task_map>() == m);
+    }
+
+    SECTION("empty map")
+    {
+        const json j = std::map<TaskState, int>();
+        CHECK(j.is_object());
+        CHECK(j.empty());
+    }
+
+    SECTION("NLOHMANN_JSON_SERIALIZE_ENUM_STRICT")
+    {
+        using color_map = std::map<strict_color, int>;
+        const color_map m = {{strict_color::red, 1}, {strict_color::green, 2}};
+        const json j = m;
+        CHECK(j == json::parse(R"({"red":1,"green":2})"));
+        CHECK(j.get<color_map>() == m);
+
+        const color_map unmapped = {{strict_color::blue, 1}};
+        json _;
+        CHECK_THROWS_WITH_AS(_ = unmapped,
+                             "[json.exception.out_of_range.410] enum value out of range for strict_color", json::out_of_range&);
+    }
+
+    SECTION("arrays of [key, value] pairs are still read")
+    {
+        using task_map = std::map<TaskState, int>;
+        const task_map m = {{TS_STOPPED, 1}};
+        CHECK(json::parse(R"([["stopped",1]])").get<task_map>() == m);
+    }
+
+    SECTION("other containers are not affected")
+    {
+        const std::vector<std::pair<TaskState, int>> pairs = {{TS_STOPPED, 1}};
+        const std::map<std::string, TaskState> string_keys = {{"a", TS_STOPPED}};
+        const std::map<int, int> int_keys = {{1, 2}};
+        CHECK(json(pairs) == json::parse(R"([["stopped",1]])"));
+        CHECK(json(string_keys) == json::parse(R"({"a":"stopped"})"));
+        CHECK(json(int_keys) == json::parse("[[1,2]]"));
+    }
+
+    SECTION("maps with non-unique keys are still stored as arrays of pairs")
+    {
+        const std::multimap<TaskState, int> mm = {{TS_STOPPED, 1}, {TS_STOPPED, 2}};
+        const std::unordered_multimap<TaskState, int, enum_hash> umm = {{TS_RUNNING, 3}, {TS_RUNNING, 3}};
+        CHECK(json(mm) == json::parse(R"([["stopped",1],["stopped",2]])"));
+        CHECK(json(umm) == json::parse(R"([["running",3],["running",3]])"));
+    }
+
+    SECTION("keys that do not serialize to strings")
+    {
+        const std::map<TaskState, int> null_key = {{TS_INVALID, 1}};
+        const std::map<digit, int> number_key = {{digit::zero, 1}};
+        json j = "unchanged";
+
+        // mapped to null
+        CHECK_THROWS_WITH_AS(j = null_key,
+                             "[json.exception.type_error.302] type must be string, but is null", json::type_error&);
+
+        // mapped to a number
+        CHECK_THROWS_WITH_AS(j = number_key,
+                             "[json.exception.type_error.302] type must be string, but is number", json::type_error&);
+
+#ifndef SKIP_TESTS_FOR_ENUM_SERIALIZATION
+        // enum without NLOHMANN_JSON_SERIALIZE_ENUM
+        const std::map<plain, int> plain_key = {{plain::zero, 1}};
+        CHECK_THROWS_WITH_AS(j = plain_key,
+                             "[json.exception.type_error.302] type must be string, but is number", json::type_error&);
+#endif
+
+        CHECK(j == "unchanged");
+    }
+
+    SECTION("keys that serialize to the same string")
+    {
+        const std::map<color, int> m = {{color::red, 1}, {color::blue, 2}};
+        json j = "unchanged";
+
+        // color::blue is not mapped and falls back to "red"
+        CHECK_THROWS_WITH_AS(j = m,
+                             "[json.exception.type_error.318] duplicate object key 'red'", json::type_error&);
+
+        CHECK(j == "unchanged");
+    }
+}
+
+DOCTEST_CLANG_SUPPRESS_WARNING_POP

tests/src/unit-enum_keyed_maps_default.cpp

@@ -0,0 +1,144 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#include "doctest_compatibility.h"
+
+// This file tests maps with enum keys with the default setting of
+// JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS (or whatever a -D flag sets it to).
+// unit-enum_keyed_maps.cpp tests JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS=1.
+// These tests are not part of unit-conversions.cpp, because that object file
+// is already too big for the MinGW linker of some compilers.
+
+#include <nlohmann/json.hpp>
+using nlohmann::json;
+
+#include <cstddef>
+#include <functional>
+#include <map>
+#include <string>
+#include <unordered_map>
+
+// NLOHMANN_JSON_SERIALIZE_ENUM uses a static std::pair
+DOCTEST_CLANG_SUPPRESS_WARNING_PUSH
+DOCTEST_CLANG_SUPPRESS_WARNING("-Wexit-time-destructors")
+
+enum class cards {kreuz, pik, herz, karo};
+
+// NOLINTNEXTLINE(misc-use-internal-linkage,misc-const-correctness,cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays) - false positive
+NLOHMANN_JSON_SERIALIZE_ENUM(cards,
+{
+    {cards::kreuz, "kreuz"},
+    {cards::pik, "pik"},
+    {cards::herz, "herz"},
+    {cards::karo, "karo"}
+})
+
+enum TaskState // NOLINT(cert-int09-c,readability-enum-initial-value,cppcoreguidelines-use-enum-class)
+{
+    TS_STOPPED,
+    TS_RUNNING,
+    TS_COMPLETED,
+    TS_INVALID = -1,
+};
+
+// NOLINTNEXTLINE(misc-const-correctness,misc-use-internal-linkage,cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays) - false positive
+NLOHMANN_JSON_SERIALIZE_ENUM(TaskState,
+{
+    {TS_INVALID, nullptr},
+    {TS_STOPPED, "stopped"},
+    {TS_RUNNING, "running"},
+    {TS_COMPLETED, "completed"},
+})
+
+enum class strict_cards {kreuz, pik, herz, karo, andere}; // andere not included in mapping
+
+// NOLINTNEXTLINE(misc-use-internal-linkage,misc-const-correctness,cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays) - false positive
+NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(strict_cards,
+{
+    {strict_cards::kreuz, "kreuz"},
+    {strict_cards::pik, "pik"},
+    {strict_cards::herz, "herz"},
+    {strict_cards::karo, "karo"}
+})
+
+namespace
+{
+// std::hash is only required for enums since C++14
+struct enum_hash
+{
+    template<typename T>
+    std::size_t operator()(T t) const noexcept
+    {
+        return static_cast<std::size_t>(t);
+    }
+};
+} // namespace
+
+// see unit-enum_keyed_maps.cpp for JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS=1
+TEST_CASE("maps with enum keys")
+{
+    using task_map = std::map<TaskState, std::string>;
+    using task_umap = std::unordered_map<TaskState, std::string, enum_hash>;
+    using task_gmap = std::map<TaskState, std::string, std::greater<TaskState>>;
+    using nested_map = std::map<cards, std::map<TaskState, int>>;
+    using strict_map = std::map<strict_cards, int>;
+    using int_map = std::map<int, int>;
+    using int_umap = std::unordered_map<int, int>;
+
+    const task_map m = {{TS_STOPPED, "aa"}, {TS_COMPLETED, "bb"}};
+
+#if !JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS
+    SECTION("stored as array of pairs")
+    {
+        CHECK(json(m) == json::parse(R"([["stopped","aa"],["completed","bb"]])"));
+        CHECK(json(task_umap {{TS_RUNNING, "cc"}}) == json::parse(R"([["running","cc"]])"));
+    }
+#endif
+
+    SECTION("read from array of pairs")
+    {
+        CHECK(json::parse(R"([["stopped","aa"],["completed","bb"]])").get<task_map>() == m);
+    }
+
+    SECTION("read from object (#4378)")
+    {
+        const json j = json::parse(R"({"stopped":"aa","completed":"bb"})");
+        CHECK(j.get<task_map>() == m);
+        CHECK(j.get<task_umap>() == task_umap(m.begin(), m.end()));
+        CHECK(j.get<task_gmap>() == task_gmap(m.begin(), m.end()));
+        CHECK(json::parse(R"({"kreuz":{"stopped":1}})").get<nested_map>() == nested_map {{cards::kreuz, {{TS_STOPPED, 1}}}});
+        CHECK(nlohmann::ordered_json::parse(R"({"stopped":"aa","completed":"bb"})").get<task_map>() == m);
+
+        // object keys go through the enum's from_json
+        strict_map sm;
+        CHECK_THROWS_WITH_AS(json::parse(R"({"what?":1})").get_to(sm),
+                             "[json.exception.out_of_range.410] enum value out of range for strict_cards: \"what?\"", json::out_of_range&);
+    }
+
+    SECTION("objects are only read for enum keys")
+    {
+        // built rather than parsed, so that the messages do not gain a byte
+        // range with JSON_DIAGNOSTIC_POSITIONS
+        const json j = {{"1", 2}};
+        int_map im;
+        int_umap ium;
+        CHECK_THROWS_WITH_AS(j.get_to(im),
+                             "[json.exception.type_error.302] type must be array, but is object", json::type_error&);
+        CHECK_THROWS_WITH_AS(j.get_to(ium),
+                             "[json.exception.type_error.302] type must be array, but is object", json::type_error&);
+    }
+
+    SECTION("other types are rejected")
+    {
+        task_map tm;
+        CHECK_THROWS_WITH_AS(json("stopped").get_to(tm),
+                             "[json.exception.type_error.302] type must be array, but is string", json::type_error&);
+    }
+}
+
+DOCTEST_CLANG_SUPPRESS_WARNING_POP