Regression: broken nullability after update to v3.9.0

[bkoelman]

Describe the bug
After updating from v3.7.0 to v3.9.0, the nullable property disappears when writing an OpenAPI 3.0 document.

Repro steps

using Microsoft.OpenApi;

var metaSchema = new OpenApiSchema
{
 Type = JsonSchemaType.Object,
 AdditionalProperties = new OpenApiSchema
 {
 Type = JsonSchemaType.Null
 }
};

var baseSchema = new OpenApiSchema
{
 Type = JsonSchemaType.Object,
 Id = "base",
 Properties = new Dictionary<string, IOpenApiSchema>
 {
 ["id"] = new OpenApiSchema
 {
 Type = JsonSchemaType.String
 }
 }
};

var derivedSchema = new OpenApiSchema
{
 Type = JsonSchemaType.Null,
 AllOf = new List<IOpenApiSchema>
 {
 new OpenApiSchemaReference(baseSchema.Id)
 },
 Properties = new Dictionary<string, IOpenApiSchema>
 {
 ["kind"] = new OpenApiSchema
 {
 Type = JsonSchemaType.String
 }
 }
};

var doc = new OpenApiDocument();
doc.Components ??= new OpenApiComponents();
doc.Components.Schemas ??= new Dictionary<string, IOpenApiSchema>();
doc.Components.Schemas.Add("meta", metaSchema);
doc.Components.Schemas.Add("base", baseSchema);
doc.Components.Schemas.Add("derived", derivedSchema);

var result = await doc.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_0);
Console.WriteLine(result);

Using v3.7.0, this prints:

{
 "openapi": "3.0.4",
 "info": { },
 "paths": { },
 "components": {
 "schemas": {
 "meta": {
 "type": "object",
 "additionalProperties": {
 "nullable": true
 }
 },
 "base": {
 "type": "object",
 "properties": {
 "id": {
 "type": "string"
 }
 }
 },
 "derived": {
 "allOf": [
 {
 "$ref": "#/components/schemas/base"
 }
 ],
 "properties": {
 "kind": {
 "type": "string"
 }
 },
 "nullable": true
 }
 }
 }
}

Using v3.9.0, this prints:

{
 "openapi": "3.0.4",
 "info": { },
 "paths": { },
 "components": {
 "schemas": {
 "meta": {
 "type": "object",
 "additionalProperties": {
 "enum": [
 null
 ]
 }
 },
 "base": {
 "type": "object",
 "properties": {
 "id": {
 "type": "string"
 }
 }
 },
 "derived": {
 "allOf": [
 {
 "$ref": "#/components/schemas/base"
 }
 ],
 "properties": {
 "kind": {
 "type": "string"
 }
 }
 }
 }
 }
}

Screenshots/Code Snippets
View of the diff:

Originally reported at: domaindrivendev/Swashbuckle.AspNetCore#4065

[martincostello]

Changes in 3.8.0 also created a similar but different effect as can be seen by the change in our snapshots here: domaindrivendev/Swashbuckle.AspNetCore@cc099e8.

[baywet]

Hey everyone,
Thank you for using the SDK and for reaching out.

This keyword only takes effect if type is explicitly defined within the same Schema Object

From v3.0 specification

In the examples shared above:

• was removed from the derived component schema (which has no type property, and makes the keyword unapplicable).
• was "transformed" to enum null on the meta component schema additionalProperties. (so it's applicable because that schema doesn't have a type)

While I understand this is disruptive to snapshot tests, I believe this is the more "correct" behaviour (least transformations applied during serialization, do not serialize a keywork that's unapplicable, try to maintain the semantics when possible). See #2358 for more context.

Let me know if you have any additional comments or questions.

CC @Youssef1313

[bkoelman]

This is basically #2342 (comment) again, which I fixed in #2358. TLDR: The 3.0 spec changed in 3.0.3, focused on making validators happy, not taking into account the merging of allOf subtrees into a generated class.

The meta schema represents a free-format JSON subtree, which models JSON:API meta. Interpreting the spec as "nullable not allowed without type" means a free-format structure can no longer be expressed in OpenAPI: additionalProperties must not be constrained to objects, because meta properties can also be (nullable) strings, arrays, etc.

I suppose it would be possible to adapt Swashbuckle and other consumers of this library to explicitly set Type=Object, but that results in a different openapi.json file, which we already know NSwag can't handle. Therefore, I still believe the better choice is to remain flexible about the spec interpretation:

This keyword only takes effect if type is explicitly defined within the same Schema Object.

That doesn't mean it is forbidden to emit nullable: true; it just means that document consumers should ignore it when no type is present.