Основи синтаксису та структури JSON

1. Згадуємо JSON

JSON — абревіатура від JavaScript Object Notation. Попри слово JavaScript у назві, цей формат мовно нейтральний і сумісний із більшістю мов програмування, зокрема з C#. Його створили, щоб зручно й зрозуміло описувати дані — об’єкти, масиви, списки та словники — у вигляді звичайного тексту.

Сьогодні, коли майже кожна програма спілкується з іншими, JSON став де-факто стандартом серіалізації та обміну структурованими даними. Його використовують повсюдно: від REST API до зберігання користувацьких налаштувань і навіть для внутрішньої взаємодії між мікросервісами. Є на те добра причина — він зрозумілий для людини, простий у розборі та підтримується всіма сучасними мовами й бібліотеками.

Чому не XML?

JSON простіший, компактніший і краще читається, ніж XML. До того ж без зайвого шуму й тегів він краще відповідає структурам даних більшості мов програмування. А ще не доводиться стежити за закривальними тегами, лапками та іншою XML-бюрократією. Отже, JSON — це про «швидше, простіше, зручніше».

2. Основні елементи синтаксису JSON

Уявімо JSON як просте дерево з вкладеними рівнями, яке складається з об’єктів, масивів і елементарних даних. Ось які «цеглинки» маємо в розпорядженні:

Об’єкти (Objects)

Об’єкт JSON — це набір пар «ключ: значення», укладений у фігурні дужки { }.

Приклад:

{
  "name": "Alice",
  "age": 23
}

У C# таку структуру можна подати у вигляді класу або словника.

Масиви (Arrays)

Масив JSON — це впорядкований список елементів (значень будь-якого типу), укладений у квадратні дужки [ ].

Приклад:

[1, 2, 3, 42]

Або так:

[
  {"name": "Ivan"},
  {"name": "Olga"}
]

У C# — це List<T>, T[] та аналогічні колекції.

Пари «ключ-значення»

Ключі завжди рядки (у подвійних лапках!), а значення можуть бути будь-яких типів даних, дозволених у JSON.

Приклад:

{
  "id": 123,
  "login": "student",
  "isActive": true
}

Типи даних у JSON

10, -5, 3.14

"hello"

true, false

null

{"a":1}

[1,2,3]

Приклад — усе разом:

{
  "id": 1,
  "name": "Bob",
  "scores": [10, 20, 30],
  "profile": {
    "email": "bob@mail.com",
    "phone": null
  },
  "isAdmin": false
}

Бачите, як компактно й логічно можна описати цілий об’єкт користувача.

3. Правила оформлення JSON

Рядки завжди у подвійних лапках

Навіть якщо дуже хочеться поставити одинарні, JSON цього не пробачить. Ось так — правильно:

{ "name": "Vera" }

А так — помилка:

{ 'name': 'Vera' }

Ключі — лише рядки

На відміну від C#, де ключ словника може бути хоч int, хоч enum, у JSON ключ — це завжди рядок:

{ "2025": "Рік C#", "favorite": true }

Жодних кінцевих ком

На відміну від масивів і об’єктів у C#, зайва кома перед закривальною дужкою — це синтаксична помилка JSON!

// ПОМИЛКА! (кінцева кома не допускається)
{
  "id": 10,
  "name": "Oleg",
}

Правильно:

{
  "id": 10,
  "name": "Oleg"
}

Пробіли та переноси рядків

Їх можна додавати для читабельності, аналізатори їх ігнорують. Зазвичай для «людського» формату використовують pretty-printed (відформатований) JSON, для передавання мережею — minified (в один рядок, без пробілів).

4. Як C#-об’єкти перетворюються на JSON

Якщо серіалізувати об’єкт за допомогою System.Text.Json.JsonSerializer.Serialize(), поля та властивості об’єкта перетворюються на пари «ключ-значення».

Приклад C#-класу та серіалізації

public class Book
{
    public string Title { get; set; }
    public int Pages { get; set; }
}
var book = new Book { Title = "CLR via C#", Pages = 900 };
string json = JsonSerializer.Serialize(book);
Console.WriteLine(json); // {"Title":"CLR via C#","Pages":900}

Колекції

• List<int> перетворюється на [1,2,3]
• string[] перетворюється на ["hi", "wow"]
• List<Person> — у масив об’єктів

Словники

Словник виду Dictionary<string, int> перетворюється на об’єкт:

var dict = new Dictionary<string, int>
{
    ["apples"] = 5, ["bananas"] = 10
};
string json = JsonSerializer.Serialize(dict);
// {"apples":5,"bananas":10}

5. Візуальна схема: як будується JSON

Вкладеність — шар за шаром

Об'єкт
│
├── Пара: "name": "Alex"
├── Пара: "hobbies": масив
│               │
│               ├── "skiing"
│               └── "programming"
└── Пара: "profile": об'єкт
                 │
                 ├── "age": 42
                 └── "city": "Базель"

У підсумку:

{
  "name": "Alex",
  "hobbies": ["skiing", "programming"],
  "profile": {
    "age": 42,
    "city": "Базель"
  }
}

6. Типові помилки та особливості синтаксису

У програмуванні не буває ідеального світу — навіть у JSON є свої пастки! Якщо ви надішлете JSON із неправильними лапками, із зайвими комами або з ключами, не взятими в лапки, аналізатор видасть помилку.

Є ще один підводний камінь — числа з провідними нулями. У JSON це заборонено (наприклад, 0123 — помилка).

Корисно знати: Деякі аналізатори, наприклад JSON.parse у JavaScript, поблажливіші й можуть «пробачити» дрібні відхилення. Але більшість суворих аналізаторів (зокрема в C# та .NET) повідомлятимуть про найменше порушення синтаксису.

7. Приклади перетворення C#-даних у JSON

Давайте спробуємо серіалізувати складну структуру на практиці. Наш навчальний застосунок розвивається: припустімо, у нас тепер є список студентів, і ми хочемо зберегти їх у файл JSON.

Визначимо клас:

public class Student
{
    public string Name { get; set; }
    public int Age { get; set; }
}

Заповнимо список:

var students = new List<Student>
{
    new Student { Name = "Ганна", Age = 20 },
    new Student { Name = "Микита", Age = 22 }
};

Серіалізація:

using System.Text.Json;

// Серіалізуємо список студентів у рядок JSON
string json = JsonSerializer.Serialize(students, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

/*
[
  {
    "Name": "Ганна",
    "Age": 20
  },
  {
    "Name": "Микита",
    "Age": 22
  }
]
*/

Бачите, як зручно? Кожен студент — це окремий об’єкт усередині JSON-масиву.

8. Міні-генератор: як «вручну» написати JSON

Іноді доводиться писати JSON самостійно, наприклад створювати тестові дані. Ось чекліст:

1. Зовнішні фігурні дужки — для об’єкта, зовнішні квадратні — для масиву.
2. Ключ — завжди рядок у подвійних лапках.
3. Значення — рядки (у подвійних лапках), числа, true, false, null, об’єкт ({}), масив ([]).
4. Коми — лише між елементами, не після останнього!
5. Відступи й пробіли для читабельності (але не обов’язкові).