Skip to content

Downcast oneOf null to nullable with OpenAPI 3.0 #2629

Closed

Description

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

OpenAPI 3.1

"contact": 
{
  "oneOf": 
  [
    {
      "type": "null"
    },
    {
      "$ref": "#/components/schemas/Person"
    }
  ]
}

When downcasting this to OpenAPI 3.0 we get

"contact": 
{
  "oneOf": 
  [
    {
      "nullable": true
    },
    {
      "$ref": "#/components/schemas/Person"
    }
  ]
}

This is incorrect as { "nullable": true } does not refer to a base schema.

The pattern of "oneOf" with OpenAPI 3.1 should be downcasted to the following:

"contact":
{
  "allOf":
  {
    "$ref": "#/components/schemas/Person"
  },
  "nullable": true
}

Remarks:

  • 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

Activity

  1. martincostello commented on Dec 4, 2025

    @martincostello
    Contributor

    We recently had a very similar issue in Swashbuckle: domaindrivendev/Swashbuckle.AspNetCore#3683

  2. baywet commented on Dec 8, 2025

    @baywet
    Member

    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?

  3. desjoerd commented on Dec 8, 2025

    @desjoerd
    ContributorAuthor

    According to the openapi 3.0.4 specification https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-20 nullable: true only takes into effect when type is specified. Which makes it do nothing in the current situation.

    Edit:
    You would expect that the below is invalid as well:

    "contact":
    {
      "allOf":
      {
        "$ref": "#/components/schemas/Person"
      },
      "nullable": true
    }

    But $ref is a full replacement in OpenAPI 3.0.4 and allOf merges all schemas and makes the contact schema be something like:

    "contact":
    {
      "allOf":
      {
        "$ref": "#/components/schemas/Person"
      },
      "nullable": true
    },
    "Person": {
      "type": "object",
      "properties": {
        "firstName": { "type": "string" }
      }
    }

    Becomes

    "contact":
    {
      "allOf":
      {
        "type": "object",
        "properties": {
          "firstName": { "type": "string" }
        },
      },
      "nullable": true
    },
    ...

    Becomes

    "contact":
    {
      "type": "object",
      "properties": {
        "firstName": { "type": "string" }
      },
      "nullable": true
    },
    ...
  4. baywet commented on Dec 8, 2025

    @baywet
    Member

    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?

  5. desjoerd commented on Dec 8, 2025

    @desjoerd
    ContributorAuthor

    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.

    "contact": 
    {
      "oneOf": 
      [
        {
          "type": "object",
          "nullable": true
        },
        {
          "$ref": "#/components/schemas/Person"
        }
      ]
    }
    ...

    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

    And

    Any sibling elements of a $ref are ignored. This is because $ref works by replacing itself and everything on its level with the definition it is pointing at.
    From https://swagger.io/docs/specification/v3_0/using-ref/#considerations

  6. baywet commented on Dec 8, 2025

    @baywet
    Member

    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.

    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?

  7. baywet commented on Dec 8, 2025

    @baywet
    Member

    3.0.3

    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.

    3.0.4

    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

  8. 28 remaining items

  9. desjoerd commented on Dec 10, 2025

    @desjoerd
    ContributorAuthor

    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).

  10. baywet commented on Dec 10, 2025

    @baywet
    Member

    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.

  11. microsoft-github-policy-service commented on Dec 15, 2025

    @microsoft-github-policy-service
    Contributor

    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.

  12. added a commit that references this issue on Dec 17, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    type:questionAn issue that's a question

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions