JSON Toolkit

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.

Początkujący~6 min czytaniaOpublikowano 2026-11-20Zaktualizowano 2026-11-20
Okładka wprowadzenia do struktur tablic i obiektów JSON

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:

  1. 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.
  2. Oddzielaj pary przecinkami i nigdy nie zostawiaj przecinka po ostatniej. {"a": 1, "b": 2,} zawodzi z Unexpected token } przy zamykającej klamrze.
  3. 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.
  4. 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.