Every time an app talks to a web API, there's a very good chance the words passing between them are JSON.

Your C# program has an Order object — a real, in-memory .NET object with properties, methods, and a specific type. A web API written in a completely different language, running on a completely different server, needs to receive that same order's data. C# objects can't travel across a network — but text can. JSON is the text format almost every modern system has agreed to use for exactly this handoff.

In this lesson, you'll learn what JSON is, why it became the near-universal format for this kind of data exchange, and how to serialize and deserialize C# objects to and from JSON using System.Text.Json — .NET's modern, built-in JSON library.

What Is It?

The Simple Explanation

JSON (JavaScript Object Notation) is a plain-text way of writing structured data — objects, lists, numbers, strings, booleans — using a small, simple, human-readable syntax. Despite the name, it's not tied to JavaScript at all anymore; it's a language-neutral text format that virtually every modern programming language, including C#, can read and write.

The Technical Definition

JSON is a lightweight, text-based data-interchange format built on two structures: an object — an unordered collection of key/value pairs, written with { } — and an array — an ordered list of values, written with [ ]. Values can be strings, numbers, booleans, null, or nested objects/arrays. System.Text.Json is the JSON library built into .NET since .NET Core 3.0, and it's the idiomatic, default choice for JSON work in modern .NET — it converts .NET objects to JSON text (serialization) and JSON text back into .NET objects (deserialization).

Why Does It Exist?

The Problem

An in-memory C# object is specific to the .NET runtime — its exact bit layout, its type metadata, all of it is meaningless to a Python service, a JavaScript browser, or a mobile app written in Swift. If two systems need to exchange structured data and they're not both running the exact same runtime, they need a shared, neutral format both sides already know how to read and write.

The Need

The industry needed a data format that's language-neutral, simple enough to read by eye when debugging, compact enough to send efficiently over a network, and expressive enough to represent the nested objects and lists real applications actually use.

The Solution — JSON as the Common Language

JSON satisfies all of that, and virtually every language — C#, Python, JavaScript, Java, Go, Swift — has mature, standard library support for it. This is precisely why it became the default format for REST APIs, configuration files, message queues, and countless other places where two independent pieces of software need to agree on structured data.

Big Picture

How It Works

public class Order
{
    public int Id { get; set; }
    public string CustomerName { get; set; } = "";
    public decimal Total { get; set; }
    public bool IsPaid { get; set; }
}

var order = new Order { Id = 1042, CustomerName = "Acme Co", Total = 149.99m, IsPaid = true };
string json = JsonSerializer.Serialize(order);
// {"Id":1042,"CustomerName":"Acme Co","Total":149.99,"IsPaid":true}

string incomingJson = "{\"Id\":2001,\"CustomerName\":\"Globex\",\"Total\":89.5,\"IsPaid\":false}";
Order? parsed = JsonSerializer.Deserialize<Order>(incomingJson);
Console.WriteLine(parsed?.CustomerName); // "Globex"

Common options

JsonSerializerOptions controls how serialization behaves — two of the most commonly reached-for options:

camelCase naming matters a great deal in practice — most JSON APIs (especially anything with a JavaScript front end) expect property names like customerName, not the C# convention of CustomerName. Applying JsonNamingPolicy.CamelCase lets your C# class keep normal C# naming conventions while still producing (and accepting) JSON in the style the rest of the ecosystem expects.

Simple Example

Round-tripping a simple object, and also reading/writing JSON directly to a file (tying this back to the File lessons earlier in the module):

Real-World Example

A REST API endpoint receiving a new order as JSON and responding with a JSON confirmation — the everyday shape of nearly every modern web API request/response cycle:

This is essentially what happens under the hood every time you call a modern web API — a JSON request body comes in, gets deserialized into a strongly typed C# object you can work with normally, and the response goes back out the same way. Note also that JsonSerializer.Serialize works fine on record types and even anonymous objects (new { error = "..." }) — it isn't limited to plain classes.

Under the Hood

At a first-look level, it's enough to know that System.Text.Json works by reflecting over your class's public properties (or using source-generated metadata in performance-sensitive scenarios) to figure out how to map each JSON key to a matching .NET property, and vice versa in the other direction. It matches property names against JSON keys case-insensitively during deserialization by default, which is why "customerName" in the JSON still correctly maps to a C# property named CustomerName even without an explicit naming policy configured for that direction.

Common Confusion

1. "JSON is only for JavaScript"

The name is a historical artifact — JSON originated from JavaScript's own object literal syntax, but it long ago became a fully language-independent standard. A C# service, a Python script, and a Java backend can all read and write the exact same JSON with no special JavaScript involved anywhere.

2. Serialize vs. Deserialize — which direction is which

It's easy to mix these up early on: Serialize takes a .NET object and turns it into JSON text (object → string). Deserialize takes JSON text and turns it into a .NET object (string → object). A useful memory hook: "serial" as in a series of characters — serializing produces text.

Common Mistakes

Mistake 1 — Not handling a null deserialization result

Wrong:

Correct:

Mistake 2 — Assuming deserialization always succeeds

Deserializing user-supplied or externally-received JSON without a try/catch. Malformed JSON throws a JsonException — this is exactly the same "boundary with the outside world" reasoning from the file-handling lessons: JSON coming from outside your program deserves the same defensive handling as a file you didn't create yourself.

Mistake 3 — Mismatched casing expectations without a naming policy

Serializing with default settings (PascalCase property names) and sending the result to a JavaScript front end that expects camelCase — the front end's code silently receives undefined for every field because the keys don't match what it's looking for. Set PropertyNamingPolicy = JsonNamingPolicy.CamelCase when the consumer expects it — which, for most public-facing web APIs, is the common default expectation.

When Should I Use It?

Mental Model

Key Takeaway

Check Your Understanding

You've seen why JSON is so widely used and how to serialize and deserialize with System.Text.Json. Let's check your understanding.

You can now serialize and deserialize C# objects to and from JSON with real confidence. Next, and finally in this module: a broader look at serialization itself — what it means beyond just JSON, and how it compares to XML and binary formats.

dotnetmadeeasy.com — Learn C# and .NET, the right way.