Introduction

ASP.NET Core uses System.Text.Json by default, and the default naming policy outputs camelCase property names. If your API contract requires PascalCase or custom naming, you can disable or customize this behavior globally or per endpoint. The right approach depends on compatibility requirements with existing clients.

Core Sections

Default behavior in ASP.NET Core

By default, response JSON usually maps C# properties to camelCase names.

1public class UserDto
2{
3    public string FirstName { get; set; } = "";
4    public string LastName { get; set; } = "";
5}

Response may appear as firstName and lastName.

Turn off camel casing globally

Set naming policy to null.

1builder.Services
2    .AddControllers()
3    .AddJsonOptions(options =>
4    {
5        options.JsonSerializerOptions.PropertyNamingPolicy = null;
6        options.JsonSerializerOptions.DictionaryKeyPolicy = null;
7    });

Now JSON keeps original property names such as FirstName.

Per-property overrides

Use attributes when only specific fields need custom names.

1using System.Text.Json.Serialization;
2
3public class UserDto
4{
5    [JsonPropertyName("first_name")]
6    public string FirstName { get; set; } = "";
7}

This is useful for transitional contracts.

Handling mixed client contracts

If some clients expect camelCase and others expect legacy PascalCase, version your APIs or expose separate endpoints instead of switching naming globally at runtime.

Newtonsoft.Json alternative

If project uses Newtonsoft, equivalent setting is:

1services.AddControllers()
2    .AddNewtonsoftJson(opts =>
3    {
4        opts.SerializerSettings.ContractResolver = new Newtonsoft.Json.Serialization.DefaultContractResolver();
5    });

Use one serializer stack consistently when possible.

Validation and production readiness

Add contract tests that snapshot response JSON keys. This prevents accidental casing changes during framework upgrades.

Document naming policy in API specifications so client teams do not infer behavior incorrectly. Include migration notices if casing policy changes in a new API version.

Per-endpoint naming policy in Minimal APIs

If you cannot switch casing globally, set options per response. This gives a safe migration path for one endpoint at a time.

1using System.Text.Json;
2
3var legacyOptions = new JsonSerializerOptions
4{
5    PropertyNamingPolicy = null,
6    DictionaryKeyPolicy = null,
7    WriteIndented = false
8};
9
10app.MapGet("/legacy-user", () =>
11{
12    var dto = new UserDto { FirstName = "Ada", LastName = "Lovelace" };
13    return Results.Json(dto, legacyOptions);
14});

This endpoint returns FirstName and LastName while the rest of your API can stay camelCase.

Validate casing with integration tests

Contract tests catch accidental serializer changes after framework upgrades.

1[Fact]
2public async Task LegacyEndpoint_UsesPascalCase()
3{
4    await using var app = new WebApplicationFactory<Program>();
5    var client = app.CreateClient();
6
7    var json = await client.GetStringAsync("/legacy-user");
8
9    Assert.Contains(""FirstName"", json);
10    Assert.DoesNotContain(""firstName"", json);
11}

Migration strategy for mixed clients

When old and new clients coexist, explicit versioning is cleaner than runtime switching. For example, expose /v1 with PascalCase and /v2 with camelCase, then deprecate gradually. Update OpenAPI documents per version and publish cutoff dates. This avoids hidden behavior and keeps API expectations stable for client teams.

Production checklist and verification loop

A reliable implementation needs more than a working snippet. Add a small verification loop that runs in CI and after dependency upgrades. Start with golden examples that represent normal input, boundary input, and one malformed input. Then validate output values, output shape or schema, and failure messages. This catches silent behavior drift early.

Document assumptions directly in the code comments near the transformation or query logic. Teams often forget whether behavior is strict, permissive, or backward-compatibility focused. Clear assumptions reduce future refactor risk.

For performance-sensitive paths, capture a baseline metric and compare after every change. The metric can be latency, memory use, or throughput depending on workload. Keep benchmark inputs realistic so results are meaningful.

Finally, expose observability signals that tell you when this logic starts failing in production. Useful signals include error counts, validation failures, and rate of fallback paths. A short checklist, a few deterministic tests, and lightweight monitoring are usually enough to keep this solution stable as surrounding systems evolve.

Common Pitfalls

• Changing naming policy without versioning and breaking existing clients.
• Mixing System.Text.Json and Newtonsoft settings unintentionally.
• Assuming dictionary keys follow property policy by default.
• Overusing per-property overrides and creating inconsistent contracts.
• Skipping automated contract checks in CI.

Summary

• ASP.NET Core can disable camel casing by setting naming policy to null.
• Use attributes for targeted property name overrides.
• Prefer explicit API versioning when casing contracts differ.
• Keep serializer choice and settings consistent.
• Protect casing expectations with contract tests.