Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Proposal/Clarify Nullable - Add interactions with default #2058

Merged
merged 17 commits into from
Nov 21, 2019
Merged

Proposal/Clarify Nullable - Add interactions with default #2058

Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
2fe1ec8
Merge pull request #2 from OAI/master
tedepstein Apr 17, 2018
d20a217
Merge remote-tracking branch 'upstream/master'
tedepstein Feb 3, 2019
dacf5c7
Merge remote-tracking branch 'upstream/master'
tedepstein Oct 31, 2019
905dacd
Addressing #1389, and clearing the way for PRs #2046 and #1977. This …
tedepstein Oct 31, 2019
cddbc1e
Corrected table formatting.
tedepstein Oct 31, 2019
a64f81a
Minor tweaks and corrections.
tedepstein Oct 31, 2019
3f25047
Correct Change Log heading.
tedepstein Oct 31, 2019
d58009a
Cleaned up notes about translation to JSON Schema and *Of inheritance…
tedepstein Oct 31, 2019
d1e3d94
Fix Change Log heading in the proposal template.
tedepstein Oct 31, 2019
c58f5bf
Snappy answers to stupid questions.
tedepstein Oct 31, 2019
92fa3a6
Change single-quote 'null' to double-quote "null"
tedepstein Oct 31, 2019
e1c5bc9
Clarified the proposed definition of nullable
tedepstein Nov 1, 2019
63a71b5
Corrected the alternative, heavy-handed interpretation of nullable.
tedepstein Nov 1, 2019
7d94b7c
Added more explicit detail about the primary use case.
tedepstein Nov 1, 2019
e456a98
Added a more complete explanation of the problems created by disallow…
tedepstein Nov 5, 2019
8b766fe
Added issue #2057 - interactions between nullable and default value.
tedepstein Nov 17, 2019
00351bf
Merge remote-tracking branch 'upstream/master' into proposal/clarify-…
tedepstein Nov 17, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions proposals/003_Clarify-Nullable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -87,7 +87,7 @@ components:

UTCDate:
allOf:
$ref: "#/components/schemas/OptionalDate"
- $ref: "#/components/schemas/OptionalDate"
not:
type: string
pattern: "^.*Z.*$"
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down