Migrate .NET Delivery SDK from Newtonsoft.Json to System.Text.Json

Use this guide when you upgrade the Contentstack Delivery .NET SDK to the next major version. That version removes Newtonsoft.Json and replaces it with System.Text.Json, breaking every call site that uses JObject, JsonSerializerSettings, Newtonsoft converters, or Newtonsoft attributes.

This guide shows the System.Text.Json replacement for each affected area and the exact code changes required.

Note If your codebase uses SelectToken() extensively, plan additional migration effort. System.Text.Json has no built-in equivalent. See JSON Path and SelectToken.

• The Contentstack Delivery .NET SDK at the next major version or later, installed in your project.
• .NET 6 or later.

For most upgrades, follow this order:

1. Complete the prerequisites.
2. Update SDK method call sites that return JObject (Entry.ToJson(), Query.Count(), AssetLibrary.Count(), ContentType.Fetch(), GlobalField.Fetch(), GlobalFieldQuery.Find()).
3. Replace AssetLibrary.Query(JObject) parameter with JsonObject.
4. Replace JObject, JToken, and JArray usage with JsonObject, JsonNode, and JsonArray.
5. Replace SelectToken() calls with chained indexers, typed models, or a JSON Path library.
6. Replace [JsonProperty] with [JsonPropertyName] on your models.
7. Update catch (Newtonsoft.Json.JsonException) to catch (System.Text.Json.JsonException).
8. Replace SerializerSettings with SerializerOptions and rewrite any custom converters.
9. Run integration tests and compare serialized payloads. Remove the Newtonsoft.Json dependency.

The following SDK methods now return or accept System.Text.Json types. Update every call site that stores the result or passes a parameter typed as a Newtonsoft type.

Before

JObject raw = entry.ToJson();
string title = (string?)raw["title"];

After

JsonObject raw = entry.ToJson();
string? title = raw["title"]?.GetValue<string>();

Before

JObject countJson = await query.Count();
int total = countJson["count"]!.Value<int>();

After

JsonObject countJson = await query.Count();
int total = countJson["count"]!.GetValue<int>();

Before

var filter = new JObject { ["tag"] = "featured" };
var library = stack.AssetLibrary().Query(filter);

After

var filter = new JsonObject { ["tag"] = "featured" };
var library = stack.AssetLibrary().Query(filter);

Before

JObject schema = await contentType.Fetch();
JObject gf = await globalField.Fetch();
JObject found = await globalFieldQuery.Find();

After

JsonObject schema = await contentType.Fetch();
JsonObject gf = await globalField.Fetch();
JsonObject found = await globalFieldQuery.Find();

Adjust any code that casts to Newtonsoft.Json.Linq.JObject or uses LINQ-to-JSON APIs (Properties(), Descendants(), etc.) to the equivalent JsonObject or JsonNode APIs.

Before

using Newtonsoft.Json.Linq;

JObject doc = JObject.Parse(responseJson);
var count = doc["count"]?.Value<int>();

After

using System.Text.Json.Nodes;

JsonObject doc = JsonNode.Parse(responseJson)!.AsObject();
int? count = doc["count"]?.GetValue<int>();

For nested objects or arrays within the document, deserialize with the client's options:

MyDto? dto = JsonSerializer.Deserialize<MyDto>(doc["nested"]!.GetRawText(), stack.SerializerOptions);

Newtonsoft's SelectToken("$.entries[0].title") has no built-in equivalent in System.Text.Json.

Simple property paths become chained indexers:

Before

var entries = obj.SelectToken("$.entries");
var title = obj.SelectToken("$.entries[0].title")?.ToString();

After

var entries = obj["entries"];
var title = doc["entries"]?[0]?["title"]?.GetValue<string>();

For deep or dynamic paths:

• Navigate to the target node by chaining indexers and iterating arrays in a loop.
• Deserialize to a typed model and use C# property access instead of path queries.
• Use JsonPath.Net if your codebase relies heavily on dynamic path queries.
• Keep Newtonsoft as a direct project dependency in your application for legacy path-heavy code that does not pass data to or receive data from the SDK (see Gradual migration).

