JSON and Serialisation

Serialisation is the conversion between an object in memory and text on the wire. Your C# type becomes JSON on the way out, and incoming JSON becomes a C# object on the way in. In ASP.NET Core that work is done by System.Text.Json, and by default it happens without you writing a line of it.

That convenience hides a contract. The names, the letter case, the way a date is written, whether a missing value appears as null or vanishes — every one of those is part of what callers depend on. If you do not decide them, the defaults decide for you, and they change when your C# changes.

using System.Text.Json;
using System.Text.Json.Serialization;

// Program.cs
builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    options.SerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.Never;
    options.SerializerOptions.Converters.Add(new JsonStringEnumConverter());
});

// Contracts/EmployeeResponse.cs
public enum EmploymentStatus { Active, OnLeave, Left }

public sealed record EmployeeResponse(
    int Id,
    string FullName,
    string Email,
    EmploymentStatus Status,
    DateOnly StartDate,
    DateTimeOffset CreatedAt,
    int? ManagerId);

• ConfigureHttpJsonOptions sets the policy for minimal API endpoints. If you use controllers, the equivalent is builder.Services.AddControllers().AddJsonOptions(...). Setting it in both places is worth doing in a project that mixes them.
• PropertyNamingPolicy.CamelCase turns FullName into fullName. This is already the default for web applications; stating it means a future change to the defaults cannot quietly alter your contract.
• JsonIgnoreCondition.Never writes null for absent values instead of omitting the property. Callers then see managerId on every employee, which is easier to model than a property that sometimes is not there.
• JsonStringEnumConverter writes Status as "OnLeave" rather than 1. Without it, System.Text.Json writes the numeric value.
• DateOnly for StartDate and DateTimeOffset for CreatedAt is the distinction that saves the most confusion later: one is a date on a calendar, the other is a specific moment somewhere in the world.

{
  "id": 42,
  "fullName": "Asha Menon",
  "email": "asha.menon@example.com",
  "status": "OnLeave",
  "startDate": "2024-04-17",
  "createdAt": "2024-04-17T09:31:44+05:30",
  "managerId": null
}

• Every property is camelCase, so a JavaScript client reads employee.fullName without a mapping layer.
• status is a word. A client can compare it to "OnLeave" and a support engineer can read it in a log without a lookup table.
• startDate has no time and no zone, because a start date does not have one. Sending it as a full timestamp invites a client in another zone to display the day before.
• createdAt carries +05:30, so the moment is unambiguous. A timestamp with no offset is a guess about which clock it came from.
• managerId is present and null rather than missing, because DefaultIgnoreCondition.Never was chosen. The caller can rely on the property existing.