[System.Text.Json] Converter-level conditional serialization

[trinitrotoluene]

Motivation

In many (usually web) scenarios, conditional serialization is an absolute must for a variety of reasons.

Some that come to mind:

• Omitting certain fields in an API response for privacy (GDPR) reasons, avoiding duplication of types
• Semantic difference between "foo": null and omitting "foo" entirely (for example RESTful PATCH calls)

Right now, STJ allows you to completely ignore null values as an options switch, which means this can be hacked in using a nullable struct and custom serializerfactory, but that's not a very reasonable API to expect users to be resorting to, and it results in juggling different JsonSerializerOptions around and polluting your data models with SomeWrapperType<T>).

It would be nice to be able to specify whether a custom or overriden type should be serialized at all at the converter-level.

API Proposal

Add an overridable JsonConverter<T>#ShouldSerialize(T, PropertyInfo, JsonSerializerOptions) method:

public abstract class JsonConverter<T>
{
    ...

    public virtual bool ShouldSerialize(T value, PropertyInfo propertyInfo, JsonSerializerOptions options) => true;

    ...
}

Which would be called before an attempt is made to write the property.

Performance Implications

This depends largely on the performance of the user-provided ShouldSerialize method, but by caching whether the method was overridden when initialising the property, the call could be ommitted for converters that don't implement it.

Usage

Example: the Option pattern (factory omitted):

public class OptionConverter<T> : JsonConverter<Option<T>>
{
    ...

    public override Option<T> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        ...
    }

    public override bool ShouldSerialize(Option<T> value, PropertyInfo propertyInfo, JsonSerializerOptions options)
    {
        return value.HasValue;
    }

    public override void Write(Utf8JsonWriter writer, Option<T> value, JsonSerializerOptions options)
    {
        ...
    }
}

One final note, the added propertyInfo parameter is for enabling masking logic based on custom attributes or property names, result of which the implementer could then cache per-property.

I think this would be a useful feature for many users and increase the versatility of the serializer. As for whether it's a feature that exists in JSON.NET - this kind of functionality would be implemented through the IContractResolver interface by providing a delegate to JsonProperty#ShouldSerialize when creating the property.

The IContractResolver API is a lot more expansive as it operates at the type-level and solves a lot more of the issues that I see users opening here, but I think that this is still a valid extension point to offer. (Issue tracking that is #31257)

[layomia]

As mentioned, having a model similar to implementing an IContractResolver and adding API such as the Should(De)serialize predicates would also help this scenario. The APIs proposed in this issue would have to be examined alongside the design for such a model in System.Text.Json, to ensure that we have a cohesive set of APIs end to end. We don't want to end up having too many APIs to achieve the same result.

Related: #34456 (discusses types that would likely be exposed as part of an IContractResolver-like model)

[eiriktsarpalis]

Adding IContractResolver-like functionality is certainly on our radar (see #34456), but there have been separate proposals on controlling serialization on the converter level (see #55781). I'm going to close this issue in favor of the other two.