[API Proposal]: alternate name option for JsonPropertyNameAttribute

[hansmbakker]

Background and motivation

Kotlin / Gson supports an alternate name for json properties, which can be convenient to allow deserializing similar json to a unified class object.

Currently, JsonPropertyNameAttribute does not have support for this, and it is not possible to specify multiple instances of JsonPropertyNameAttribute.

Having this would remove the need for writing a custom JsonConverter for this case.

Note: this is only about deserialization - serialization will always use the default name value.

API Proposal

namespace System.Text.Json.Serialization
{
    /// <summary>
    /// Specifies the property name that is present in the JSON when serializing and deserializing.
    /// This overrides any naming policy specified by <see cref="JsonNamingPolicy"/>.
    /// </summary>
    [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)]
    public sealed class JsonPropertyNameAttribute : JsonAttribute
    {
        /// <summary>
        /// Initializes a new instance of <see cref="JsonPropertyNameAttribute"/> with the specified property name.
        /// </summary>
        /// <param name="name">The name of the property.</param>
        public JsonPropertyNameAttribute(string name)
        {
            Name = name;
        }

        /// <summary>
        /// Initializes a new instance of <see cref="JsonPropertyNameAttribute"/> with the specified property name
        /// and alternative property names for deserialization.
        /// </summary>
        /// <param name="name">The name of the property.</param>
        /// <param name="alternatives">The alternative names of the property.</param>
        public JsonPropertyNameAttribute(string name, string[] alternatives)
        {
            Name = name;
            Alternatives = alternative;
        }

        /// <summary>
        /// The name of the property.
        /// </summary>
        public string Name { get; }

        /// <summary>
        /// The alternative names of the property.
        /// </summary>
        /// <remarks>
        /// Is only used for deserialization
        /// </remarks>
        public string[] Alternatives { get; }
    }
}

API Usage

public class Test
{
   [JsonPropertyName("property", alternatives = { "oldPropertyNameForBackwardsCompatibility" })]
   public string Property { get; set; }
}

Alternative Designs

No response

Risks

While I would say having a clean json response from an API would be better, one does not always have control over the responses of the API.

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

---

Background and motivation

Kotlin / Gson supports an alternate name for json properties, which can be convenient to allow deserializing similar json to a unified class object.

Currently, JsonPropertyNameAttribute does not have support for this, and it is not possible to specify multiple instances of JsonPropertyNameAttribute.

Having this would remove the need for writing a custom JsonConverter for this case.

Note: this is only about deserialization - serialization will always use the default name value.

API Proposal

namespace System.Text.Json.Serialization
{
    /// <summary>
    /// Specifies the property name that is present in the JSON when serializing and deserializing.
    /// This overrides any naming policy specified by <see cref="JsonNamingPolicy"/>.
    /// </summary>
    [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)]
    public sealed class JsonPropertyNameAttribute : JsonAttribute
    {
        /// <summary>
        /// Initializes a new instance of <see cref="JsonPropertyNameAttribute"/> with the specified property name.
        /// </summary>
        /// <param name="name">The name of the property.</param>
        public JsonPropertyNameAttribute(string name)
        {
            Name = name;
        }

        /// <summary>
        /// Initializes a new instance of <see cref="JsonPropertyNameAttribute"/> with the specified property name.
        /// </summary>
        /// <param name="name">The name of the property.</param>
        /// <param name="alternatives">The alternative names of the property.</param>
        public JsonPropertyNameAttribute(string name, string[] alternatives)
        {
            Name = name;
            Alternatives = alternative;
        }

        /// <summary>
        /// The name of the property.
        /// </summary>
        public string Name { get; }

        /// <summary>
        /// The alternative names of the property.
        /// </summary>
        /// <remarks>
        /// Is only used for deserialization
        /// </remarks>
        public string[] Alternatives { get; }
    }
}

API Usage

public class Test
{
   [JsonPropertyName("property", alternatives = { "myProperty" })]
   public string MyProperty { get; set; }
}

Alternative Designs

No response

Risks

While I would say having a clean json response from an API would be better, one does not always have control over the responses of the API.

Author:	hansmbakker
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json
Milestone:	-

[aromaa]

I have myself worked around this with the following but it for sure looks ugly. However, I'm also using this for polymorphic deserialization so having support for alternative names in the JsonPolymorphicAttribute too would be helpful.

internal sealed class JsonData
{
	[JsonPropertyName("type")]
	public string Type { get; init; }

	[JsonPropertyName("t")]
	public string T
	{
		init => this.Type = value;
	}
}

[gregsdennis]

Under what conditions would an alternate name be used?

[hansmbakker]

Under what conditions would an alternate name be used?

When having to e.g. support multiple versions of a REST API that have minor changes in property naming of the API response json.

[krwq]

You can actually easily add support for this yourself with contract resolver which is added in 7.0 preview7. Here is code sample:

using System.Text.Json;
using System.Text.Json.Serialization.Metadata;

