Handling of nullable for $ref in OpenAPI 3.0
See original GitHub issueI have an API that needs to differentiate between properties that are T | null
and T | undefined
. It looks like using nullable
works for basic types but is ignored for $ref
:
schemas:
TestObject:
type: object
properties:
stringMaybeUndefined:
type: string
stringMaybeNullA:
type: string
nullable: true
stringMaybeNullB:
anyOf:
- type: string
nullable: true
otherObjectMaybeUndefined:
$ref: "#/components/schemas/OtherObject"
otherObjectMaybeNullA:
$ref: "#/components/schemas/OtherObject"
nullable: true
otherObjectMaybeNullB:
anyOf:
- $ref: "#/components/schemas/OtherObject"
nullable: true
required:
- stringMaybeNullA
- stringMaybeNullB
- otherObjectMaybeNullA
- otherObjectMaybeNullB
OtherObject:
type: object
Generates:
export interface TestObject {
stringMaybeUndefined?: string;
stringMaybeNullA?: string | null;
stringMaybeNullB?: string;
otherObjectMaybeUndefined?: OtherObject;
otherObjectMaybeNullA?: OtherObject;
otherObjectMaybeNullB?: OtherObject;
}
Note: The OpenAPI 3.1 syntax
oneOf:
- $ref: "#/components/schemas/OtherObject"
- type: 'null'
works, but I’m forced to use OpenAPI 3.0 because of constraints from other tooling.
Can this be achieved somehow?
Edit, relevant resources:
- https://github.com/OAI/OpenAPI-Specification/issues/1368
- https://github.com/OAI/OpenAPI-Specification/blob/master/proposals/003_Clarify-Nullable.md
If I interpret these (long) discussions correctly, at least the allOf
wrapping should work?
Issue Analytics
- State:
- Created 3 years ago
- Comments:7 (4 by maintainers)
Top Results From Across the Web
openapi - How to specify a property can be null or a reference ...
to specify a property value can be null, however, $ref replaces the object with what it references, so it would appear any use...
Read more >How to manage nullable properties - Jane - Read the Docs
By doing this, any property of your schema will be considered nullable. ... OpenAPI v3 still does not support null type but added...
Read more >How to specify a property can be null or a reference
This is a real-world problem for my project: complex objects reference other objects, but in some cases, the referenced object is NULL, i.e,...
Read more >Using Optional and Nullable Properties in API Requests
OpenAPI supports values of data types to be null. To specify, one can use the “nullable: true” property while defining a data type...
Read more >OpenAPI Specification - Version 3.0.3 - Swagger
In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions....
Read more >
Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free
Top Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
Should be fixed in release 1.6.3
If someone still have same problems, please reopen issue and attach part of swagger schema
Looks good, thanks for the super fast maintenance!