From 24cc6c4b82ded4f88e1e12d35a27bba2f565558a Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 3 May 2024 11:45:48 -0700 Subject: [PATCH 1/2] Define "undefined" and "implementation-defined" (3.2.0) Undefined means "don't use this even if it seems to work, as there are cases where it won't." Implementation-defined means "this isn't portable or interoperable, but it is still correct." Signed-off-by: Henry H. Andrews --- versions/3.2.0.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/versions/3.2.0.md b/versions/3.2.0.md index cfb5555e37..67e8d80bc9 100644 --- a/versions/3.2.0.md +++ b/versions/3.2.0.md @@ -99,6 +99,19 @@ Some examples of possible media type definitions: The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). +##### Undefined and Implementation-Defined Behavior + +This specification deems certain situations to have either _undefined_ or _implementation-defined_ behavior. + +Behavior described as _undefined_ is likely, at least in some circumstances, to contradict the specification. +This description is used when detecting the contradiction is impossible or impractical. +Implementations MAY support undefined scenarios for historical reasons, including ambiguous text in prior versions of the specification. +This support might produce correct outcomes in many cases, but relying on it is NOT RECOMMENDED as there is no guarantee that it will work across all tools or with future specification versions, even if those versions are otherwise strictly compatible with this one. + +Behavior described as _implementation-defined_ allows implementations to choose which of several different-but-compliant approaches to a requirement to implement. +This documents ambiguous requirements that API description authors are RECOMMENDED to avoid in order to maximize interoperability. +Unlike undefined behavior, it is safe to rely on implementation-defined behavior if _and only if_ it can be guaranteed that all relevant tools support the same behavior. + ## Specification ### Versions From 6e7654598c57e4867acc3d9c6239ca3bd691b750 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 8 May 2024 07:39:41 -0700 Subject: [PATCH 2/2] Review feedback from notEthan and ralfhandl Co-authored-by: Ralf Handl --- versions/3.2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.2.0.md b/versions/3.2.0.md index 67e8d80bc9..6379948e99 100644 --- a/versions/3.2.0.md +++ b/versions/3.2.0.md @@ -103,7 +103,7 @@ The available status codes are defined by [RFC7231](https://tools.ietf.org/html/ This specification deems certain situations to have either _undefined_ or _implementation-defined_ behavior. -Behavior described as _undefined_ is likely, at least in some circumstances, to contradict the specification. +Behavior described as _undefined_ is likely, at least in some circumstances, to result in outcomes that contradict the specification. This description is used when detecting the contradiction is impossible or impractical. Implementations MAY support undefined scenarios for historical reasons, including ambiguous text in prior versions of the specification. This support might produce correct outcomes in many cases, but relying on it is NOT RECOMMENDED as there is no guarantee that it will work across all tools or with future specification versions, even if those versions are otherwise strictly compatible with this one.