Support System.Text.Json JsonStringEnumMemberNameAttribute

[bdovaz]

Added in 9.0.0: dotnet/runtime#74385

I think it should only affect:

NJsonSchema/src/NJsonSchema.CodeGeneration.CSharp/Templates/Enum.liquid

Line 15 in 9bf8f69

[System.Runtime.Serialization.EnumMember(Value = @"{{ enum.Value | replace: '"', '""' }}")]

And maybe?

NJsonSchema/src/NJsonSchema/Generation/JsonSchemaGenerator.cs

Line 717 in 9bf8f69

var enumMemberAttribute = contextualType.Type.GetRuntimeField(enumName)?.GetCustomAttribute<EnumMemberAttribute>();

[desjoerd]

Currently we do this in the file Enum.Member.Annotations.liquid. Maybe it's helpfull for someone :).

{%  if IsStringEnum %}
    [System.Text.Json.Serialization.JsonStringEnumMemberName(@"{{ enum.Value | replace: '"', '""' }}")]
{% endif %}

This is only usefull when generating the Client from openapi.

[lh-ak]

It seems that this is now implemented in the newest version, but as @bdovaz already mentioned it's available in > .NET 9. for .NET 8 it brakes the client generation currently as it's not available there:

Is it possible to do this only for .NET versions 9 and above?

[RicoSuter]

/cc @lahma @0xced

We need to fix this ASAP... major breaking change for non-latest .NET users. I think we need to introduce CSharpVersion configuration property (same as TypeScriptVersion property, set it to 8.0 by default).

Ref: #1864

[desjoerd]

Or emit a #if NET9_0_OR_GREATER in the template

[RicoSuter]

Or emit a #if NET9_0_OR_GREATER in the template

yeah good idea, simple and does not need yet another config :-), any way this could introduce another breaking change?
can someone create a PR for that?

[RicoSuter]

... ill have a look

[0xced]

There's no need for .NET 9, only the System.Text.Json version 9 package. It targets .NET Standard 2.0 so I don't see it as a big deal, is it?

Also, yes, the new JsonStringEnumMemberName attribute is needed to properly serialize an enum value that does not match the enum name exactly. The System.Runtime.Serialization.EnumMember has never been supported by System.Text.Json, there was a long thread at dotnet/runtime#74385.

[desjoerd]

So it's either a config option or requiring >= NET9 for this feature. November 2026 v8 will be out of support. I can't make this decision, but the first quick fix would be the template

[0xced]

So it's either a config option or requiring >= NET9 for this feature.

No, it doesn't require .NET 9. You can just add a package reference to System.Text.Json (version 9 onwards) and it will work just fine on any plaform supporting .NET Standard 2.0, which includes .NET 8. It will even work on .NET Framework 4.6.2.

I agree that it's a bit counterintuitive but you can get System.Text.Json features introduced in .NET 9 with just a package reference without needing to change your project target framework.

[desjoerd]

I know, but adding a config option for one year when System.Text.Json 8.x goes out of support is a lot. So add the check for NET9_0_OR_GREATER and when Net8 is out of support you can remove this and make it available for NET Framework.

[RicoSuter]

Also, yes, the new JsonStringEnumMemberName attribute is needed to properly serialize an enum value that does not match the enum name exactly. The System.Runtime.Serialization.EnumMember has never been supported by System.Text.Json, there was a long thread at dotnet/runtime#74385.

But then why is it actually working? In my PR (see link below) I test both attributes and the output is the same (and it uses the serializer internally). Or am I missing something?

It targets .NET Standard 2.0 so I don't see it as a big deal, is it?

The big deal is that it's a breaking change... this library (and NSwag with it) is used by a lot of projects where you cannot just quickly upgrade STJ to v9 (either because it's super complex or because it introduces other undesired behavior - ie you dont just update the JSON serializer in big projects just because of some JSON Schema generator breaking change).

I know, but adding a config option for one year when System.Text.Json 8.x goes out of support is a lot. So add the check for NET9_0_OR_GREATER and when Net8 is out of support you can remove this and make it available for NET Framework.

I agree, I'd say we go with NET9_0_OR_GREATER to keep it simple... hmm problem is that if you target .NET Standard 2.0 you are never able to use this, so you'd need to be able to specify the STJ version via config, or not? Only option is to keep it as is for NON-NET9 and remove NET9_0_OR_GREATER in a year - but yeah that's not really ideal because usually NSwag/NJS it's again a breaking change for quite some ppl.

See PR: #1865

[0xced]

But then why is it actually working?

Well, it's not actually working.

Take this simple code, using the EnumMember attribute.

using System;
using System.Runtime.Serialization;
using System.Text.Json;
using System.Text.Json.Serialization;

var pizza = new Pizza
{
    Name = "Margherita",
    Size = PizzaSize.Medium,
};

var json = JsonSerializer.Serialize(pizza, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

public class Pizza
{
    public string Name { get; set; }

    [JsonConverter(typeof(JsonStringEnumConverter<PizzaSize>))]
    public PizzaSize Size { get; set; }
}

public enum PizzaSize
{
    [EnumMember(Value = "S")]
    Small,

    [EnumMember(Value = "M")]
    Medium,

    [EnumMember(Value = "L")]
    Large,
}

This produces the following output.

{
  "Name": "Margherita",
  "Size": "Medium"
}

Note that it's using Medium which is the name of the enum member itself, not the value defined on the EnumMember attribute.

Now if you switch from [EnumMember(Value = "M")] to [JsonStringEnumMemberName("M")] then it will produce this JSON output, using the M defined in the attribute, which is what I consider working.

{
  "Name": "Margherita",
  "Size": "M"
}