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
{{ message }}
Repository navigation
Downcast oneOf null to nullable with OpenAPI 3.0 #2629
ASP.NET Core 10 OpenApi generates "oneOf" schemas for nullable references for OpenApi 3.1 which is structurely different than what would be idiomatic in OpenAPI 3.0
Probably a pattern of "anyOf" with a { "type": "null" } should also be recognized.
OpenAPI 3.1 "oneOf" with multiple schemas AND a null schema would be required to be downcasted to a "oneOf" without the { "type": "null" } and the nullable: true
Can you please provide more context on why you think that having the nullable:true on the "root schema" is better in any way than having it as a oneOf entry?
Right, but this has nothing to do with the location (root or anyOf entry) of the value, but rather the fact that the type keyword is missing when downcasting.
And no, even though semantically it "looks like" we can do permutations like you just shared in your latest edit, this is not how the JSON schema specification works. Each keyword is evaluated independently.
The downcast should set a type when inserting a nullable:true schema. Where it becomes tricky is that the type that must be set depends on the other entry (object, number, etc...)
The moment we add "type": "object" to the { nullable: true } an empty object { } becomes valid as well, as it would match the object without properties in the oneOf.
On the $ref resolving and composition, I think it depends on how you interpret the following
The OpenAPI Specification allows combining and extending model definitions using the allOf keyword of JSON Schema, in effect offering model composition. allOf takes an array of object definitions that are validated independently but together compose a single object.
From https://spec.openapis.org/oas/v3.0.4.html#composition-and-inheritance-polymorphism
The moment we add "type": "object" to the { nullable: true } an empty object { } becomes valid as well
This is already the case because of the type: object in the person schema in your example. It only becomes a problem when properties are required.
I think it depends on how you interpret the following
allOf takes an array of object definitions that are validated independently
This clearly calls out that each entry is evaluated independently.
but together compose a single object.
This calls out the JSON instance (not the JSON schema, the payload object in memory) is ultimately a single object to which all the validations are applied.
As for the swagger quote, this IS NOT the specification, and it's not normative (but it can sometimes be useful).
In 3.X, all references are OpenAPI references, and do not define any additional fields/overridable keywords.
From 3.1 and onwards, JSON schema references are defined from the JSON schema specification and other references are OpenAPI references, which support summary, description, and extension fields (x-). The consequence of that is that JSON Schema references support overriding keywords in the reference (but nullable does not exist in that version). I'm mentioning all of that to clarify defining nullable:true in the same schema object would never be a valid option.
Ultimately, downcasting is going to be lossy in a number of different subtle ways. Which is why using the latest version of the specification is always going to guarantee a greater fidelity with the object model (at least, this is how this library is designed).
Since using nullable: true is not valid without the type keyword, my suggestion here is to "pick" the type of one of the sister entries as an "improvement" over the current downcast behaviour. And yet, that might still be a bit leaky in the context of required properties, but it'll be better than emitting a document that is semantically invalid.
Thoughts?
A true value adds "null" to the allowed type specified by the type keyword, only if type is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of null as a value. A false value leaves the specified or default type unmodified. The default value is false.
This keyword only takes effect if type is explicitly defined within the same Schema Object. A true value indicates that both null values and values of the type specified by type are allowed. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of null as a value. A false value leaves the specified or default type unmodified. The default value is false.
Interestingly, the wording was updated between 3.0.3 and 3.0.4 to more explicitly call out the required-ness of the peer type keyword between those two minor versions. This is probably where some of the "bad downcast behaviour" originates from since I believe the work was started under 3.0.3
Or emitting a oneOf for each "type" with nullable: true. But that would open up the type.
I don't think there is a perfect solution.
I would favor the one where we don't open up the type, with the downside of "mishandling" oneOf with different types. Mainly because it's a more common pattern which will be better recognized by existing tools. Examples of packages which emit the nullable one up (NSwag, Swashbuckle, and as you shared TypeSpec).
This issue has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 4 days. It will be closed if no further activity occurs within 3 days of this comment.
Activity
martincostello commentedon Dec 4, 2025
We recently had a very similar issue in Swashbuckle: domaindrivendev/Swashbuckle.AspNetCore#3683
baywet commentedon Dec 8, 2025
Hi Sjoerd van der Meer (@desjoerd)
Thank you for using the SDK and for reaching out.
Can you please provide more context on why you think that having the nullable:true on the "root schema" is better in any way than having it as a oneOf entry?
desjoerd commentedon Dec 8, 2025
According to the openapi 3.0.4 specification https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-20
nullable: trueonly takes into effect whentypeis specified. Which makes it do nothing in the current situation.Edit:
You would expect that the below is invalid as well:
But $ref is a full replacement in OpenAPI 3.0.4 and
allOfmerges all schemas and makes the contact schema be something like:Becomes
Becomes
baywet commentedon Dec 8, 2025
Thank you for the additional information.
Right, but this has nothing to do with the location (root or anyOf entry) of the value, but rather the fact that the type keyword is missing when downcasting.
And no, even though semantically it "looks like" we can do permutations like you just shared in your latest edit, this is not how the JSON schema specification works. Each keyword is evaluated independently.
The downcast should set a type when inserting a nullable:true schema. Where it becomes tricky is that the type that must be set depends on the other entry (object, number, etc...)
Thoughts?
desjoerd commentedon Dec 8, 2025
The moment we add
"type": "object"to the{ nullable: true }an empty object{ }becomes valid as well, as it would match the object without properties in the oneOf.On the $ref resolving and composition, I think it depends on how you interpret the following
And
baywet commentedon Dec 8, 2025
This is already the case because of the type: object in the person schema in your example. It only becomes a problem when properties are required.
This clearly calls out that each entry is evaluated independently.
This calls out the JSON instance (not the JSON schema, the payload object in memory) is ultimately a single object to which all the validations are applied.
I don't think there's any room for other interpretation, like "we can now do schema transformation for what we think is semantically equivalent schemas". Case in point there was an attempt to normalize such transformation at some point (as a separate specification).
As for the swagger quote, this IS NOT the specification, and it's not normative (but it can sometimes be useful).
In 3.X, all references are OpenAPI references, and do not define any additional fields/overridable keywords.
From 3.1 and onwards, JSON schema references are defined from the JSON schema specification and other references are OpenAPI references, which support summary, description, and extension fields (x-). The consequence of that is that JSON Schema references support overriding keywords in the reference (but nullable does not exist in that version). I'm mentioning all of that to clarify defining nullable:true in the same schema object would never be a valid option.
Ultimately, downcasting is going to be lossy in a number of different subtle ways. Which is why using the latest version of the specification is always going to guarantee a greater fidelity with the object model (at least, this is how this library is designed).
Since using nullable: true is not valid without the type keyword, my suggestion here is to "pick" the type of one of the sister entries as an "improvement" over the current downcast behaviour. And yet, that might still be a bit leaky in the context of required properties, but it'll be better than emitting a document that is semantically invalid.
Thoughts?
baywet commentedon Dec 8, 2025
3.0.3
3.0.4
Interestingly, the wording was updated between 3.0.3 and 3.0.4 to more explicitly call out the required-ness of the peer type keyword between those two minor versions. This is probably where some of the "bad downcast behaviour" originates from since I believe the work was started under 3.0.3
28 remaining items
desjoerd commentedon Dec 10, 2025
Maybe it's an option to do the same as the "type" property. Take the first one which isn't null. Or omit the "type".
https://github.com/microsoft/OpenAPI.NET/blob/main/src%2FMicrosoft.OpenApi%2FModels%2FOpenApiSchema.cs#L789
Or emitting a oneOf for each "type" with
nullable: true. But that would open up the type.I don't think there is a perfect solution.
I would favor the one where we don't open up the type, with the downside of "mishandling" oneOf with different types. Mainly because it's a more common pattern which will be better recognized by existing tools. Examples of packages which emit the nullable one up (NSwag, Swashbuckle, and as you shared TypeSpec).
baywet commentedon Dec 10, 2025
Is this something you'd like to submit a pull request for provided some guidance?
Start from and target the support/v2 branch. This way the roll over to v3 will be easier.
microsoft-github-policy-service commentedon Dec 15, 2025
This issue has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 4 days. It will be closed if no further activity occurs within 3 days of this comment.
Merge branch 'fix/support-v2/microsoftgh-2629' of https://github.com/…
Merge pull request #2645 from desjoerd/fix/support-v2/gh-2629