What makes the public API

[nlohmann]

Regarding #3453, I have some thoughts:

The 4.0.0 release will introduce breaking changes with respect to the public API (see https://semver.org/spec/v2.0.0.html). As first step, we should finally document "the public API" in the sense that we are explicit about which aspects we want to guarantee to be stable between minor and patch versions. Even more important, we need to list which aspects are not part of the public API.

Things I could think about are:

• The IDs of thrown exceptions. Rationale: reorganizing the ids can make sense to improve understandability.
• The what() messages of thrown exceptions. Rationale: improved diagnostics should not be prohibited.
• The ABI. Rationale: It's not that we want to break the ABI, but it is very hard to check if the ABI has changed. The guarantee should be that minor and patch releases allow you to compile your existing code without problems.
• Anything in the nlohmann::details namespace. Rationale: We are moving things around constantly. Nobody should rely on such internals.

[falbrechtskirchinger]

we need to list which aspects are not part of the public API.

Things I could think about are:

• The IDs of thrown exceptions. Rationale: reorganizing the ids can make sense to improve understandability.

What is the purpose of the IDs, if I cannot depend on them to be stable and always refer to the same error?

• The what() messages of thrown exceptions. Rationale: improved diagnostics should not be prohibited.
• The ABI. Rationale: It's not that we want to break the ABI, but it is very hard to check if the ABI has changed. The guarantee should be that minor and patch releases allow you to compile your existing code without problems.

Agreed.

• Anything in the nlohmann::details namespace. Rationale: We are moving things around constantly. Nobody should rely on such internals.

And some code in the nlohmann::details namespace should either be explicitly exempted or brought into nlohmann (moved or aliased). I'm thinking specifically about the SAX classes but there may be more.

[nlohmann]

What is the purpose of the IDs, if I cannot depend on them to be stable and always refer to the same error?

The idea is to have something to google to find detailed documentation. But you're right - they are also part of the exception class, so code can rely on them.

[gregmarr]

Agreed that keeping the IDs is good, messages should be able to be changed, things in detail should not be part of the public API, and things in detail that should be public should move out of detail.

[falbrechtskirchinger]

Some type traits should also be considered. At least is_basic_json.

template<typename BasicJsonType, std::enable_if_t<nlohmann::is_basic_json_v<BasicJsonType>, int> = 0>
void to_json(BasicJsonType &j, ...) {
    // ...
}

[nlohmann]

tcmalloc has a nice list of what users must not do, which is related to this discussion: https://github.com/google/tcmalloc/blob/master/docs/compatibility.md

[steffenb7333]

Since in #3657 I was mistaken about nlohmann::json being able to represent "this-is-a-json-document"-type in a library API (except when that library is header-only) I would like to wishlist that for the future.
The cited issue may use a niche style (according to the github code search) declaring the conversion functions extern, but that is to not expose users of that library to some insanity contained in some third-party headers which the implementation and other library parts need to use.
And TBH since nothing was mentioned in the documentation and everything was just working for years that was something I was kind of expecting being able to do up until 3.11.

[T-640]

Regarding ABI stability, could you give a guarantee of sizeof (nlohmann::json) being always the same or at least some approximation of how large it can grow in the future? As of the latest release version the sizeof (nlohmann::json) is 16 bytes long when compiled with MSVC 2019.

If the context matters, I hide the library within implementation details and reserve a fixed amount of memory for nlohmann::json in the interface class to avoid heap allocation. Once I release my project I will not be able to change that, so if nlohmann::json's size grows significantly it will break things down.

This is the only ABI detail of nlohmann::json that really matters, the rest is pretty much irrelevant as it is not a problem to make an abstraction layer over the library.