Before

var q = new JObject
{
    ["title"] = "Hello",
    ["locale"] = "en-us"
};

After

var q = new JsonObject
{
    ["title"] = "Hello",
    ["locale"] = "en-us"
};

Replace Newtonsoft serialization attributes with System.Text.Json equivalents for any type deserialized by the SDK.

Before

using Newtonsoft.Json;

public class Product
{
    [JsonProperty("product_title")]
    public string Title { get; set; }

    [JsonIgnore]
    public string Internal { get; set; }
}

After

using System.Text.Json.Serialization;

public class Product
{
    [JsonPropertyName("product_title")]
    public string Title { get; set; } = "";

    [JsonIgnore]
    public string Internal { get; set; } = "";
}

Additional System.Text.Json attributes:

If you catch JSON parsing errors around SDK calls:

Before

catch (Newtonsoft.Json.JsonException ex) { /* ... */ }

After

catch (System.Text.Json.JsonException ex) { /* ... */ }

SDK-specific errors are unchanged by this migration.

The SerializerSettings property is renamed to SerializerOptions and its type changes from JsonSerializerSettings to JsonSerializerOptions. Code that sets Newtonsoft-specific options on SerializerSettings does not compile after you upgrade.

using Newtonsoft.Json;

var stack = new ContentstackClient(/* ... */);

stack.SerializerSettings.DateParseHandling = DateParseHandling.None;
stack.SerializerSettings.DateFormatHandling = DateFormatHandling.IsoDateFormat;
stack.SerializerSettings.DateTimeZoneHandling = DateTimeZoneHandling.Utc;
stack.SerializerSettings.NullValueHandling = NullValueHandling.Ignore;

// Register a custom Newtonsoft converter
stack.SerializerSettings.Converters.Add(new MyNewtonsoftEntryConverter());

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

var stack = new ContentstackClient(/* ... */);

// System.Text.Json uses ISO 8601 for dates by default — no extra configuration needed for most cases
stack.SerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;

// Register a custom System.Text.Json converter (must be rewritten — see Custom converters section)
stack.SerializerOptions.Converters.Add(new MySystemTextJsonEntryConverter());

SerializerOptions key points:

• The property is SerializerOptions (JsonSerializerOptions), not SerializerSettings.
• Newtonsoft converters cannot be added to JsonSerializerOptions without rewriting them (see Custom converters).
• SerializerOptions is a public property on ContentstackClient. The same instance is used for all SDK API calls, so converters and options you add there apply throughout.

using Newtonsoft.Json;

string json = JsonConvert.SerializeObject(myModel, stack.SerializerSettings);
var copy = JsonConvert.DeserializeObject<MyModel>(json, stack.SerializerSettings);

using System.Text.Json;

string json = JsonSerializer.Serialize(myModel, stack.SerializerOptions);
var copy = JsonSerializer.Deserialize<MyModel>(json, stack.SerializerOptions);

Pass the same JsonSerializerOptions instance from stack.SerializerOptions so field names, converters, and date behavior stay consistent with how the SDK parses entries and assets.

Both serializers define a type named JsonConverter<T>, but they are in different namespaces and have different method signatures, reader and writer types, and parsing patterns. You must rewrite any custom converters. Re-registering an existing Newtonsoft converter does not work.

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

public class MyNewtonsoftConverter : JsonConverter<MyModel>
{
    public override MyModel ReadJson(JsonReader reader, Type objectType,
        MyModel? existingValue, bool hasExistingValue, JsonSerializer serializer)
    {
        JObject obj = JObject.Load(reader);
        var model = obj.ToObject<MyModel>(serializer)!;
        // custom logic
        return model;
    }

    public override void WriteJson(JsonWriter writer, MyModel? value, JsonSerializer serializer)
    {
        serializer.Serialize(writer, value);
    }
}

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

