Non-Required fields generate Non-Nullable properties

[pazoozooCH]

My issue is related to the now closed issue #82 where you took the position that if we wanted a field to be nullable, it should not only be optional (= not required), but also nullable.

While I understand that these are two distinct concepts (a field not being submitted at all vs. a field being submitted as null), this distinction is not mappable to a simple C# class. My property can either be null or not null, it cannot be "not defined".

So in the context of C#, I would expect that a non-required field results in a nullable property (e.g. int? instead of int). Otherwise, it simply won't be possible to convert a perfectly valid JSON document into the corresponding C# object. Would you agree to this?

Furthermore, it is currently not possible to have nullable enums in NSwag (even if they have "type": "null" in JSON Schema). While this might be seen as a different issue, it could also be fixed (at least in my context) with an implementation treating non-required fields as nullable.

I would prepare a fix for this issue as we vitaly need this in our project. Would you generally support to merge such a fix or do you have any other considerations?

btw. I've also discussed this with @lbovet which supports this approach (we're using NSwag in combination with https://github.com/swisspush/apikana).

[lbovet]

I suggest that we provide this feature "behind a flag", i.e. that the current behavior stays the default and that we activate the "non-required-as-nullable" feature explicitely and on demand.

[pazoozooCH]

@RSuter , could you maybe comment on how you see this and give some hints on where this would need to be fixed? Unless you have immediate resources to fix it yourself, of course... 😎

[lbovet]

This should actually be solved in the NJsonSchema project, I think.
This line sets the nullability (the "?") of the generated property: https://github.com/RSuter/NJsonSchema/blob/master/src/NJsonSchema.CodeGeneration.CSharp/Models/PropertyModel.cs#L42
It uses only the "nullable" property and not the "required/optional" information.
I guess we should change this line to:

public override string Type => _resolver.Resolve(_property, _property.IsNullable(_settings.SchemaType) || !property.IsRequired && _settings.NonRequiredAsNullable, GetTypeNameHint());

And also add this "NonRequiredAsNullable" property in the configuration.

[RicoSuter]

This should actually be solved in the NJsonSchema project, I think.

Correct all DTO schema handling stuff is in NJsonSchema and not in NSwag.

It uses only the "nullable" property and not the "required/optional" information.

This is not 100% correct, see: https://github.com/RSuter/NJsonSchema/blob/master/src/NJsonSchema/JsonProperty.cs#L92

[RicoSuter]

I already spent days for the nullability and undefined handling and I think it is fine as is. The problem is that there are three different "dimensions" which change the actual handling:

