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

Use this guide when you upgrade the Contentstack Management .NET SDK from v0.x to v1.0.0-beta.1+. The new 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 Management .NET SDK v1.0.0-beta.1 or later, installed in your project.
• .NET 10 or later, the framework version this SDK targets.

For most upgrades, follow this order:

1. Make sure you have the prerequisites.
2. Replace OpenJObjectResponse() with OpenJsonObjectResponse() at every response call site.
3. Replace JObject, JToken, and JArray usage with JsonObject, JsonNode, and JsonArray.
4. Replace SelectToken() calls with chained indexers, typed models, or a JSON Path library.
5. Replace ParameterCollection.AddQuery(JObject) with ParameterCollection.AddQuery(JsonNode).
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.

ContentstackResponse now exposes three ways to read a response:

JObject result = response.OpenJObjectResponse();
string title = result["title"]?.Value<string>();

JsonObject result = response.OpenJsonObjectResponse();
string? title = result["title"]?.GetValue<string>();

Or deserialize directly to a typed model (preferred):

MyModel? model = response.OpenTResponse<MyModel>();

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(), client.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"
};

The following 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.

ParameterCollection.AddQuery accepts a System.Text.Json.Nodes.JsonNode. Pass a JsonObject, which derives from JsonNode, wherever you previously passed a Newtonsoft JObject.

Before (Newtonsoft, v0.x)

using Newtonsoft.Json.Linq;

var filter = new JObject { ["locale"] = "en-us" };
query.Parameters.AddQuery(filter);

After (System.Text.Json, v1.0.0-beta.1+)

using System.Text.Json.Nodes;

var filter = new JsonObject { ["locale"] = "en-us" };
query.Parameters.AddQuery(filter);

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 (ContentstackErrorException) are unchanged.

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 client = new ContentstackClient(options);

client.SerializerSettings.DateParseHandling = DateParseHandling.None;
client.SerializerSettings.DateFormatHandling = DateFormatHandling.IsoDateFormat;
client.SerializerSettings.NullValueHandling = NullValueHandling.Ignore;

// Register a custom Newtonsoft converter
client.SerializerSettings.Converters.Add(new MyNewtonsoftConverter());

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

var client = new ContentstackClient(options);

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

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

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, client.SerializerSettings);
var copy = JsonConvert.DeserializeObject<MyModel>(json, client.SerializerSettings);

using System.Text.Json;

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

Pass the same JsonSerializerOptions instance from client.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:

client.SerializerOptions.Converters.Add(new MySystemTextJsonConverter());

Polymorphic converters

The SDK itself uses [JsonPolymorphic] and [JsonDerivedType] on base model types (for example, Field and its subtypes). If you subclass SDK models or provide your own polymorphic field types, declare them at the base class level:

using System.Text.Json.Serialization;

[JsonPolymorphic(UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor)]
[JsonDerivedType(typeof(MyCustomField))]
public class Field { ... }

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 client.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 field type you added comes back as the base Field rather than your subclass.

Root cause: The SDK declares Field with [JsonPolymorphic(UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToNearestAncestor)], so an unrecognized subtype falls back to the nearest known ancestor instead of throwing.

Resolution: Declare your subtype with [JsonDerivedType(typeof(MyCustomField))] on the base class, as shown in Custom converters.

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 client.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 response handling: replace OpenJObjectResponse() with OpenJsonObjectResponse(), or switch to OpenTResponse<T>() for typed models (see Working with response objects).
3. Replace all JObject/JToken usage in business logic with JsonObject/JsonNode (see Working with JSON documents).
4. Replace SelectToken with chained indexers or a deliberate JSON Path strategy (see JSON Path and SelectToken).
5. Update query parameters: replace AddQuery(JObject) with AddQuery(JsonNode) (see Updated SDK method signatures).
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 v1.0.0-beta.1 release notes for this SDK.