std::optional<T> direct construction from JSON null throws instead of yielding std::nullopt

[nlohmann]

Description

Constructing or assigning std::optional<T> directly from a JSON null value throws type_error instead of yielding std::nullopt. Only the explicit .get<std::optional<T>>() form works correctly.

Reproduction

#include <nlohmann/json.hpp>
#include <optional>

int main() {
    nlohmann::json j_null;
    
    // Works correctly
    auto opt1 = j_null.get<std::optional<std::string>>();  // → std::nullopt ✓
    
    // Throws type_error 302
    std::optional<std::string> opt2 = j_null;  // ✗ throws
    std::optional<std::string> opt3(j_null);   // ✗ throws (direct-init also fails)
}

Error: [json.exception.type_error.302] type must be string, but is null

Expected behavior

Direct construction/assignment should yield std::nullopt, consistent with .get<std::optional<T>>().

Environment

• Compiler: GCC 16.1.0, Apple Clang 21.0.0
• C++ standard: C++17 and later
• Library version: develop branch

Why this cannot be cleanly fixed

This is a limitation at the C++ language level, not a library bug:

1. std::optional<T> has its own converting constructor that accepts any type constructible from T
2. T (e.g., std::string) is constructible from basic_json via basic_json::operator T()
3. When both constructors are viable, std::optional's own constructor wins overload resolution
4. There is no SFINAE trick to distinguish "being called from inside std::optional's own constructor" from a direct call

A proper fix would require restricting or redesigning basic_json::operator ValueType() (json.hpp:1946-1971), which is relied upon for all ordinary implicit conversions (e.g., std::string s = json_obj;). Such a change would be a breaking change to the core conversion API and belongs in a major-version redesign.

Workaround

Use .get<std::optional<T>>() or .get_to() for std::optional<T> conversions:

auto opt = j_null.get<std::optional<std::string>>();  // → std::nullopt ✓
j_null.get_to(opt);                                     // → std::nullopt ✓

Related

• C++17 std::optional feature not enabled #4864: Original std::optional support issue (now fixed on develop)
• Define roadmap for 4.0.0 #3453: Type-strictness redesign for 4.0 (where a permanent fix could live)

---

Note: This issue was filed by Claude Code to track a limitation separate from #4864.

[nlohmann]

Thanks for the suggestion — the null-handling for direct construction and get<std::optional<T>>() is already covered in #5247, and the docs there (conversions.md) clarify that direct construction/static_cast goes through std::optional<T>'s own converting constructor rather than the serializer, which answers your documentation question.

That left two gaps in the regression matrix you outlined: assignment and get_to(). Opened #5269 to add both.

(This comment was written by Claude Code on Niels's behalf.)