1. Schema generator: The used schema type (JSON Schema, Swagger 2 and OpenAPI 3) have a big impact on how the schema looks like:
   • JSON Schema: "required" => cannot be undefined but can be null if "type" = "null" => nullable
   • Swagger 2: "required" => cannot be undefined and cannot be null (there is no way in Swagger 2 to express nullability => that's why we introduced x-nullable)
   • OpenAPI 3: "required" => cannot be undefined but can be null if "nullable" = true => nullable
2. Client generator:
   • In TypeScript, the target TS version is important
3. Settings and annotations

So I think it a good start is to actually document the different behaviors with samples in the NJS wiki and then decide whether we need to change something. The problem with changing something is that it is a huge breaking change for many users...

[pazoozooCH]

Thanks for the clarifications. I feel this is getting a bit complex for my problem. Let me get one step back and outline my use case again:

• Input: JSON Schema v4 (actually I start from TypeScript, but that doesn't really change too much here)
  • Field: not required, no nullable information (i.e. not nullable); primitive type: number, integer, enum, ...
• Output: C# class, generated by NSwag.MSBuild

So I want to be able to parse JSON to C# classes and generate JSON from C# classes, pretty standard use case I assume.

When I get a JSON now without the field that is not required (which is 100% legit according to the Schema), I simply cannot parse that into the C# class if the type is not nullable. So I would say the required handling in this (not too unusual) context is not fine at all.

I guess I'm just using a small part of NSwag (and NJsonSchema for that matter) and cannot easily predict any side effects in other areas. So I was hoping that this adaptation could be made as isolated as possible in order to avoid breaking changes in other areas that might have more options in differing null and undefined as C# has. But in the context of C# classes generation from JSON Schema, I don't see how this change would break anything as nobody would be able to actually use it as is...

[RicoSuter]

Can you provide a sample schema, some C# output and sample data?

[RicoSuter]

So you are talking about JSON Schema, not Swagger or OpenAPI? If this is the case, we should move this issue over to NJsonSchema

[pazoozooCH]

Ok, here's a very simplistic sample demonstrating the issue:

TypeScript (just for completeness, dont' worry too much about this one):

export enum MyEnum {
    Val1,
    Val2
}

export interface MySimpleType {
    myOptionalValue?: number;
    myOptionalEnum?: MyEnum;
}

This generates the following JSON Schema v4 files:

my-enum.json:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "definitions": {},
  "type": "string",
  "enum": [
    "Val1",
    "Val2"
  ],
  "id": "MyEnum"
}

my-simple-type.json:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "definitions": {},
  "type": "object",
  "properties": {
    "myOptionalValue": {
      "type": "number"
    },
    "myOptionalEnum": {
      "$ref": "my-enum.json"
    }
  },
  "additionalProperties": false,
  "id": "MySimpleType"
}

Now I take that JSON Schema and use NSwag.MSBuild to generate C# classes: <Exec Command="$(NSwagExe_Core20) jsonschema2csclient /name:MySimpleType /output:$(ProjectDir)/gen/MySchema.cs /input:$(ProjectDir)/dist/model/json-schema-v4/my-simple-type.json" />

This will create a class that looks as this (excerpt):

    public partial class MySimpleType : System.ComponentModel.INotifyPropertyChanged
    {
        private double _myOptionalValue;
        private MyEnum _myOptionalEnum;
        ...

Now consider I have an empty JSON document {} as input which is perfectly legal with this Schema as both fields are not required. It will not be mappable to the class. Both fields / properties should / must be optional (double?, MyEnum?) in the generated class to support this case.

[pazoozooCH]

btw in my case, it's JSON Schema. But I feel it's more an issue of treating optional and nullable different in the context of C# class generation while they cannot really be distinguished in a POCO. So I'm not sure it wouldn't be the same problem with Swagger or OpenAPI as well...

[pazoozooCH]

And yes, for the number field, I could add "null" as type and it would result in double?. But when I do the same with a $ref enum, NSwag starts introducing weird, empty helper classes...
So I figured it would be better to fix the unfortunate non-required-primitive handling instead of fiddling with "null" in the JSON-Schema...

[RicoSuter]

I used the playground here: https://apiverse.io/tools

With this schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "definitions": {},
  "type": "object",
  "properties": {
    "myOptionalValue": {
      "type": "number"
    },
    "myOptionalEnum": {
      "enum": [
        "Val1",
        "Val2"
      ]
    }
  },
  "additionalProperties": false,
  "id": "MySimpleType"
}

With schemaType = JsonSchema, I get the following:

        [Newtonsoft.Json.JsonProperty("myOptionalValue", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public double MyOptionalValue { get; set; }
    
        [Newtonsoft.Json.JsonProperty("myOptionalEnum", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public RootMyOptionalEnum MyOptionalEnum { get; set; }

As you can see, all properties are not nullable but allow undefined - in this case the default of the enum/double is used. This is a compromise for JSON Schema so that not all properties are nullable but do not allow null (this is even more confusing).

If you use schemaType = Swagger2, you'll get what you expect (because Swagger2 does not know null):

        [Newtonsoft.Json.JsonProperty("myOptionalValue", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public double? MyOptionalValue { get; set; }
    
        [Newtonsoft.Json.JsonProperty("myOptionalEnum", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public RootMyOptionalEnum? MyOptionalEnum { get; set; }

But for your scenario, we'd need to add a new setting for the C# generator and schemaType = JsonSchema. But this is purely an NJsonSchema issue...

[pazoozooCH]

Ok - so would you say the input from @lbovet (#838 (comment)) is appropriate then?

How do we proceed? Should I make a fix and submit a PR or do you have time to have a look at this yourself (in the near future)?