namespace JsonAlternativeName
{
    internal class Program
    {
        static void Main(string[] args)
        {
            JsonSerializerOptions options = new()
            {
                TypeInfoResolver = new DefaultJsonTypeInfoResolver()
                {
                    Modifiers = { JsonAlternativeNameModifier }
                }
            };

            string json = """{"Foo": "test1", "Baz": "test2"}""";
            Print(JsonSerializer.Deserialize<Test>(json, options)); // [ Foo = test1; Baz = test2]

            json = """{"Bar": "test3", "ASD": "test4"}""";
            Print(JsonSerializer.Deserialize<Test>(json, options)); // [ Foo = test3; Baz = test4]

            json = """{"Bar2": "test5", "Baz": "test6"}""";
            Print(JsonSerializer.Deserialize<Test>(json, options)); // [ Foo = test5; Baz = test6]
        }

        static void Print(Test test) => Console.WriteLine($"[ Foo = {test.Foo}; Baz = {test.Baz}]");

        static void JsonAlternativeNameModifier(JsonTypeInfo typeInfo)
        {
            int initialCount = typeInfo.Properties.Count;
            for (int i = 0; i < initialCount; i++)
            {
                JsonPropertyInfo prop = typeInfo.Properties[i];
                if (prop.AttributeProvider != null)
                {
                    object[] attrs = prop.AttributeProvider.GetCustomAttributes(typeof(JsonAlternativeNameAttribute), inherit: true);
                    foreach (var attr in attrs)
                    {
                        JsonAlternativeNameAttribute attribute = (JsonAlternativeNameAttribute)attr;
                        JsonPropertyInfo newProp = typeInfo.CreateJsonPropertyInfo(prop.PropertyType, attribute.AltName);
                        newProp.Set = prop.Set;
                        typeInfo.Properties.Add(newProp);
                    }
                }
            }
        }
    }

    internal class Test
    {
        [JsonAlternativeName("Bar")]
        [JsonAlternativeName("Bar2")]
        public string Foo { get; set; }

        [JsonAlternativeName("ASD")]
        public string Baz { get; set; }
    }

    [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = true)]
    internal class JsonAlternativeNameAttribute : Attribute
    {
        public string AltName { get; set; }

        public JsonAlternativeNameAttribute(string altName)
        {
            AltName = altName;
        }
    }
}

csproj:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <LangVersion>preview</LangVersion><!-- for triple quote syntax -->
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="System.Text.Json" Version="7.0.0-preview.7.22375.6" />
  </ItemGroup>

</Project>

[Guiorgy]

@krwq Thank you for the tip, however this doesn't seem to work with non-public properties and public constructors. The constructor argument name must match the property name, however the properties added through typeInfo.Properties.Add don't have a match in the constructor, thus only the original name works. Here's an example:

public sealed class Test2
{
    [JsonAlternativeName("Bar")]
    [JsonAlternativeName("Bar2")]
    public string Foo { get; }

    [JsonAlternativeName("ASD")]
    public string Baz { get; }

    [JsonConstructor]
    public Test2(string foo, string baz)
    {
        Foo = foo;
        Baz = baz;
    }
}

[TestMethod]
public void Test2()
{
    string json = """{"Foo": "test1", "Baz": "test2"}""";
    var test = JsonSerializer.Deserialize<Test2>(json, options);
    Assert.IsNotNull(test);
    Assert.AreEqual("test1", test.Foo); // pass
    Assert.AreEqual("test2", test.Baz); // pass

    json = """{"Bar": "test3", "ASD": "test4"}""";
    test = JsonSerializer.Deserialize<Test2>(json, options);
    Assert.IsNotNull(test);
    Assert.AreEqual("test3", test.Foo); // failed
    Assert.AreEqual("test4", test.Baz);

    json = """{"Bar2": "test5", "Baz": "test6"}""";
    test = JsonSerializer.Deserialize<Test2>(json, options);
    Assert.IsNotNull(test);
    Assert.AreEqual("test5", test.Foo);
    Assert.AreEqual("test6", test.Baz);
}

Do you have any thought on how to handle such case?

EDIT: Found a workaround! Well, almost...

If the properties have a setter action, they don't need a matching argument in the constructor, so for every property added override the setter:

var setter = (object obj, object? value) =>
{
    if (prop.Set != null) prop.Set(obj, value);
    else {
        // the setter may be private
        var privateSetter = typeInfo.Type.GetProperty(property.Name)?.GetSetMethod(nonPublic: true);
        if (privateSetter != null) privateSetter.Invoke(obj, new[] { value });
        else {
            // there's no setter, so access the backing field dirrectly
            var backingField = typeInfo.Type.GetField($"<{property.Name}>k__BackingField", BindingFlags.Instance | BindingFlags.NonPublic);
            if (backingField != null) backingField.SetValue(obj, value);
            else {
                // it could be a field, not a property
                var field = typeInfo.Type.GetField(property.Name);
                if (field != null) field.SetValue(obj, value);
                else throw new JsonException("Must be a property with no setter and a custom getter (no backing field). Can't handle this!");
            }
        }
    }
};

newProp.Set = setter;
typeInfo.Properties.Add(newProp);

It's quite ugly, and still can't handle a property without a default backing field.

Let me know if you find something better.

EDIT2: On further though, there's a huge flaw in my workaround, it assumes that the constructor and setter (if present) transform the value in the same way. This may not always be the case. Besides going for a source generator, I can't think of a way to make it work right. I hope this feature gets implemented.

[Varorbc]

@eiriktsarpalis any update?