You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: proposals/003_Clarify-Nullable.md
+28-1
Original file line number
Diff line number
Diff line change
@@ -93,9 +93,10 @@ So the 3.0 spec is ambiguous about null values. It's not clear whether the spec
93
93
### Specific Questions
94
94
95
95
Questions that are not answered by the current specification include the following:
96
+
96
97
* If a schema specifies `nullable: true` and `enum: [1, 2, 3]`, does that schema allow null values? (See [#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900).)
97
98
98
-
* Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any,does `nullable: true` have on an untyped schema?
99
+
* Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any,does `nullable: true` have on an untyped schema?
99
100
100
101
* Can `allOf` be used to define a nullable subtype of non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).)
101
102
@@ -133,6 +134,32 @@ This also solves the issues of alignment with JSON Schema:
133
134
134
135
* It is now clear that `nullable: false`, whether explicit or by default, _does not_ prohibit null values. Consistent with JSON Schema, an empty object allows all values, including `null`.
135
136
137
+
### Questions Answered
138
+
139
+
Following are answers to the questions posed above, assuming the proposed clarification is adopted:
140
+
141
+
#### If a schema specifies `nullable: true` and `enum: [1, 2, 3]`, does that schema allow null values? (See [#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900).)
142
+
143
+
No. The `nullable: true` assertion folds into the `type` assertion, which presumably specifies `integer` or `number`.
144
+
145
+
While the modified `type` now allows `null`, the `enum` does not. Consistent with JSON schema, a value conforms to the schema only if it is valid against _all_ constraints. Any constraint, in this case `enum`, can cause a value to fail validation, even if that value meets all of the other constraints.
146
+
147
+
#### Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any, does `nullable: true` have on an untyped schema?
148
+
149
+
Yes, an untyped schema allows null values, in addition to all other types. `nullable: true` has no effect, because null values are already allowed. And `nullable: false` has no effect because it just leaves the `type` constraint unmodified.
150
+
151
+
#### Can `allOf` be used to define a nullable subtype of non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).)
152
+
153
+
No. Subtypes can add constraints, but not relax them.
154
+
155
+
#### Can `allOf` be used to define a non-nullable subtype of nullable base schema?
156
+
157
+
Yes. The subtype can specify a `type` without `nullable: true`, or can specify `not: {enum: [null]}`.
158
+
159
+
#### What is the correct translation of a nullable schema from OpenAPI into an equivalent JSON Schema?
160
+
161
+
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'`.
162
+
136
163
## Backwards compatibility
137
164
138
165
Spec revisions through 3.0.2 are ambiguous as described above, so any possible clarification has the potential to break existing implementations.
0 commit comments