[API Proposal]: Add more extensive control over ignoring properties

[rogerfar]

Background and motivation

If I have this config:

services.AddControllers()
		.AddJsonOptions(options =>
		{
			options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
			options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault;
			options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
		});

And I return the following:

[HttpGet]
[Route("Test")]
public ActionResult Test()
{
    return Ok(new
    {
        StringValue = "Prop",
        NullString = (string)null,
        DefaultNumber = 0,
        EnumValue = TestEnum.Val2,
        DefaultEnum = TestEnum.Val1
    });
}

The result is:

{
  "stringValue": "Prop",
  "enumValue": "Val2"
}

This can cause confusion because the value of DefaultEnum is omitted because it's default is, but because it's converted as a string this reduces clarity.

API Proposal

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace System.Text.Json.Serialization
{
    /// <summary>
    /// When specified on <see cref="JsonSerializerOptions.DefaultIgnoreCondition"/>,
    /// determines when properties and fields across the type graph are ignored.
    /// When specified on <see cref="JsonIgnoreAttribute.Condition"/>, controls whether
    /// a property is ignored during serialization and deserialization. This option
    /// overrides the setting on <see cref="JsonSerializerOptions.DefaultIgnoreCondition"/>.
    /// </summary>
    public enum JsonIgnoreCondition
    {
        /// <summary>
        /// Property is never ignored during serialization or deserialization.
        /// </summary>
        Never = 0,
        /// <summary>
        /// Property is always ignored during serialization and deserialization.
        /// </summary>
        Always = 1,
        /// <summary>
        /// If the value is the default, the property is ignored during serialization.
        /// This is applied to both reference and value-type properties and fields.
        /// </summary>
        WhenWritingDefault = 2,
        /// <summary>
        /// If the value is <see langword="null"/>, the property is ignored during serialization.
        /// This is applied only to reference-type properties and fields.
        /// </summary>
        WhenWritingNull = 3,
        /// <summary>
        /// If the value is the default, the property is ignored during serialization.
        /// This is applied to both reference and value-type properties and fields.
		/// When using JsonStringEnumConverter enum properties will be included.
        /// </summary>
        WhenWritingDefaultExceptEnums = 4,
    }
}

API Usage

services.AddControllers()
		.AddJsonOptions(options =>
		{
			options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
			options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefaultExceptEnums;
			options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
		});

Risks

No response

Tagging subscribers to this area: @eiriktsarpalis, @layomia
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

If I have this config:

services.AddControllers()
		.AddJsonOptions(options =>
		{
			options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
			options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault;
			options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
		});

And I return the following:

[HttpGet]
[Route("Test")]
public ActionResult Test()
{
    return Ok(new
    {
        StringValue = "Prop",
        NullString = (string)null,
        DefaultNumber = 0,
        EnumValue = TestEnum.Val2,
        DefaultEnum = TestEnum.Val1
    });
}

The result is:

{
  "stringValue": "Prop",
  "enumValue": "Val2"
}

This can cause confusion because the value of DefaultEnum is omitted because it's default is, but because it's converted as a string this reduces clarity.

API Proposal

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace System.Text.Json.Serialization
{
    /// <summary>
    /// When specified on <see cref="JsonSerializerOptions.DefaultIgnoreCondition"/>,
    /// determines when properties and fields across the type graph are ignored.
    /// When specified on <see cref="JsonIgnoreAttribute.Condition"/>, controls whether
    /// a property is ignored during serialization and deserialization. This option
    /// overrides the setting on <see cref="JsonSerializerOptions.DefaultIgnoreCondition"/>.
    /// </summary>
    public enum JsonIgnoreCondition
    {
        /// <summary>
        /// Property is never ignored during serialization or deserialization.
        /// </summary>
        Never = 0,
        /// <summary>
        /// Property is always ignored during serialization and deserialization.
        /// </summary>
        Always = 1,
        /// <summary>
        /// If the value is the default, the property is ignored during serialization.
        /// This is applied to both reference and value-type properties and fields.
        /// </summary>
        WhenWritingDefault = 2,
        /// <summary>
        /// If the value is <see langword="null"/>, the property is ignored during serialization.
        /// This is applied only to reference-type properties and fields.
        /// </summary>
        WhenWritingNull = 3,
        /// <summary>
        /// If the value is the default, the property is ignored during serialization.
        /// This is applied to both reference and value-type properties and fields.
		/// When using JsonStringEnumConverter enum properties will be included.
        /// </summary>
        WhenWritingDefaultExceptEnums = 4,
    }
}

API Usage

services.AddControllers()
		.AddJsonOptions(options =>
		{
			options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
			options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefaultExceptEnums;
			options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
		});

Risks

No response

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

[eiriktsarpalis]

Exposing a separate setting only to exempt JsonStringEnumConverter in particular seems a bit ad-hoc to me. Perhaps one alternative might be to expose a setting that disables ignored defaults when a custom converter is being used for a type.

Related to #50294. It seems clear that WhenWritingDefault is too much of a blunt instrument when applied at the JsonSerializerOptions level and too noisy when applied at the individual property level.

What we could do instead is expose a mechanism for omitting properties at the converter level, for example:

public class JsonConverter<T>
{
    public virtual bool IgnoreProperty(T propertyValue, JsonSerializerOptions options) => 
       // naive, partial implementation adopted for brevity
       options.DefaultIgnoreCondition == JsonIgnoreCondition.WhenWritingDefault &&
       EqualityComparer<T>.Default.Equals(propertyValue, default);
}

and thus completely opt out JsonStringEnumConverter by default:

public class StringEnumConverter<TEnum>
{
    public override bool IgnoreProperty(TEnum _, JsonSerializerOptions options) => false;
}

cc @layomia @NinoFloris

[NinoFloris]

@eiriktsarpalis the proposal looks good to me, the only question to me would be whether the IgnoreProperty method is additive to or entirely overriding JsonSerializerOptions.JsonIgnoreCondition. Overriding is more powerful but I'd rather not come across too many 'constant false' converters that completely fail to respect any JsonIgnoreCondition. So it'd need some good guiding examples of how to do it right, either by looking up JsonIgnoreCondition in options or having specific converter options for it.

[rogerfar]

Would it be an idea to make DefaultIgnoreCondition not just an enum but an options object that accept multiple conditions? It will be a breaking change but not a very difficult one to fix.