Introduction

Json.NET can skip properties whose values are null, which often makes outgoing JSON cleaner and smaller. The important design point is that omitting a property is not the same thing as serializing it with an explicit null, so the setting should be chosen based on API semantics, not only on output appearance.

Omit Nulls Globally With NullValueHandling.Ignore

The standard global setting is NullValueHandling.Ignore. When enabled, Json.NET does not write properties whose values are null.

1using System;
2using Newtonsoft.Json;
3
4public class Profile
5{
6    public string Name { get; set; }
7    public string Email { get; set; }
8    public string Phone { get; set; }
9}
10
11var profile = new Profile
12{
13    Name = "Ava",
14    Email = null,
15    Phone = null
16};
17
18var settings = new JsonSerializerSettings
19{
20    NullValueHandling = NullValueHandling.Ignore,
21    Formatting = Formatting.Indented
22};
23
24var json = JsonConvert.SerializeObject(profile, settings);
25Console.WriteLine(json);

In the output, only Name appears because the other properties are null.

Apply the Rule Per Property When Global Omission Is Too Broad

Sometimes a global rule is too aggressive. Json.NET also lets you control null handling at the property level.

1using Newtonsoft.Json;
2
3public class PaymentRequest
4{
5    public string Currency { get; set; }
6
7    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
8    public string CouponCode { get; set; }
9
10    public decimal Amount { get; set; }
11}

This is useful when one optional field should disappear if null, while the rest of the contract should continue to represent nulls explicitly.

Missing and Null Can Mean Different Things

This is the most important part of the topic. In many APIs:

• a missing property means "not provided"
• an explicit null means "clear this value"

If clients or servers depend on that distinction, switching on global null omission changes contract behavior even though your model classes stay the same. That is why serializer settings belong in API design discussions, not only in formatting preferences.

Configure ASP.NET Carefully

If your application uses Json.NET in ASP.NET, configure the serializer centrally so behavior is consistent.

1using Microsoft.Extensions.DependencyInjection;
2using Newtonsoft.Json;
3
4var builder = WebApplication.CreateBuilder(args);
5
6builder.Services
7    .AddControllers()
8    .AddNewtonsoftJson(options =>
9    {
10        options.SerializerSettings.NullValueHandling = NullValueHandling.Ignore;
11    });

This only works if the application is actually using the Json.NET pipeline. If the project is serializing with System.Text.Json, these settings will have no effect.

Null References Are Not the Same as Empty Collections

Json.NET skips null references when null omission is enabled, but empty collections still serialize because they are not null.

1using System.Collections.Generic;
2
3public class OrderDto
4{
5    public string Id { get; set; }
6    public List<string> Notes { get; set; } = new();
7    public AddressDto ShippingAddress { get; set; }
8}
9
10public class AddressDto
11{
12    public string Line1 { get; set; }
13    public string Line2 { get; set; }
14}

If ShippingAddress is null, it may disappear. If Notes is an empty list, it still appears as an empty array unless you add different rules. That distinction matters in contract tests.

Treat It as a Contract Choice, Not a Cosmetic Trick

Developers often enable null omission to reduce noise in the JSON. That is a reasonable goal, but it should not be the only consideration. Ask whether the receiving side distinguishes between missing data and explicit null, whether documentation promises one behavior or the other, and whether partial-update endpoints rely on the difference.

Once you think of null omission as a contract choice, the correct configuration usually becomes much clearer.

Common Pitfalls

• Assuming that omitting a property and serializing it as null mean the same thing.
• Applying global null omission when only one or two fields were supposed to be omitted.
• Debugging Json.NET settings in an app that is actually using System.Text.Json.
• Forgetting that empty collections are still serialized even when null properties are ignored.
• Changing serializer behavior without updating contract tests or client expectations.

Summary

• Json.NET can omit null-valued properties with NullValueHandling.Ignore.
• The rule can be applied globally or at the property level.
• Missing properties and explicit null values often mean different things in APIs.
• Null objects can disappear while empty collections still serialize normally.
• Choose the behavior intentionally as part of the API contract, not just for prettier JSON.