OpenApi generation creates NullableOf version of structs when null is allowed?

[Markz878]

Not sure if this is a question, bug report or API proposal, but I was pretty surprised when I tried to switch from Swagger to .NET 9 OpenApi generation, and saw that it generates these NullableOfXXX versions of structs if the API has any endpoints where the struct is nullable in input or output objects. What is the purpose of them?

This makes it harder to migrate from Swagger api generation to this, because we have auto-generated the Typescript schema objects and this would need a lot of changes in the app's TS signatures.

I'm not an OpenApi expert, but couldn't this be handled by using oneOf or anyOf?
Or can this be somehow disabled using the OpenApi configuration? This doesn't happen with classes, why are structs handled differently?

[Atulin]

I'm having the same issue. Switching from Swagger generated a bunch of NullableOf, IEnumerableOf, DictionaryOf and other types of this kind, instead of having them inlined. The worst offender are probably enums and collections of primitives. I really don't need NullableOfMyEnum and IEnumerableOfInt64 when just { "$ref": "#/components/schemas/MyEnum", "nullable": true } would suffice.

[ClementCHA]

I'm also having the same issue. Fun part is that, if a model is using nullable Propriety AND an other model using the same propriety but non nullable this time, it will add it twice in the json as NullableOfProperty & Property

[jankaltenecker]

I encountered the same issue. Here's another problem I noticed:
If you add additional metadata (e.g., a description), it results in duplicate schemas as well. For example, I end up with two schemas:

• NullableOfMyEnum (without a description)
• NullableOfMyEnum2 (with a description)

This happens because metadata like nullable, example, and description are applied to the reference itself rather than being inlined.

OpenAPI keywords like oneOf, anyOf, allOf, or not are not used at all. Is there a way to activate this?

I came across this blog post about schema reuse, but the enum inlining example doesn't work for me: https://devblogs.microsoft.com/dotnet/dotnet9-openapi/#customize-schema-reuse

Swashbuckle:

"MyModel": {
  "type": "object",
  "properties": {
    "myEnum": {
      "allOf": [
        {
          "$ref": "#/components/schemas/MyEnum"
        }
      ],
      "description": "Description.",
      "nullable": true,
      "example": "Value1"
    }
  }
},

...

"MyEnum": {
  "enum": [
    "Value1",
    "Value2",
    "Value3"
  ],
  "type": "string"
}

.NET 9:

"MyModel": {
  "type": "object",
  "properties": {
    "myEnum": {
      "$ref": "#/components/schemas/MyEnum"
    }
  }
},

...

"NullableOfMyEnum": {
  "enum": [
    "Value1",
    "Value2",
    "Value3",
    null
  ],
  "nullable": true,
  "example": "Value1"
},
"NullableOfMyEnum2": {
  "enum": [
    "Value1",
    "Value2",
    "Value3",
    null
  ],
  "description": "Description.",
  "nullable": true,
  "example": "Value1"
}

[mikekistler]

tl;dr

Yes. A schema that allows null is different than a schema that does not, so two different schemas are generated. By necessity.

The detailed answer

Swashbuckle also generates different schemas. The difference is really that Swashbuckle attempts to reuse the "base" (non-nullable) schema in the schema for the nullable type. Unfortunately, the way this is done is not technically correct. To explain why, consider this schema:

"MyModel": {
  "type": "object",
  "properties": {
    "myEnum": {
      "allOf": [
        {
          "$ref": "#/components/schemas/MyEnum"
        }
      ],
      "description": "Description.",
      "nullable": true,
      "example": "Value1"
    }
  }
},

And now let's look at how nullable is defined in the OpenAPI specification. Here's the description in the 3.0.4 (most recent and likely the last) point release of the 3.0.x OpenAPI Specification [ref]:

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.

By this description, the nullable keyword in the schema for the MyEnum property has no effect, because type is not explicitly defined within the same Schema Object. Further, because "Other Schema Object constraints retain their defined behavior" and because the MyEnum schema in the allOf does not allow null, this constraint applies to the schema for the MyEnum property.

Aside: the nullable keyword in OpenAPI 3.0.x is an extension of JSON Schema added by OpenAPI and has had to be clarified multiple times in the patch releases of the 3.0 spec.

To my knowledge, there is no technically correct way in OpenAPI 3.0.x to reuse the "base" (non-nullable) schema in the schema for the nullable type. But I believe this will be possible with OpenAPI v3.1, which uses "full JSON Schema". In OpenAPI v3.1 you could write:

    "OptionalAddress": {
      "oneOf": [
        {
          "$ref": "#/definitions/Address"
        },
        {
          "type": "null"
        }
      ]
    }

There is an open issue for adding OpenAPI v3.1 support in ASP.NET - #58619. Please add a thumb's up reaction on that issue if this is important to you.

So what can be done in OpenAPI 3.0.x and .NET 9? One approach could be to avoid generating "nullable" schemas at all. In many cases the "nullability" of a property in a request or response body can be represented as being "optional" -- not in the required properties of the schema. This allows the property to be omitted from the body entirely and the Json deserializer will produce an object with a null value for that property.

This is something you can accomplish with a schema transformer that removes nullable: true from any properties that are not listed in the required keyword of the schema.

builder.Services.AddOpenApi(options =>
{
    options.AddSchemaTransformer((schema, context, cancellationToken) =>
    {
        if (schema.Properties is not null)
        {
            foreach (var property in schema.Properties)
            {
                if (schema.Required?.Contains(property.Key) != true)
                {
                    property.Value.Nullable = false;
                }
            }
        }
        return Task.CompletedTask;
    });
});

Unfortunately this does not handle the case where a nullable property is an enum. I made a couple attempts to fix the enum properties as well but none had the desired outcome. I'll continue to investigate that case but hopefully the above will be helpful to some.

[mikekistler]

After a little more investigation and consultation with @captainsafia I now have an improved transformer that handles the NullableOf cases reported here. These arise when value types are used in nullable an non-nullable forms. In addition, nullable enums have null included in the enum values and this must be removed to allow a single schema for both nullable and non-nullable enums.

The code for this is a little more involved than the transformer I posted in the previous comment, so I will link to an implementation of it in GitHub:

https://github.com/mikekistler/aspnet-transformer-gallery/blob/main/TransformerGallery/Transformers/NullableTransformer.cs

I believe this should be a complete solution but pls post here if there are any remaining problems.