JSON-LD wyjaśniony
JSON-LD to zwykły JSON z jedną dodatkową linią, która mówi, co znaczą pola. Ta linia zamienia lokalną nazwę pola w nazwę zdefiniowaną globalnie, dzięki czemu system, który nigdy nie widział Twoich danych, i tak zorientuje się, o czym mówisz. Jest standardem W3C od 2014 roku, w ten sposób wyszukiwarki czytają właśnie tę stronę, i na tym opiera się model danych W3C dla weryfikowalnych poświadczeń.
Problem ze zwykłym JSON-em
JSON mówi, jak zapisuje się dane. Nie mówi nic o tym, co one znaczą. Pole o nazwie name może być osobą, firmą albo produktem. Pole o nazwie id może być numerem klienta, numerem paszportu albo wierszem w czyjejś bazie danych. Dwa systemy mogą wytwarzać całkowicie poprawny JSON i mimo to nie zgadzać się co do każdego jego pola.
W praktyce lukę zamyka się umową. Obie strony spisują, co znaczą pola, i budują pod to swoje oprogramowanie. To działa przy jednej integracji, robi się drogie przy dziesięciu i przestaje działać zupełnie, gdy poświadczenie wydane w jednym kraju ma zrozumieć weryfikator w innym, z którym nikt wcześniej nie rozmawiał.
Co robi @context
JSON-LD zamyka tę lukę wewnątrz samego dokumentu. @context przypisuje każdej skróconej nazwie pola globalnie unikalny identyfikator, zwykle adres URL kontrolowany przez tego, kto zdefiniował słownik. Pole pozostaje krótkie i czytelne dla człowieka, a staje się jednoznaczne dla maszyny.
Zwykły JSON
{
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Poprawny, czytelny i pozbawiony znaczenia dla każdego, komu nikt wcześniej nie powiedział, co powinno znaleźć się w polach.
Te same dane jako JSON-LD
{
"@context": "https://schema.org",
"@type": "Person",
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Każde pole wskazuje teraz opublikowaną definicję, więc system, który nigdy nie widział tego dokumentu, i tak odczyta go poprawnie.
- @context wskazuje słownik, w którym zdefiniowane jest każde pole dokumentu.
- @type mówi, jakiego rodzaju rzecz opisuje dokument, aby z tego słownika wybrano właściwe definicje.
W samych danych nic się nie zmienia. Te same wartości w tej samej postaci niosą teraz wskaźnik do definicji każdego pola. System odbierający, który rozpoznaje słownik, wie dokładnie, co dostał, a taki, który go nie rozpoznaje, nadal może odczytać dokument jak zwykły JSON i zignorować resztę.
Na tym polega cała idea. Znaczenie podróżuje razem z dokumentem, zamiast mieszkać w specyfikacji, co do której obie strony musiały się wcześniej dogadać.
Gdzie pojawia się w weryfikowalnych poświadczeniach
W3C Verifiable Credentials Data Model 2.0, od 15 maja 2025 roku W3C Recommendation, jest zbudowany na JSON-LD. Każde poświadczenie zaczyna się od @context, którego pierwszą wartością jest wspólny słownik poświadczeń, więc pojęcia wspólne wszystkim poświadczeniom, wydawca, podmiot, daty ważności i informacja o statusie, znaczą wszędzie to samo.
Wszystko poza tym pochodzi z drugiego słownika. Uczelnia publikuje jeden dla pól dyplomu, izba handlowa jeden dla pól rejestracji przedsiębiorstwa. Weryfikator, któremu zależy na dyplomach, ładuje pierwszy, weryfikator, któremu zależy na danych firmowych, ładuje drugi, i żaden z nich nie musi się zmieniać, gdy drugi dodaje pole.
To właśnie pozwala jednemu formatowi poświadczeń nieść dane, których nikt nie przewidział, gdy format powstawał, a jest to własność potrzebna otwartemu ekosystemowi i niepotrzebna zamkniętemu profilowi.
Podpisywanie połączonych danych
Poświadczenie trzeba też podpisać, a model danych celowo zostawia tu wybór. Dowód opakowujący zamyka całe poświadczenie w kontenerze podpisu, takim jak JWT. Bajty są podpisywane dokładnie takie, jakie są, więc wszystko, co po drodze zmieni ich kolejność lub formatowanie, łamie podpis.
Osadzony dowód Data Integrity działa odwrotnie. Dokument najpierw sprowadza się do postaci kanonicznej, zdefiniowanej przez RDF Dataset Canonicalization i będącej W3C Recommendation od 21 maja 2024 roku, a podpis obejmuje tę postać, a nie bajty. Ponieważ postać kanoniczna nie zależy od kolejności kluczy, od spacji ani od tego, jakich krótkich nazw akurat używa @context, podpis przetrwa ponowne zapisanie dokumentu gdzie indziej.
Gdzie mieści się w EUDI Wallet
Nie tam, gdzie większość zakłada. Architecture and Reference Framework wskazuje dwa formaty poświadczeń dla europejskiego portfela, SD-JWT VC i mdoc, i żaden z nich nie jest JSON-LD. Organizacja wydająca dziś do EUDI Wallet nie napotka po drodze żadnego @context.
Powodem jest wykonalność. Oba formaty mają stałą strukturę, jeden mechanizm podpisu i żadnego dokumentu, po który weryfikator musiałby sięgnąć, zanim cokolwiek sprawdzi. Dla portfela działającego na telefonie i weryfikatora, który musi odpowiedzieć w milisekundach, jest to warte więcej niż otwarty słownik.
JSON-LD zasługuje na swoje miejsce tam, gdzie dane muszą podróżować poza ekosystem, który je zdefiniował: paszporty produktów i dane łańcucha dostaw, pilotaże międzysektorowe oraz typy poświadczeń, których żaden centralny profil nigdy nie wyliczy. Te dwa światy częściej się nakładają, niż konkurują, a organizacje działające w obu zwykle kończą na wspieraniu jednego i drugiego.
Ten drugi JSON-LD, z którego już korzystasz
Na długo przed poświadczeniami JSON-LD stał się sposobem, w jaki witryna mówi wyszukiwarce, o czym jest strona. Jego blok w źródle strony, korzystający ze słownika schema.org, sprawia, że strona staje się rozpoznanym artykułem, produktem, wydarzeniem lub organizacją. Ta strona nosi taki blok.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "JSON-LD wyjaśniony",
"description": "Co JSON-LD dodaje do zwykłego JSON-a, jak @context nadaje każdemu polu jedno znaczenie i gdzie korzystają z niego weryfikowalne poświadczenia.",
"image": "https://www.credenco.com/images/og-default.jpg",
"datePublished": "2026-10-15",
"dateModified": "2026-10-15",
"inLanguage": "pl",
"mainEntityOfPage": "https://www.credenco.com/pl/explained/json-ld",
"author": {
"@type": "Organization",
"name": "Credenco",
"url": "https://www.credenco.com/"
},
"publisher": {
"@type": "Organization",
"name": "Credenco",
"logo": {
"@type": "ImageObject",
"url": "https://www.credenco.com/logo.svg"
}
}
}To ten sam format z innym słownikiem i najjaśniejszy sposób, by zobaczyć sedno. Nikt tutaj nie umówił się z żadną wyszukiwarką. @context wskazuje schema.org, wyszukiwarka zna już ten słownik, a strona jest rozumiana przez stronę, z którą nigdy nie rozmawiała. Poświadczenie przekraczające granicę robi dokładnie to samo.
Ile to kosztuje
Kontekst musi być dostępny. Weryfikator, który pobiera go w momencie weryfikacji, dołożył zależność sieciową do decyzji bezpieczeństwa, a ten, kto serwuje ten dokument, może zmienić to, co poświadczenie zdaje się mówić. Prawdziwe wdrożenia przypinają akceptowane konteksty i dostarczają je razem z oprogramowaniem, zamiast rozwiązywać je na żywo.
Kanonizacja też jest prawdziwą pracą. Przekształcenie dokumentu w kanoniczny zbiór danych przed podpisaniem to znacznie więcej kodu niż podpisanie bajtów, a sposoby, w jakie może zawieść, są subtelne. Dokumenty są poza tym większe, co zaczyna się liczyć na kodzie QR albo przy zbliżeniu NFC.
Nic z tego nie czyni z JSON-LD złego wyboru. Czyni z niego wybór: zapłać za otwarte słowniki tam, gdzie dane muszą przetrwać dłużej niż umowa, która je stworzyła, i zrezygnuj z nich tam, gdzie stały profil mówi już wszystko, czego obie strony potrzebują.
Co to oznacza dla ciebie
Wydawca
Wydawanie do EUDI Wallet oznacza SD-JWT VC albo mdoc, a JSON-LD nigdy się nie pojawia. Wydawanie do ekosystemu W3C czyni z Twojego @context zobowiązanie długoterminowe: jest publiczną definicją Twoich pól, a jego zmiana psuje każdy weryfikator, który zapisał w pamięci podręcznej poprzednią wersję.
Weryfikator
Zdecyduj, które konteksty akceptujesz, i dostarczaj je razem ze swoim oprogramowaniem. Pobranie jednego w trakcie weryfikacji czyni zdalny serwer częścią Twojej decyzji bezpieczeństwa i wstawia wywołanie sieciowe w środek Twojego czasu odpowiedzi.
Deweloper
Czytaj dokument JSON-LD jak zwykły JSON, gdy potrzebujesz tylko jednego pola, a po pełny procesor sięgaj dopiero tam, gdzie naprawdę rozwijasz albo kanonizujesz. Większość złożoności przypisywanej JSON-LD siedzi w ścieżce podpisu, a nie w ścieżce odczytu.
Powiązane pojęcia
Najczęściej zadawane pytania
Czy JSON-LD to wciąż po prostu JSON?
Tak. Każdy dokument JSON-LD jest poprawnym JSON-em, a oprogramowanie, które musi odczytać tylko jedno pole, może go tak traktować. Dodatkowa maszyneria wchodzi do gry dopiero wtedy, gdy rozwijasz dokument do pełnej postaci albo kanonizujesz go do podpisu, czego większość kodu czytającego poświadczenie nigdy nie robi.
Czy EUDI Wallet używa JSON-LD?
Nie. Architecture and Reference Framework wskazuje SD-JWT VC i mdoc jako formaty poświadczeń, a żaden z nich nie używa JSON-LD. Ma to znaczenie dla ekosystemów W3C z weryfikowalnymi poświadczeniami, dla paszportów produktów i danych łańcucha dostaw, a nie dla samego europejskiego portfela.
Czy weryfikator pobiera @context za każdym razem?
Nie powinien. Pobieranie kontekstu w trakcie weryfikacji umieszcza wywołanie sieciowe wewnątrz decyzji bezpieczeństwa i daje zdalnemu serwerowi możliwość zmiany tego, co dokument zdaje się mówić. Implementacje przypinają akceptowane konteksty i dostarczają je razem z oprogramowaniem, co usuwa również opóźnienie.
Czy to ten sam JSON-LD, który czytają wyszukiwarki?
Ten sam format z innym słownikiem. Dane strukturalne na stronie internetowej kierują swój @context do schema.org, a poświadczenie kieruje go do słownika poświadczeń i do tego, czego jeszcze potrzebuje. Reguły przetwarzania są w obu przypadkach identyczne.
Źródła
Ta strona ma charakter informacyjny i nie stanowi porady prawnej. Po wiążące wskazówki sięgnij bezpośrednio do specyfikacji W3C.