Introduction

In C#, converting JSON into a custom object usually means deserializing a JSON string into a class whose properties match the JSON structure. The modern built-in option is System.Text.Json, while many existing projects still use Newtonsoft.Json, also known as Json.NET.

The main requirement is that your class shape matches the JSON. Once that is true, deserialization is typically a one-line operation.

Use System.Text.Json

Suppose the JSON looks like this:

1{
2  "id": 42,
3  "name": "Ada",
4  "isActive": true
5}

Define a matching C# class:

1public class User
2{
3    public int Id { get; set; }
4    public string Name { get; set; } = string.Empty;
5    public bool IsActive { get; set; }
6}

Then deserialize it:

1using System;
2using System.Text.Json;
3
4string json = """
5{
6  "id": 42,
7  "name": "Ada",
8  "isActive": true
9}
10""";
11
12User? user = JsonSerializer.Deserialize<User>(json);
13
14Console.WriteLine(user?.Name);

That is the standard approach in modern .NET code.

Handle Property Name Differences

If JSON property names do not match your C# property names exactly, annotate them:

1using System.Text.Json.Serialization;
2
3public class User
4{
5    [JsonPropertyName("user_id")]
6    public int Id { get; set; }
7
8    [JsonPropertyName("display_name")]
9    public string Name { get; set; } = string.Empty;
10}

This is useful when the API uses snake case and your C# code uses Pascal case.

You can also configure naming policies globally, but explicit attributes are often clearer when only a few names differ.

Nested Objects and Arrays

Deserialization works recursively as long as your classes match the JSON structure.

Example JSON:

1{
2  "name": "Ada",
3  "address": {
4    "city": "Toronto"
5  },
6  "roles": ["admin", "editor"]
7}

Corresponding classes:

1using System.Collections.Generic;
2
3public class Address
4{
5    public string City { get; set; } = string.Empty;
6}
7
8public class User
9{
10    public string Name { get; set; } = string.Empty;
11    public Address Address { get; set; } = new();
12    public List<string> Roles { get; set; } = new();
13}

Then deserialize in exactly the same way with JsonSerializer.Deserialize<User>(json).

Newtonsoft.Json Still Works Fine

If your project already uses Json.NET, the equivalent code is:

using Newtonsoft.Json;

User? user = JsonConvert.DeserializeObject<User>(json);

This is still very common in older codebases or when you need Json.NET-specific features. The underlying idea is identical: match the JSON shape with your class and deserialize into that type.

Validate the Shape You Expect

Deserialization does not magically fix a schema mismatch. If the JSON is missing fields, contains wrong types, or wraps the object differently from your class design, the result may be null, partially filled, or throw an exception depending on the settings and library.

That means it is worth checking:

• whether the root JSON is an object or an array
• whether numeric and string types match your class
• whether nested objects are modeled correctly

A large share of "JSON to object" problems are really schema-mismatch problems.

Common Pitfalls

• Trying to deserialize a JSON object into a class that does not match the JSON structure.
• Forgetting that arrays need collection types such as List<T>.
• Ignoring property-name differences between the JSON and the C# model.
• Using the term "custom C object" when the real target is a custom C# class, which can confuse the API choice.

Summary

• In C#, convert JSON to a custom object by deserializing into a matching class.
• 'System.Text.Json is the modern built-in option.'
• Newtonsoft.Json is still common and works similarly.
• Use attributes when JSON property names differ from your C# property names.
• Most deserialization issues come from mismatched schema, not from the deserializer call itself.