deploy: e4e7d657ef

api/macros/json_brace_init_copy_semantics.md

@@ -50,9 +50,11 @@ The default value is `0` (disabled — existing behavior is preserved).
     ```
 
     Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one
-    element, and a single `[string, value]` pair such as `{{"key", "value"}}`, which still creates an object, are not
-    affected. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes
-    `[5]`.
+    element, and a single `[string, value]` pair *written as a braced list*, such as `{{"key", "value"}}`, which still
+    creates an object, are not affected. This exception is based on how the pair is written, not on the shape of its
+    value: an existing JSON value that happens to be a two-element array with a string as its first element, such as
+    `json arr = {"key", 42};`, is still copied by `json j{arr};` rather than turned into an object. The library's own
+    conversions are not affected either: for example, `std::tuple<int>{5}` still becomes `[5]`.
 
 !!! note "ABI compatibility"
 

api/macros/json_brace_init_copy_semantics/index.md

@@ -43,7 +43,7 @@ json j2 = {"text"};  // "text", not ["text"]
 json j3 = {{1, 2}};  // [1,2], not [[1,2]]
 ```
 
-Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one element, and a single `[string, value]` pair such as `{{"key", "value"}}`, which still creates an object, are not affected. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes `[5]`.
+Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one element, and a single `[string, value]` pair *written as a braced list*, such as `{{"key", "value"}}`, which still creates an object, are not affected. This exception is based on how the pair is written, not on the shape of its value: an existing JSON value that happens to be a two-element array with a string as its first element, such as `json arr = {"key", 42};`, is still copied by `json j{arr};` rather than turned into an object. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes `[5]`.
 
 ABI compatibility
 

community/contribution_guidelines/index.md

