Merge pull request #3779 from handrews/undef-impdef

Define "undefined" and "implementation-defined" (3.0.4)

Author: lornajane

versions/3.0.4.md

@@ -96,6 +96,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).
 
+##### <a name="undefinedAndImplementationDefinedBehavior"></a>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
@@ -147,7 +160,7 @@ Models are defined using the [Schema Object](#schemaObject), which is an extende
 <a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`.
 OAS uses several known formats to define in fine detail the data type being used.
 However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.
-Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification.
+Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though they are not defined by this specification.
 Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified.
 
 The formats defined by the OAS are: