diff --git a/versions/3.2.0.md b/versions/3.2.0.md index cfb5555e37..6379948e99 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 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. + +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