@@ -152,6 +152,8 @@ We take pride in the library being used by [numerous customers across various in
 - Changing access specifiers.
 - Changing default arguments.
 
+What is and is not covered by this guarantee is described in the [roadmap](https://json.nlohmann.me/community/roadmap/#api-stability).
+
 Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.
 
 Breaking changes may be introduced when they are guarded with a feature macro such as [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/) which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.

community/roadmap.md

@@ -25,9 +25,7 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js
 
 ## What the project will not do
 
-- **Break the public API of version 3.x.** See the
-  [contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#break-the-public-api)
-  for what counts as a breaking change.
+- **Break the public API of version 3.x.** See [API stability](#api-stability) for what this covers.
 - **Require a newer C++ standard than C++11.**
 - **Break JSON conformance** or enable non-standard extensions by default.
 - **Add dependencies** or require a build step. The library remains header-only, and the single header
@@ -35,6 +33,32 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js
 - **Trade simplicity for speed or memory efficiency.** Performance improvements are welcome, but the library is not
   meant to compete with the fastest JSON libraries, see [Design goals](../home/design_goals.md).
 
+## API stability
+
+Releases follow [semantic versioning](https://semver.org): a minor or patch release of version 3.x does not break code
+that uses the public API. In particular, a 3.x release does not:
+
+- change the signature of a function (its parameter types, return type, number of parameters, or the const-ness of a
+  member function);
+- remove or rename a function or class;
+- change which exceptions a function throws, or the [exception ids](../home/exceptions.md);
+- change access specifiers or default arguments.
+
+Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are
+documented in the [release notes](../home/releases.md).
+
+The following are **not** part of the public API and may change in any release, including patch releases:
+
+- The text of exception messages returned by `what()`. Use the [exception id](../home/exceptions.md) to tell errors
+  apart.
+- The ABI, including `sizeof(basic_json)` and the memory layout of its values. Recompile your code when you upgrade the
+  library. The [versioned inline namespace](../features/namespace.md) turns mixing versions into a link error.
+- Everything in namespace `nlohmann::detail`, and macros and type traits that are not documented in the
+  [API reference](../api/basic_json/index.md).
+
+Changes that would break the public API are only added behind a macro whose default keeps the 3.x behavior, see
+[Version 4.0](#version-40).
+
 ## Version 4.0
 
 There is no release date for version 4.0 yet. Proposals that need a major version, for instance stricter type

community/roadmap/index.md

@@ -14,12 +14,31 @@ This page describes what the project intends to do, and what it does not intend
 
 ## What the project will not do
 
-- **Break the public API of version 3.x.** See the [contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#break-the-public-api) for what counts as a breaking change.
+- **Break the public API of version 3.x.** See [API stability](#api-stability) for what this covers.
 - **Require a newer C++ standard than C++11.**
 - **Break JSON conformance** or enable non-standard extensions by default.
 - **Add dependencies** or require a build step. The library remains header-only, and the single header `json.hpp` remains a complete distribution.
 - **Trade simplicity for speed or memory efficiency.** Performance improvements are welcome, but the library is not meant to compete with the fastest JSON libraries, see [Design goals](https://json.nlohmann.me/home/design_goals/index.md).
 
+## API stability
+
+Releases follow [semantic versioning](https://semver.org): a minor or patch release of version 3.x does not break code that uses the public API. In particular, a 3.x release does not:
+
+- change the signature of a function (its parameter types, return type, number of parameters, or the const-ness of a member function);
+- remove or rename a function or class;
+- change which exceptions a function throws, or the [exception ids](https://json.nlohmann.me/home/exceptions/index.md);
+- change access specifiers or default arguments.
+
+Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are documented in the [release notes](https://json.nlohmann.me/home/releases/index.md).
+
+The following are **not** part of the public API and may change in any release, including patch releases:
+
+- The text of exception messages returned by `what()`. Use the [exception id](https://json.nlohmann.me/home/exceptions/index.md) to tell errors apart.
+- The ABI, including `sizeof(basic_json)` and the memory layout of its values. Recompile your code when you upgrade the library. The [versioned inline namespace](https://json.nlohmann.me/features/namespace/index.md) turns mixing versions into a link error.
+- Everything in namespace `nlohmann::detail`, and macros and type traits that are not documented in the [API reference](https://json.nlohmann.me/api/basic_json/index.md).
+
+Changes that would break the public API are only added behind a macro whose default keeps the 3.x behavior, see [Version 4.0](#version-40).
+
 ## Version 4.0
 
 There is no release date for version 4.0 yet. Proposals that need a major version, for instance stricter type conversions, are collected in issue [#3453](https://github.com/nlohmann/json/issues/3453).

features/binary_formats/cbor.md

@@ -131,6 +131,7 @@ The library maps CBOR types to JSON value types as follows:
 | Byte string            | binary          | 0x59       |
 | Byte string            | binary          | 0x5A       |
 | Byte string            | binary          | 0x5B       |
+| Byte string            | binary          | 0x5F       |
 | UTF-8 string           | string          | 0x60..0x77 |
 | UTF-8 string           | string          | 0x78       |
 | UTF-8 string           | string          | 0x79       |
@@ -156,6 +157,9 @@ The library maps CBOR types to JSON value types as follows:
 | Single-Precision Float | number_float    | 0xFA       |
 | Double-Precision Float | number_float    | 0xFB       |
 
+Indefinite-length UTF-8 strings (0x7F) and byte strings (0x5F) are supported. Each chunk must be a definite-length
+string of the same major type, as required by [RFC 8949, Section 3.2.3](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.2.3).
+
 !!! warning "Incomplete mapping"
 
     The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors:

features/binary_formats/cbor/index.md

@@ -145,6 +145,7 @@ The library maps CBOR types to JSON value types as follows:
 | Byte string            | binary          | 0x59       |
 | Byte string            | binary          | 0x5A       |
 | Byte string            | binary          | 0x5B       |
+| Byte string            | binary          | 0x5F       |
 | UTF-8 string           | string          | 0x60..0x77 |
 | UTF-8 string           | string          | 0x78       |
 | UTF-8 string           | string          | 0x79       |
@@ -170,6 +171,8 @@ The library maps CBOR types to JSON value types as follows:
 | Single-Precision Float | number_float    | 0xFA       |
 | Double-Precision Float | number_float    | 0xFB       |
 
+Indefinite-length UTF-8 strings (0x7F) and byte strings (0x5F) are supported. Each chunk must be a definite-length string of the same major type, as required by [RFC 8949, Section 3.2.3](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.2.3).
+
 Incomplete mapping
 
 The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors: