Support customizing enum member names in System.Text.Json

[jscarle]

API Proposal

Concerning the question of adding built-in enum name customization support, this would need to be done via a new attribute type:

namespace System.Text.Json.Serialization;

[AttributeUsage(AttributeTargets.Field, AllowMultiple = false)]
public class JsonStringEnumMemberNameAttribute : Attribute
{
    public JsonStringEnumMemberNameAttribute(string name);
    public string Name { get; }
}

API Usage

Setting the attribute on individual enum members can customize their name

JsonSerializer.Serialize(MyEnum.Value1 | MyEnum.Value2); // "A, B"

[Flags, JsonConverter(typeof(JsonStringEnumConverter))]
public enum MyEnum
{
    [JsonStringEnumMemberName("A")]
    Value1 = 1,

    [JsonStringEnumMemberName("B")]
    Value2 = 2,
}

Original Post

[Issue 31081](https://github.com//issues/31081) was closed in favor of [issue 29975](https://github.com//issues/29975), however the scope of the issues differ.

Issues 29975 is a discussion regarding the DataContract and DataMember attributes in general. Although JsonStringEnumConverter does address the straight conversion between an enum and its direct string representation, it does not in fact address cases where the string is not a direct match to the enum value.

The following enum will NOT convert properly using the current implementation of JsonStringEnumConverter:

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum GroupType
{
    [EnumMember(Value = "A")]
    Administrator,

    [EnumMember(Value = "U")]
    User
}

Suggested Workaround

See this gist for a recommended workaround that works for both AOT and reflection-based scenaria.

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Issue 31081 was closed in favor of issue 29975, however the scope of the issues differ.

Issues 29975 is a discussion regarding the DataContract and DataMember attributes in general. Although JsonStringEnumConverter does address the straight conversion between an enum and its direct string representation, it does not in fact address cases where the string is not a direct match to the enum value.

The following enum will NOT convert properly using the current implementation of JsonStringEnumConverter:

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum GroupType
{
    [EnumMember(Value = "A")]
    Administrator,

    [EnumMember(Value = "U")]
    User
}

The solution proposed by JasonBodley works correctly: #31081 (comment)

[JsonConverter(typeof(JsonStringEnumConverterEx<GroupType>))]
public enum GroupType
{
    [EnumMember(Value = "A")]
    Administrator,

    [EnumMember(Value = "U")]
    User
}

However, this functionality should be built-in to the JsonStringEnumConverter.

Author:	jscarle
Assignees:	-
Labels:	area-System.Text.Json, untriaged
Milestone:	-

[eiriktsarpalis]

As mentioned in the issues you're linking to, it is unlikely we would add support for EnumMemberAttribute specifically, for the same reason that we are reluctant to do it for all the other attributes under System.Runtime.Serialization. These pertain to different/older serialization stacks and as such supporting them OOTB in System.Text.Json is not something we are planning to do.

We might consider exposing a dedicated attribute in the future, assuming there is substantial demand. Alternatively, it should be possible to add support using a custom converter, as has already been proposed by the community.

[jscarle]

Looking at the System.Text.Json.Serialization namespace, in addition to the JsonConverter and JsonConverter<T>, the only other JsonConverter added was the JsonStringEnumConverter. In other words, it was clearly identified that there is a frequent use case for converting between json string values and their enum equivalents, and vice-versa. However, right from the very beginning, people ran into situations where the string value is not necessarily the exact name of the enum, as it has been clearly demonstrated on stackoverflow: https://stackoverflow.com/questions/59059989/system-text-json-how-do-i-specify-a-custom-name-for-an-enum-value

I do agree that EnumMember is not the correct attribute, and that moving forward the goal should be to build upon System.Text.Json and not another unrelated namespace.

In the spirit of what's already been established with JsonStringEnumConverter, I would propose the following attribute:

namespace System.Text.Json.Serialization
{
    /// <summary>
    /// Specifies the enum string value that is present in the JSON when serializing and deserializing.
    /// </summary>
    [AttributeUsage(AttributeTargets.Field, Inherited = false, AllowMultiple = false)]
    public sealed class JsonStringEnumValueAttribute : JsonAttribute
    {
        /// <summary>
        /// Initializes a new instance of <see cref="JsonStringEnumValueAttribute"/> with the specified string value.
        /// </summary>
        /// <param name="value">The string value of the enum.</param>
        public JsonStringEnumValueAttribute(string value)
        {
            Value = value;
        }

        /// <summary>
        /// The string value of the enum.
        /// </summary>
        public string Value { get; }
    }
}

Which could then be used by the JsonStringEnumConverter specifically. Extending support for this attribute would eliminate the need for workarounds and nuget packages that people currently use and allow JsonStringEnumConverter to be used as the built-in go-to for all string to enum use cases.

[eiriktsarpalis]

Extending support for this attribute would eliminate the need for workarounds and nuget packages that people currently use

I should clarify that implementing all functionality OOTB is not a design goal for System.Text.Json. We do want to make sure the library offers the right extensibility points so that third party extensions can be defined easily and be successfully, however.

[jscarle]

I do agree, and there are popular alternatives such as Newtonsoft.Json which can fulfill the need for more advanced JSON serialization and deserialization. Its simply that the functionality for JsonStringEnumConverter has already been included in System.Text.Json, it would be nice to round off that functionality with this last missing bit.

String to enum conversions is a frequent use case, and due to the language restrictions for enum members, the occurrences where the string representation of the enum value will differ from the enum member name is quite frequent. Quite often due to the use of spaces, dashes, or underscores in the JSON string value used by the system with which .NET code may be communicating.

An alternative would be to enhance the parsing logic of Enum.TryParse (which is eventually called by JsonStringEnumConverter) to compensate for spaces, dashes, and underscores, but being that it's such a core method in the runtime, I doubt that would ever see the light of day.

[IanKemp]

Extending support for this attribute would eliminate the need for workarounds and nuget packages that people currently use

I should clarify that implementing all functionality OOTB is not a design goal for System.Text.Json. We do want to make sure the library offers the right extensibility points so that third party extensions can be defined easily and be successfully, however.

Do "the right extensibility points" include "hiding JsonStringEnumConverter's functionality in EnumConverter<T>, an internal sealed class that precludes said functionality from being easily extended by developers, thus forcing them to re-implement that same functionality entirely from scratch"?

Why is it that every time I need to do something simple like this feature request in STJ, I end up spending half a day looking for a solution, which turns out to be the opposite of simple... and along the way I find a similar solution for the same requirement in Newtonsoft.Json, and it is absolutely simple there? I very much get the impression that the STJ APIs and classes were designed by people who have never had to try to use STJ, whereas Newtonsoft.Json was written by a developer for developers.

To put it simply, Microsoft: if you want people to use STJ, why do you continually make it so difficult to use STJ? Why do you make me regret my decision to use it every time I try to use it? Why does this API have to be so unnecessarily, continually painful?

[layomia]

The contract resolver feature new in 7.0 could be extended to support user detection of EnumMemberAttribute with minimal configuration code to apply it to enum contracts. We can evaluate the feasibility of enabling this scenario in 8.0.

[Maximys]

@eiriktsarpalis , I want to provide some links about current Issue:

1. System.Text.Json.Tests.EnumConverterTests.DuplicateNameEnumTest;
2. System.Text.Json.Tests.EnumConverterTests.DuplicateNameEnum.FooBar.

Yes, may be I does not understand something, but this test and enum assume the implementation of EnumMemberAttribute support.
Today I had alot of hadacke with JsonSerializer and EnumMemberAttribute. Can I try to implement this support?