API Proposal for gRPC JSON transcoding option for case insensitive field names

[JamesNK]

Edit: Updated with feedback.

Background and Motivation

Many JSON APIs have case insensitive property names. People looking to replace their existing JSON API with gRPC JSON transcoding want to keep that behavior. Today they don't have that option. Some are using reflection to modify JSON settings to enable it.

Addresses #50401

Proposed API

namespace Microsoft.AspNetCore.Grpc.JsonTranscoding;

public sealed class GrpcJsonSettings
{
+    /// <summary>
+    /// Gets or sets a value that indicates whether property names are compared using case-insensitive matching during deserialization.
+    /// The default value is <see langword="false"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The Protobuf JSON specification requires JSON property names to match field names exactly, including case.
+    /// Enabling this option may reduce interoperability, as case-insensitive matching might not be supported
+    /// by other JSON transcoding implementations.
+    /// </para>
+    /// <para>
+    /// For more information, see <see href="https://protobuf.dev/programming-guides/json/"/>.
+    /// </para>
+    /// </remarks>
+    public bool PropertyNameCaseInsensitive { get; set; }
}

Usage Examples

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGrpc()
builder.Services.AddJsonTranscoding(o =>
{
    o.JsonSettings.FieldNamesCaseInsensitive = true;
});

Alternative Designs

This setting internally sets JsonSerializerOptions.PropertyNameCaseInsensitive. I considered calling it PropertyNameCaseInsensitive but in Protobuf members are always called fields, not properties.

Risks

Technically case insensitive property names aren't part of the Protobuf JSON spec - https://protobuf.dev/programming-guides/json/ - but we'll call this out in docs so people can make an informed decision.

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[halter73]

You mention in the alternative design section that you considered calling it PropertyNameCaseInsensitive since it configures JsonSerializerOptions.PropertyNameCaseInsensitive but decided against it because Protobuf members are called “fields” not “properties”. However, since this is configuring gRPC JSON transcoding, and this directly affects the JsonSerializerOptions used for transcoding JSON properties, I think “properties” is appropriate and a bit clearer.

If we were to stick with the “field” naming, it should probably still be FieldNameCaseInsensitive with a singular “Name” to match the JsonSerializerOptions naming, but I’d rather just copy the property name fully. Have we given any thought to exposing public API to configure the entire JsonSerializerOptions? Obviously, this gives you more room to shoot yourself in the foot, but it would allow people to work around unforeseen issues with custom converters and the like without resorting to reflection which can break between releases like the people running into the issue have been doing so far.

[JamesNK]

Updating to PropertyNameCaseInsensitive.

[halter73]

After email review, we decided to approve this with PropertyNameCaseInsensitive as the name.