public class MySystemTextJsonConverter : JsonConverter<MyModel>
{
    public override MyModel? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        JsonNode node = JsonNode.Parse(ref reader)!;
        var model = JsonSerializer.Deserialize<MyModel>(node.GetRawText(), options);
        if (model is null) return null;
        // custom logic using node.AsObject(), etc.
        return model;
    }

    public override void Write(Utf8JsonWriter writer, MyModel value, JsonSerializerOptions options)
    {
        JsonSerializer.Serialize(writer, value, options);
    }
}

Register with stack.SerializerOptions.Converters.Add(new MySystemTextJsonConverter());.

If you need to migrate incrementally while some legacy code still uses JObject:

using System.Text.Json.Nodes;
using Newtonsoft.Json.Linq;

static JsonObject ToJsonObject(JObject jo) =>
    JsonNode.Parse(jo.ToString(Newtonsoft.Json.Formatting.None))!.AsObject();

static JObject ToJObject(JsonObject jo) =>
    JObject.Parse(jo.ToJsonString());

This lets your non-SDK code continue using JObject while satisfying the SDK's requirement for JsonObject at each call site. It does not restore full compatibility. You still need to convert every place you pass a JObject to or receive one from the SDK. Remove the adapter once all call sites are ported.

Symptom: Your existing converter compiles, but the SDK ignores it and values serialize with default behavior.

Root cause: The SDK serializes through its SerializerOptions, which is a System.Text.Json.JsonSerializerOptions. A Newtonsoft JsonConverter<T> is a different type in a different namespace, so it is never registered on those options.

Resolution: Rewrite the converter as a System.Text.Json.Serialization.JsonConverter<T> and register it with stack.SerializerOptions.Converters.Add(...). See Custom converters.

Symptom: Code using SelectToken("$.path") fails to build after switching to JsonObject.

Root cause: The JsonNode API has no SelectToken method, and System.Text.Json has no single built-in JSON Path equivalent.

Resolution: Replace simple paths with chained indexers such as doc["a"]?[0]?["b"], deserialize to a typed model, or adopt a JSON Path library for JsonNode. See JSON Path and SelectToken.

Symptom: A JsonException is thrown when reading models that contain date fields.

Root cause: System.Text.Json expects ISO 8601 date strings by default, and the SDK registers no custom date converter. Other date formats are not parsed automatically.

Resolution: Supply dates in ISO 8601, or register a custom JsonConverter<DateTime> on stack.SerializerOptions to handle your format.

Use this checklist to verify you have completed every change before removing the Newtonsoft.Json dependency.

1. Search your solution for Newtonsoft.Json, JObject, JToken, JArray, JsonConvert, JsonSerializerSettings, [JsonProperty], and Newtonsoft JsonConverter.
2. Update SDK method call sites that return JObject: Entry.ToJson(), Query.Count(), AssetLibrary.Count(), ContentType.Fetch(), GlobalField.Fetch(), GlobalFieldQuery.Find() (see SDK methods that change).
3. Replace AssetLibrary.Query(JObject) parameter with JsonObject (see SDK methods that change).
4. Replace all JObject/JToken usage in business logic with JsonObject/JsonNode (see Working with JSON documents).
5. Replace SelectToken with chained indexers or a deliberate JSON Path strategy (see JSON Path and SelectToken).
6. Update model attributes: [JsonProperty] to [JsonPropertyName], etc. (see Attributes on your models).
7. Update catch (Newtonsoft.Json.JsonException) to catch (System.Text.Json.JsonException) (see Exception handling).
8. Replace client configuration: move from SerializerSettings to SerializerOptions (see Configure serialization).
9. Rewrite custom converters as System.Text.Json.Serialization.JsonConverter<T> and re-register on SerializerOptions (see Custom converters).
10. Run integration tests against staging, and compare serialized payloads if you snapshot JSON responses.
11. Remove Newtonsoft.Json from your project once your own code no longer needs it. The SDK no longer references it.

• System.Text.Json overview (Microsoft). Background on the serializer the SDK now uses, including supported types and configuration options.
• Migrate from Newtonsoft.Json to System.Text.Json (Microsoft). Microsoft's API-by-API migration reference for cases beyond the SDK-specific changes covered here.
• CHANGELOG.md. The release notes for the next major version of this SDK.