1. Introduction
If you've ever opened modern APIs, worked with web services, mobile apps or even just tried to save something in a "universal format" — you've already met or will meet JSON. It's the format that basically "connects" different programming languages and even different platforms: C#, JavaScript, Python — they all talk using JSON.
Why did JSON become the serialization star? The answer is simple: it's a compact, human-readable, lightweight text format for exchanging structured data. Its popularity is the result of a good mix of simplicity, universality and excellent support across programming languages.
What is JSON?
JSON stands for JavaScript Object Notation. The format came from the JavaScript world but very quickly jumped out of browsers into the wider world. Important: despite the name origin, JSON is not tied to JavaScript and is equally handy for all programming languages.
The format was invented in the early 2000s by Douglas Crockford as a simpler alternative to verbose XML. The idea is simple: "JSON is shorter, simpler and easier to read by humans".
2. Core rules of the JSON format
Main thing: JSON is a strictly defined text format for structured data. No magic, just plain text you can open in any editor.
Basic constructs:
- Arrays (arrays): ordered lists of values.
- Objects (objects): sets of key-value pairs.
- Primitive types: strings, numbers, boolean values (true, false) and the special value null.
Example of a minimal JSON document:
{
"name": "Ivan",
"age": 25,
"isStudent": true,
"scores": [5, 4, 5, 3],
"contacts": {
"email": "ivan@example.com",
"phone": null
}
}
Schematic mapping
Here is a simple table of mappings between C# types and JSON representations:
| C# type | JSON example |
|---|---|
|
|
|
|
|
|
| array (int[], ...) | |
| object (class, ...) | |
|
|
Rules for writing JSON
- Strings must be in double quotes: 'text' — error, correct is "text".
- Object keys must be strings in double quotes: for example, "name": ...
- Commas only between elements, no trailing comma after the last element.
- Indentation is not required but improves readability.
- Numbers without quotes: "age": 25, not "age": "25".
- Boolean values are true/false (without quotes), not True, FALSE or "true".
- null is written as null (without quotes).
3. JSON from a programmer's perspective
Analogies with C# types:
- JSON object ≈ Dictionary<string, object>
- JSON array ≈ T[] or List<T>
- JSON string ≈ a regular string
- JSON number ≈ int or double (depending on the value)
Example of serializing an object to JSON
Class:
public class Student
{
public string Name { get; set; } = "";
public int Age { get; set; }
public bool IsStudent { get; set; }
public int[] Scores { get; set; } = Array.Empty<int>();
}
Resulting JSON (simplified, serialization details later):
{
"Name": "Ivan",
"Age": 25,
"IsStudent": true,
"Scores": [5, 4, 5, 3]
}
4. Examples of valid JSON structures
Object with an array and nested objects
{
"product": "Coffee",
"price": 125.50,
"inStock": true,
"attributes": {
"weight": 500,
"unit": "gr"
},
"tags": ["beverage", "energy", "arabica"],
"promotions": null
}
Array of objects
[
{"id": 1, "name": "Petya"},
{"id": 2, "name": "Masha"},
{"id": 3, "name": "Vasya"}
]
5. Examples of invalid JSON (and why)
Single quotes:
{ 'name': 'Ivan' } // Error!
JSON requires double quotes.
Trailing comma after the last element:
{ "x": 1, "y": 2, } // Error!
An extra comma at the end is not allowed.
Comments:
{
// Unfortunately this kind of beauty doesn't work in JSON
"name": "Ivan"
}
JSON has no comments.
6. Why JSON is needed in real projects?
Data transfer between systems
JSON is a universal "common language" between different programs, most often over HTTP. For example, a server written in C# talks to a frontend in JavaScript — their shared format is JSON.
Storing settings and data
Many applications store settings in .json files. For example, appsettings.json — a standard for .NET apps. Pros: easy to read, change and version.
Server and mobile APIs
Most REST APIs use JSON as the request and response format: e.g., a list of users comes as an array of objects.
Configuration of tools and libraries
Many tools in .NET (Serilog, Swagger, etc.) use JSON for configuration. XML is getting rarer — JSON is more compact and clearer.
7. JSON popularity: why everyone loves it?
- Readability. Even a non-developer can figure out what's what.
- Networking convenience. Plain text, low "weight".
- Support in all languages. Serialization/deserialization is often available "out of the box".
- Good for configs. Any editor works well with it.
- Easy to generate. Creating JSON is trivial.
- Arrays, nesting, null. Everything is intuitive, without the "bracket fever" you get with XML.
When to choose JSON?
- You're building a mobile or web app;
- You're working with external service APIs;
- You want your app to be integration-friendly in the future.
8. How C# works with JSON
Briefly about popular .NET libraries:
- System.Text.Json — the standard, fast and simple option.
- Newtonsoft.Json (Json.NET) — the veteran with a huge set of features.
Minimal example of serialization/deserialization:
using System.Text.Json;
// Convert an object to a JSON string
var student = new Student { Name = "Ivan", Age = 25, IsStudent = true, Scores = new[] {5, 4, 5, 3} };
string json = JsonSerializer.Serialize(student);
// And the other way: read an object from a JSON string
Student? parsed = JsonSerializer.Deserialize<Student>(json);
Console.WriteLine(json);
9. Typical mistakes beginners make when working with JSON
A common mistake is mixing up quotes or forgetting a comma. Sometimes people try to add comments (like in C# — because it's handy!), but JSON won't forgive that.
Another frequent situation is serializing objects with uninitialized collections: you end up with "scores": null instead of the expected array. Initialize collections in advance.
Remember that JSON is text: large amounts of data take a lot of memory. If you serialize, say, 500 MB to JSON, the application can noticeably drop in performance.
GO TO FULL VERSION