From 68838a39e69e4350fb6cb5c45c64e1dc6deee84a 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.1.1) 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." --- versions/3.1.1.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 314c950074..953805e2f5 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.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. Status codes SHOULD be selected from the available status codes registered 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 baab867e9f1048a2ef500c9aa547b26a6a9d504a 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.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 953805e2f5..00f035fbfe 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -103,7 +103,7 @@ Status codes SHOULD be selected from the available status codes registered in th 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.