nullable declaration is not working correctly for reference types

[ahokkonen]

Seems like nullable field declaration for reference types is not valid and during code generation property stays as non-nullable despite "nullable": true.

Example from icarMetaType.json:

    "created": {
      "$ref": "../types/icarDateTimeType.json",
      "nullable": true
    },

non-nullable date type gets generated as a result.
Not sure if this is a generator issue or invalid OpenAPI markup for these kind on declaration. It look like valid way of defining nullable reference type would be:

OpenAPI 3.0

"created": {
    "nullable": true,
    "allOf": [
        { "$ref": "../types/icarDateTimeType.json" }
    ]
}

OpenAPI 3.1

"created": {
    "anyOf": [
        { "type": "null" },
        { "$ref": "../types/icarDateTimeType.json" }
    ]
}

I haven't tested that myself yet.

[AndreasSchultzGEA]

Our generating-process seems to cover this correctly:
@ApiModelProperty(required = true, value = "udt:DateTimeType | A particular point in the progression of time together with relevant supplementary information.") @NotNull @Valid public OffsetDateTime getModified() { return modified; }

vs
@ApiModelProperty(value = "udt:DateTimeType | A particular point in the progression of time together with relevant supplementary information.") @Valid public OffsetDateTime getCreated() { return created; }

[ahokkonen]

Our generating-process seems to cover this correctly:
@ApiModelProperty(required = true, value = "udt:DateTimeType | A particular point in the progression of time together with relevant supplementary information.") @NotNull @Valid public OffsetDateTime getModified() { return modified; }

vs
@ApiModelProperty(value = "udt:DateTimeType | A particular point in the progression of time together with relevant supplementary information.") @Valid public OffsetDateTime getCreated() { return created; }

Are you using openapi-generator tools for this? Maybe this is an issue of .NET code generation...

[AndreasSchultzGEA]

Hi Anton, yes that's the tool we use: <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>4.2.3</version>

[ahokkonen]

With some research, things around Nullable types gets even more complicated. With defining complex reference type having just a "nullable: true" is actually not right (and not spec compliant on OAS3.0), but somehow supported by various generators :)

Here is a nice issue to read on "openapi-generator" project.

Had no luck with csharp generator producing proper nullable types only with "nullable: true", but when changed code to use "allOf" (I guess "oneOf" or "anyOf" will also do the trick) from my first message everything went smoothly through.

"created": {
    "nullable": true,
    "allOf": [
        { "$ref": "../types/icarDateTimeType.json" }
    ]
}

In some feedbacks this is also considered as a workaround and not a "fully official" OAS3.0 spec.

[cookeac]

Agreed, looking back through the JSON Schema specs, "nullable": true is ignored by JSON Schema, and we had started using it purely to support OpenAPI, based on assumptions from the YAML version of OpenAPI.
JSON Schema's solution is allOf for reference types as you have described, or for simple types:

"type" : [ "string", "null" ]

Of course, different versions of OpenAPI spec support different subsets of the JSON Schema spec, hence our confusion.

[ahokkonen]

Any opinion on if we should fix a declarations for those properties which meant to be nullable?

[AndreasSchultzGEA]

Has any one from the Java-users verified the result of OpenAPI 3.1 if we change the to '"type" : [ "string", "null" ]' and
"created": { "anyOf": [ { "type": "null" }, { "$ref": "../types/icarDateTimeType.json" } ] }
Just to avoid, that C# works, but Java and JavaScript not ...

[alamers]

I've just did some testing with Java. I specified 'created' date in the 'proper' 3.0 style as Anton proposed. The 'validFrom' (and other fields I left as-is.

Client generation with openapi-generator-cli-4.3.1 and openapi-generator-cli-5.2.0
In both cases, the field private OffsetDateTime created is replaced with JsonNullable<OffsetDateTime> created = JsonNullable.<OffsetDateTime>of(null);

The rationale behind the JsonNullable wrapper is, according to OpenAPITools:

The JsonNullable wrapper shall be used to wrap Java bean fields for which it is important to distinguish between an explicit "null" and the field not being present. A typical usage is when implementing Json Merge Patch where an explicit "null"has the meaning "set this field to null / remove this field" whereas a non-present field has the meaning "don't change the value of this field".

