Tablice i obiekty JSON: struktura i zagnieżdżanie dla początkujących
Podsumowanie: JSON ma tylko dwa kontenery: obiekt dla nazwanych pól, tablicę dla uporządkowanych list. Naucz się ich łączyć, wybierać właściwy i poprawiać trzy najczęstsze błędy — fałszywe tablice z kluczami numerycznymi, końcowy przecinek i apostrofy.

JSON daje ci tylko dwa kontenery: obiekt niesie nazwane pola, tablica niesie uporządkowane listy — i prawie każdy uszkodzony payload wyjaśnia się cudzysłowami, przecinkami albo listą zapisaną jako fałszywy obiekt.
Pierwsze: JSON ma tylko dwa kontenery
Niezależnie od tego, jak skomplikowana jest odpowiedź API, wszystko redukuje się do dwóch kontenerów i sześciu typów wartości. Obiekt to kolekcja par klucz/wartość w nawiasach klamrowych {}; tablica to uporządkowana lista wartości w nawiasach kwadratowych []. Wartością może być łańcuch, liczba, true, false, null — albo znowu obiekt lub tablica. Obiekty w tablicach, tablice w obiektach: ta rekursja to cała siła wyrazu JSON.
{
"user": { "name": "Ada", "active": true },
"roles": ["admin", "editor"],
"lastLogin": null,
"loginCount": 42
}
Płynie z tego praktyczny wniosek: wobec mylącego payloadu nie czytaj go znak po znaku. Najpierw sprawdź, czy najzewnętrzniejszy znak to { czy [. Jeśli obiekt, czytaj go jako nazwane pola; jeśli tablica, czytaj jako listę, a potem schodź poziom po poziomie. Diagram składni na json.org mieści się na jednej stronie właśnie dlatego, że dwie struktury plus rekursja pokrywają wszystko.
Drugie: pisanie obiektów, cztery twarde reguły
Obiekty to miejsce, w którym początkujący popełniają najwięcej błędów, ale reguły redukują się do czterech:
- Klucze muszą być łańcuchami w cudzysłowach podwójnych.
{name: "Ada"}i{'name': 'Ada'}są oba niepoprawne; trzeba pisać{"name": "Ada"}. Literały obiektów JavaScriptu pozwalają na nagie klucze i apostrofy, JSON nie — to najczęstsze pomylenie obu zapisów. - Oddzielaj pary przecinkami i nigdy nie zostawiaj przecinka po ostatniej.
{"a": 1, "b": 2,}zawodzi zUnexpected token }przy zamykającej klamrze. - Klucze powinny być unikalne. RFC 8259 formułuje to jako SHOULD, nie MUST: zduplikowane klucze nie powodują błędu, ale to, czy zachowane zostanie pierwsze czy ostatnie wystąpienie, zależy od implementacji, a języki się różnią. Nigdy na tym nie polegaj.
- Kolejność kluczy nie ma znaczenia.
{"a":1,"b":2}i{"b":2,"a":1}to ten sam obiekt; narzędzia diff i funkcje porównawcze ignorują kolejność kluczy. Jeśli kolejność ma znaczenie, dane należą do tablicy.
Trzecie: pisanie tablic, kolejność to dane
Tablice przechowują wartości według pozycji, a indeksowanie zaczyna się od 0: w ["admin", "editor"] łańcuch "editor" to [1]. Ta kolejność jest istotna — to istotna różnica między tablicami a obiektami. Wyniki wyszukiwania posortowane po trafności, wpisy logu posortowane po dacie: ta informacja żyje tylko w sekwencji, a zamiana na obiekt ją niszczy.
Dwie praktyczne rady. Po pierwsze, trzymaj elementy jednorodne: [{"id":1},{"id":2}] jest dużo łatwiejsze w odbiorze niż [1, "text", true], które jest legalne, ale zmusza każdego konsumenta do testowania typów na każdym kroku. Po drugie, pusta tablica [] to całkowicie poprawna wartość — gdy pole listy nie ma jeszcze zawartości, wysyłaj [] zamiast null, żeby konsument nie musiał sprawdzać istnienia, a potem pustki.
[
{ "city": "Tokyo", "population": 13960000 },
{ "city": "Delhi", "population": 16780000 }
]
Czwarte: zagnieżdżanie, cztery kształty prawdziwych payloadów
Prawdziwe dane to tylko te dwa kontenery zagnieżdżone jeden w drugim, a wzorce redukują się do czterech kształtów:
| Kształt | Jak wygląda | Typowe zastosowanie |
|---|---|---|
| Obiekt zawierający tablicę | {"tags": ["a","b"]} |
Pole listowe encji |
| Tablica obiektów | [{"id":1},{"id":2}] |
Listy rekordów, wyniki stronicowane |
| Obiekt zawierający obiekt | {"db": {"host": "..."}} |
Grupowana konfiguracja, bloki adresowe |
| Tablica tablic | [[1,2],[3,4]] |
Macierze, wiersze tabeli |
Typowa odpowiedź API używa obiektu jako obudowy i tablicy jako zawartości:
{
"code": 0,
"data": {
"items": [
{ "id": 1, "title": "first" },
{ "id": 2, "title": "second" }
],
"page": 1,
"total": 2
}
}
Nie zagnieżdżaj dla samego zagnieżdżania. Powyżej trzech–czterech poziomów ścieżki dostępu stają się nieczytelne, a kod konsumenta puchnie równolegle. Pola, które zawsze podróżują razem, należą do podobiektu: zamień addrCity i addrZip na address: {city, zip}.
Piąte: obiekt czy tablica, tabela decyzyjna
| Pytanie | Odpowiedź | Dlaczego |
|---|---|---|
| Każda wartość ma nazwę? | Obiekt | Dostęp kluczem; dodanie czy usunięcie pól nic nie psuje |
| To lista podobnych rekordów? | Tablica | Kolejność ma znaczenie; można mapować i filtrować |
| Potrzebne szybkie wyszukiwanie po kluczu? | Obiekt indeksowany identyfikatorem | Dostęp O(1) zamiast przejścia |
| Kilka atrybutów jednej encji? | Obiekt | Atrybuty nie mają własnej kolejności |
| Rosnący zbiór podobnych elementów? | Tablica | Długość rozciąga się swobodnie |
Jedna antywzorzec zasługuje na osobne wspomnienie: imitowanie tablicy obiektem z kluczami "0", "1", "2". Parsuje się bez błędu, ale tracisz semantykę długości i narzędzia iteracji prawdziwej tablicy, a konsumenci muszą przed czytaniem czegokolwiek sortować Object.keys. Jeśli klucze to kolejne numery, pisz prawdziwą tablicę. Odwrotność też obowiązuje: lista par klucz/wartość typu [{"key":"theme","value":"dark"}] jest gorsza od obiektu {"theme": "dark"} — chyba że klucze są naprawdę dynamiczne i nie da się ich zadeklarować z góry.
Szóste: trzy częste błędy i ich komunikaty
| Błędna forma | Typowy błąd | Poprawka |
|---|---|---|
Końcowy przecinek {"a":1,} |
Unexpected token } |
Usunąć ostatni przecinek |
Apostrofy / nagie klucze {name:'Ada'} |
Unexpected token ' / Expected property name |
Podwójne cudzysłowy dla kluczy i łańcuchów, zawsze |
Literały Pythona True / None |
Unexpected token T |
Zamienić na true / null |
| Fałszywa tablica z kluczami numerycznymi | Bez błędu, zła semantyka | Przepisać jako prawdziwą tablicę |
Dwa nawyki debugowania: parsery zwykle wskazują pozycję po winnym znaku, więc widząc position 42, spójrz o jeden–dwa znaki wstecz; a ogromny JSON w jednej linii najpierw sformatuj — numery linii i kolumn zawsze biją przesunięcia znaków. Pełny katalog błędów jest w tablicy wyszukiwania błędów JSON, a krok po kroku proces triage w jak naprawić błędy parsowania JSON.
Siódme: po napisaniu zweryfikuj strukturę
JSON pisany ręcznie powinien przed przekazaniem zawsze przejść przez parser. Najlżejsza weryfikacja mieści się w jednej linii polecenia:
python3 -m json.tool config.json > /dev/null && echo OK
jq empty config.json && echo OK
Online wklej zawartość na stronę formatowania i walidacji JSON — błędy składni wrócą z linią i kolumną. Przełącz się na widok drzewa, by z jednego spojrzenia zobaczyć typ każdego poziomu: czy jakaś liczba została odczytana jako łańcuch, czy długości tablic się zgadzają. A gdy odbiorcy nie są techniczni, payload tablica-obiektów można rozłożyć na wiersze i kolumny na stronie JSON do tabeli — przy okazji sprawdzisz, czy twoje dane naprawdę tworzą regularną listę rekordów.
Pytania o pole, które powinno być tablicą, albo o przebudowę zbyt głębokiego zagnieżdżenia, należą do modelowania typów — kolejna lektura: sześć typów, precyzja liczb i pułapki kodowania.
Czy tablice i obiekty JSON można wzajemnie konwertować?
Można, ale nie bez strat. Konwersja obiektu na tablicę zwykle oznacza zamianę kluczy na wartości i utratę dostępu kluczem; konwersja tablicy na obiekt wymaga wymyślenia klucza dla każdego elementu, a pochodzenie tych kluczy to nowy problem projektowy. Decyduj według tego, jak konsument czyta dane, nie według wygody składniowej.
Czy klucze obiektu mogą się duplikować?
Składniowo tak — RFC 8259 mówi tylko, że klucze POWINNY być unikalne. Ale JavaScript zachowuje ostatnią wartość, podczas gdy niektóre biblioteki z rodziny C zachowują pierwszą: zachowanie różni się między parserami. W podpisach, diffach czy skrótach zduplikowane klucze dają bezpośrednie rozbieżności. Unikaj ich po stronie producenta, a duplikaty z nieznanego źródła traktuj jako ryzyko po stronie konsumenta.
Czy tablica może zawierać wartości różnych typów?
Składniowo tak: [1, "a", true] to poprawny JSON. Ale niejednorodne tablice zmuszają konsumenta do sprawdzania typów na każdej pozycji i trudno je wyrazić w schemacie. Poza macierzami i krotkami — gdzie pozycją jest sama semantyka — trzymaj tablice jednorodne.
Dlaczego {name:'json'} nie przechodzi walidacji?
Bo JSON wymaga podwójnych cudzysłowów wokół każdego klucza i każdej wartości łańcuchowej. {name:'json'} to literał obiektu JavaScriptu, nie JSON. Zamień go na {"name": "json"}, a walidacja przejdzie. Apostrofy, nagie klucze i komentarze należą do dialektów typu JSON5/JSONC, które wymagają własnych parserów zamiast standardowego JSON.parse.