From 8ab8fa9341c27005b3c5d01f03b0b7ce6a53ce84 Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Mon, 5 Oct 2026 08:44:53 +0200
Subject: [PATCH] Fix with_t nav entry and document chaining of the with_*_t
 aliases

Indent the with_t entry in mkdocs.yml so it is listed under basic_json,
explain that the aliases can be chained and work on ordered_json, and
test both, including json::with_object_t<ordered_map> == ordered_json.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---
 docs/mkdocs/docs/api/basic_json/with_t.md | 12 ++++++++++++
 docs/mkdocs/mkdocs.yml                    |  2 +-
 tests/src/unit-udt.cpp                    | 12 ++++++++++++
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/mkdocs/docs/api/basic_json/with_t.md b/docs/mkdocs/docs/api/basic_json/with_t.md
index 9de825746..2e8fee663 100644
--- a/docs/mkdocs/docs/api/basic_json/with_t.md
+++ b/docs/mkdocs/docs/api/basic_json/with_t.md
@@ -96,6 +96,18 @@ with_base_class_t&lt;CustomBaseClass2&gt;
 All other template parameters are kept unchanged, so the resulting type still uses, for instance, the same
 `ObjectType` unless `with_object_t` itself is used.
 
+The aliases are members of every `basic_json` specialization, including [`ordered_json`](../ordered_json.md), and the
+type they produce is again a `basic_json` specialization. They can therefore be chained to replace several template
+parameters at once:
+
+```cpp
+using my_json = nlohmann::json::with_integers_t<int, unsigned int>::with_float_t<float>;
+using my_ordered_json = nlohmann::ordered_json::with_string_t<std::wstring>;
+```
+
+The result is the same type as spelling out all template parameters, so the order of the chained aliases does not
+matter. For instance, `nlohmann::json::with_object_t<nlohmann::ordered_map>` is `nlohmann::ordered_json`.
+
 ## Examples
 
 ??? example
diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml
index 53ea4d19e..e22c35d8d 100644
--- a/docs/mkdocs/mkdocs.yml
+++ b/docs/mkdocs/mkdocs.yml
@@ -232,7 +232,7 @@ nav:
           - 'update': api/basic_json/update.md
           - 'value': api/basic_json/value.md
           - 'value_t': api/basic_json/value_t.md
-- 'with_t': api/basic_json/with_t.md
+          - 'with_t': api/basic_json/with_t.md
       - byte_container_with_subtype:
           - 'Overview': api/byte_container_with_subtype/index.md
           - '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md
diff --git a/tests/src/unit-udt.cpp b/tests/src/unit-udt.cpp
index f5d0ffc1e..8bc04c0ba 100644
--- a/tests/src/unit-udt.cpp
+++ b/tests/src/unit-udt.cpp
@@ -794,6 +794,18 @@ TEST_CASE("with_*_t aliases" * doctest::test_suite("udt"))
           nlohmann::basic_json<nlohmann::ordered_map, std::vector, std::wstring, bool,
           std::int64_t, std::uint64_t, double, std::allocator,
           nlohmann::adl_serializer, std::vector<std::uint8_t>>>::value);
+
+    // the aliases are members of the resulting type, so they can be chained
+    CHECK(std::is_same<json::with_integers_t<int, unsigned int>::with_float_t<float>,
+          nlohmann::basic_json<std::map, std::vector, std::string, bool,
+          int, unsigned int, float, std::allocator,
+          nlohmann::adl_serializer, std::vector<std::uint8_t>>>::value);
+    CHECK(std::is_same<json::with_float_t<float>::with_integers_t<int, unsigned int>,
+          json::with_integers_t<int, unsigned int>::with_float_t<float>>::value);
+
+    // replacing the object type of json with ordered_map yields ordered_json
+    CHECK(std::is_same<json::with_object_t<nlohmann::ordered_map>, nlohmann::ordered_json>::value);
+    CHECK(std::is_same<nlohmann::ordered_json::with_object_t<std::map>, json>::value);
 }
 
 TEST_CASE("different basic_json types conversions")