So, it seems that the original implementation leaves out this different interpretations of null. It probably works for most cases though.

Changing to the 'proper' 3.0 style means a compile time breaking change.

[ahokkonen]

I've performed my tests with various versions of openapi-generators and unless I had nullable declaration set as suggested for 3.0 (refer to my comment) the compiled result was incorrect. So, unfortunately, with using openapi-generator tool for .net specs needs to be adjusted.

I also has some tries with autorest, but seems like I need to look a bit deeper into the configuration docs :) With default setting compiled result was produced only for url APIs and not models/types. Maybe I need to merge the schemes first into one so autorest will pick all the defs from single file...

[ahokkonen]

I've just did some testing with Java. I specified 'created' date in the 'proper' 3.0 style as Anton proposed. The 'validFrom' (and other fields I left as-is.

Client generation with openapi-generator-cli-4.3.1 and openapi-generator-cli-5.2.0
In both cases, the field private OffsetDateTime created is replaced with JsonNullable<OffsetDateTime> created = JsonNullable.<OffsetDateTime>of(null);

The rationale behind the JsonNullable wrapper is, according to OpenAPITools:

The JsonNullable wrapper shall be used to wrap Java bean fields for which it is important to distinguish between an explicit "null" and the field not being present. A typical usage is when implementing Json Merge Patch where an explicit "null"has the meaning "set this field to null / remove this field" whereas a non-present field has the meaning "don't change the value of this field".

So, it seems that the original implementation leaves out this different interpretations of null. It probably works for most cases though.

Changing to the 'proper' 3.0 style means a compile time breaking change.

btw, @alamers, what if you try to switch off the "openApiNullable" in configuration and then compile? Looks like Jackson library is used by default for nullable as stated in openapi-generator Java docs. This setting I assume leads to that strange declaration in a compiled code.

[alamers]

I tested with that openApiNullable parameter and for 5.2.0 that generates the same code as before. For 4.3.1, the switch doesn't seem to do anything.

So, the proper '3.0' style works also for Java: either you get the JsonNullable wrapper (with the rationale as stated above), or you explicitly switch that off to get the same code back as we have now. That is, if you use the 5.2.0 generator.

[ahokkonen]

I tested with that openApiNullable parameter and for 5.2.0 that generates the same code as before. For 4.3.1, the switch doesn't seem to do anything.

So, the proper '3.0' style works also for Java: either you get the JsonNullable wrapper (with the rationale as stated above), or you explicitly switch that off to get the same code back as we have now. That is, if you use the 5.2.0 generator.

Ok, maybe for the older version that switch wasn't just supported. So we can state that using latest version of the generator and proper OpenAPI 3.0 nullable declaration we'll get correct results in both languages (c# and java). Was there still something wrong for TypeScript? @AndreasSchultzGEA

[AndreasSchultzGEA]

TS is okay.

[ahokkonen]

back to that issue - should we work on correcting nullable declarations in all schemata for the next minor release (1.3?) and then provide a clear and proper descriptions on code generation (at least Java, .NET, TS)?

I can assign that task on myself and verify for .NET gens, but then I'll need an input from the others to make sure we'll get correct output for Java and TS :)

[AndreasSchultzGEA]

I configured the Java-Generator for the update from 1.1 to 1.2. Now we use the mvn-generator v5.2.1. And as a hint to @alamers :
<configOptions> <dateLibrary>java8</dateLibrary> <openApiNullable>false</openApiNullable> </configOptions> <templateDirectory>${project.basedir}/openapi-generator-templates</templateDirectory>
and within the template, we exchanged include = JsonTypeInfo.As.EXISTING_PROPERTY by PROPERTY.

The results are:
Within the

• Java-code the nullable attributes are initialized with null at their declaration. Nothing more, nothing less. And, there are @NotNull-Annotations, etc. for non-null attributes located at their getter.
• TypeScript-Code there is nothing left in concerns of the non-/nullability. I'll have to check this generator next.

Does anybody have a configuration which contains more?

[ahokkonen]

PR with the fix is published, code generation tested for .NET and typescript.

[ahokkonen]

PR is merged and we only need a last Java verification before closing this issue

[AndreasSchultzGEA]

Java & JS code generation seems to be okay.

[ahokkonen]

seems like all is good, closing this tissue