Proposal/Clarify Nullable - Add interactions with default (#2058)

* Addressing #1389, and clearing the way for PRs #2046 and #1977. This adds a formal proposal to clarify the semantics of nullable, providing the necessary background and links to related resources.

* Corrected table formatting.

* Minor tweaks and corrections.

* Correct Change Log heading.

* Cleaned up notes about translation to JSON Schema and *Of inheritance semantics.

* Fix Change Log heading in the proposal template.

* Snappy answers to stupid questions.

* Change single-quote 'null' to double-quote "null"

Thanks, @handrews for the review.

* Clarified the proposed definition of nullable

Somehow in our collaborative editing, we neglected to state that `nullable` adds `"null"` to the set of allowed types. We just said that it "expands" the `type` value, but didn't state the obvious (to us) manner of said expansion. Correcting that oversight in this commit.

* Corrected the alternative, heavy-handed interpretation of nullable.

* Added more explicit detail about the primary use case.

* Added a more complete explanation of the problems created by disallowing nulls by default.

* Added issue #2057 - interactions between nullable and default value.

Author: tedepstein

proposals/003_Clarify-Nullable.md

@@ -10,7 +10,7 @@
 |Review Manager |TBD|
 |Status |Proposal|
 |Implementations |N/A|
-|Issues | [1900](https://github.com/OAI/OpenAPI-Specification/issues/1900), [1368](https://github.com/OAI/OpenAPI-Specification/issues/1368), [1389](https://github.com/OAI/OpenAPI-Specification/issues/1389), [1957](https://github.com/OAI/OpenAPI-Specification/pull/1957), [2046](https://github.com/OAI/OpenAPI-Specification/pull/2046), [1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957) |
+|Issues | [1900](https://github.com/OAI/OpenAPI-Specification/issues/1900), [1368](https://github.com/OAI/OpenAPI-Specification/issues/1368), [1389](https://github.com/OAI/OpenAPI-Specification/issues/1389), [1957](https://github.com/OAI/OpenAPI-Specification/pull/1957), [2046](https://github.com/OAI/OpenAPI-Specification/pull/2046), [1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957), [2057](https://github.com/OAI/OpenAPI-Specification/issues/2057)|
 |Previous Revisions |N/A |
 
 ## Change Log
@@ -87,7 +87,7 @@ components:
 
     UTCDate:
       allOf:
-        $ref: "#/components/schemas/OptionalDate"
+      - $ref: "#/components/schemas/OptionalDate"
       not:
         type: string
         pattern: "^.*Z.*$"
@@ -140,6 +140,8 @@ Questions that are not answered by the current specification include the followi
 
 * What is the correct translation of a nullable schema from OpenAPI into an equivalent JSON Schema?
 
+* Is `null` allowed as the `default` value of a nullable schema? (See [#2057](https://github.com/OAI/OpenAPI-Specification/issues/2057).)
+
 ## Proposed solution
 
 We propose to clarify the 3.0 specification in the next patch release, to resolve these questions and align OpenAPI's Schema Object with JSON Schema's well-defined, constraint-based semantics.
@@ -196,6 +198,12 @@ Yes. The subtype can specify a `type` without `nullable: true`, or can specify `
 
 A nullable type should translate into a type array with two string elements: the name of the type specified in the Schema Object, and `"null"`.
 
+####  Is `null` allowed as the `default` value of a nullable schema? (See [#2057](https://github.com/OAI/OpenAPI-Specification/issues/2057).)
+
+Yes. For example, a Schema Object with `"type" : "string", "nullable" : true` would translate to a JSON Schema with `"type" : ["string", "null"]`. That schema permits `"default" : null`, even with the [strict typing rule](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#properties) specified by OpenAPI 3.0:
+
+> default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`.
+
 ## Backwards compatibility
 
 Spec revisions through 3.0.2 are ambiguous as described above, so any possible clarification has the potential to break existing implementations.