Utf8Json Documentation

For complex projects, it is recommended to build a custom IJsonFormatterResolver that implements a cache for formatters. This allows you to combine specific IJsonFormatter instances (like custom date formatters) with a chain of other resolvers (like ImmutableCollectionResolver or EnumResolver).

Alternatively, you can use CompositeResolver.Create to build a dynamic resolver at runtime. Note that CompositeResolver.Create has a high cost and cannot be garbage collected easily, so you should store the resulting instance in a static field.

// create custom composite resolver per project is recommended way.
public class ProjectDefaultResolver : IJsonFormatterResolver
{
    public static IJsonFormatterResolver Instance = new ProjectDefaultResolver();

    static IJsonFormatter[] formatters = new IJsonFormatter[]{
        new DateTimeFormatter("yyyy-MM-dd HH:mm:ss"),
        new NullableDateTimeFormatter("yyyy-MM-dd HH:mm:ss")
    };

    static readonly IJsonFormatterResolver[] resolvers = new[] {
        ImmutableCollectionResolver.Instance,
        EnumResolver.UnderlyingValue,
        StandardResolver.AllowPrivateExcludeNullSnakeCase
    };

    // ... implementation of GetFormatter<T> using a FormatterCache ...
}

// Or create and store dynamic CompositeResolver
public static class MyOwnProjectResolver
{
    public static readonly IJsonFormatterResolver Instance = CompositeResolver.Create(
        /* IJsonFormatter[] */,
        /* IJsonFormatterResolver[] */
    );
}

The IJsonFormatterResolver acts as the storage for typed serializers. You can customize serialization behavior by assembling a resolver chain.

Available Resolvers:

• BuiltinResolver: Includes primitives, standard classes, nullables, arrays, and lists.
• DynamicGenericResolver: Handles generic types (e.g., List<T>, Dictionary<K,V>) using reflection on the first call.
• AttributeFormatterResolver: Resolves formatters based on the [JsonFormatter] attribute.
• EnumResolver: EnumResolver.Default (serializes as name) or EnumResolver.UnderlyingValue (serializes as value).
• StandardResolver: A composite resolver that follows the order: object fallback -> builtin -> enum -> dynamic generic -> attribute -> dynamic object.

StandardResolver can be configured with:

• AllowPrivate: (bool) If true, uses FormatterServices.GetUninitializedObject to deserialize private fields.
• ExcludeNull: (bool) If true, skips null properties.
• NameMutate: (Original, CamelCase, or SnakeCase) Changes the property naming convention.

Utf8Json supports the ShouldSerialize pattern (similar to Json.NET). If you define a public bool ShouldSerialize<MemberName>() method (must be parameterless), Utf8Json will call it before serializing that member. If the method returns false, the member will be omitted from the output.

public class MyPerson
{
    public string Name { get; set; }
    public string[] Addresses { get; set; }

// ShouldSerialize*membername**
    // method must be `public` and return `bool` and parameter less.
    public bool ShouldSerializeAddresses()
    {
        if (Addresses != null && Addresses.Length != 0)
        {
            return true;
        }
        else
        {
            return false;
        }
    }
}

// {"Name":"foo"}
JsonSerializer.ToJsonString(new MyPerson { Name = "foo", Addresses = new string[0] });

// {"Name":"bar","Addresses":["tokyo","kyoto"]}
JsonSerializer.ToJsonString(new MyPerson { Name = "bar", Addresses = new[] { "tokyo", "kyoto" } });

To use Utf8Json as a custom serializer in AWS Lambda, implement the Amazon.Lambda.Core.ILambdaSerializer interface. You can pass a custom IJsonFormatterResolver to the constructor to handle specific types (like S3 or Kinesis event records) that require custom formatting.

// with `Amazon.Lambda.Core package`
public class Utf8JsonLambdaSerializer : Amazon.Lambda.Core.ILambdaSerializer
{
    readonly IJsonFormatterResolver resolver;

    public Utf8JsonLambdaSerializer()
    {
        this.resolver = JsonSerializer.DefaultResolver;
    }

    public Utf8JsonLambdaSerializer(IJsonFormatterResolver resolver)
    {
        this.resolver = resolver;
    }

    public void Serialize<T>(T response, Stream responseStream)
    {
        Utf8Json.JsonSerializer.Serialize<T>(responseStream, response, resolver);
    }

    public T Deserialize<T>(Stream requestStream)
    {
        return Utf8Json.JsonSerializer.Deserialize<T>(requestStream, resolver);
    }
}

Use CompositeResolver.RegisterAndSetAsDefault to define a global serialization strategy. This allows you to combine custom formatters, specific enum behaviors, and standard naming conventions into a single resolver used by the default JsonSerializer.

Example of setting up a global resolver with custom DateTime formatting and SnakeCase naming:

// use global-singleton CompositeResolver.
// This method initialize CompositeResolver and set to default JsonSerializer
CompositeResolver.RegisterAndSetAsDefault(new IJsonFormatter[] {
    // add custome formatters, use other DateTime format.
    // if target type is struct, requires add nullable formatter too(use NullableXxxFormatter or StaticNullableFormatter(innerFormatter))
    new DateTimeFormatter("yyyy-MM-dd HH:mm:ss"),
    new NullableDateTimeFormatter("yyyy-MM-dd HH:mm:ss")
}, new[] {
    // resolver custom types first
    ImmutableCollectionResolver.Instance,
    EnumResolver.UnderlyingValue,

// finaly choose standard resolver
    StandardResolver.AllowPrivateExcludeNullSnakeCase
});