Języki

JSON-LD — przewodnik po danych strukturalnych

JSON-LD to oparty na skrypcie format danych strukturalnych zalecany przez Google — łatwy do wdrożenia, niezależny od widocznego HTML i zwykle łączony ze słownikiem schema.org w SEO.

Opublikowano po raz pierwszy: 26 cze 2026 · Ostatnia aktualizacja: 11 sie 2026 · Advanced
Języki
AIAutor:AI v2
1 sygnał dowodowy na tej stronie

JSON-LD (notacja obiektowa JavaScriptu dla danych połączonych) to format danych strukturalnych umieszczany w znaczniku <script type="application/ld+json">. W SEO zwykle korzysta ze słownika schema.org do opisywania treści strony, ale może stosować także inne słowniki. Jest standardem W3C od 2014 roku. Google zaleca go zamiast Microdata i RDFa ze względu na łatwiejsze wdrażanie i utrzymanie na dużą skalę, ponieważ osobny blok nie ingeruje w widoczny HTML; wszystkie trzy formaty działają równie dobrze, jeśli są poprawnie zaimplementowane. Podstawę składni tworzą @context (słownik), @type (typ encji) i opcjonalny @id (stabilny URI do łączenia encji, używany m.in. we wzorcu @graph). Googlebot renderuje JavaScript, lecz testy części robotów AI, w tym GPTBot i ClaudeBot, wykazywały brak wykonywania JS. To zachowanie zależy od dostawcy i czasu, dlatego należy je sprawdzać, a nie zakładać. Dane strukturalne nie są sygnałem rankingowym; wpływają na kwalifikację do wyników rozszerzonych i zrozumienie encji oraz muszą opisywać treść widoczną na stronie.

TL;DR — JSON-LD (notacja obiektowa JavaScriptu dla danych połączonych) jest rekomendacją W3C z 2014 roku. Bazuje na JSON, lecz dopiero @context nadaje danym charakter połączony. Google zaleca ten format, ponieważ łatwo go wdrażać i utrzymywać bez ingerencji w widoczny HTML; poprawne Microdata i RDFa są równie ważne. Rdzeń składni tworzą @context (słownik), @type (typ encji) i opcjonalny @id (stabilny URI do odwołań, m.in. we wzorcu @graph). Kod może znajdować się w <head> albo <body>. Googlebot renderuje JS, więc widzi dynamiczny JSON-LD; testy części robotów AI, w tym GPTBot i ClaudeBot, wskazywały brak wykonywania JS, ale zależy to od dostawcy i czasu. Weryfikuj konkretnego robota i renderuj po stronie serwera wszystko, czego nie możesz potwierdzić. Dane strukturalne nie są sygnałem rankingowym — umożliwiają wyniki rozszerzone, wspierają rozumienie encji i muszą odpowiadać treści widocznej na stronie.

JSON-LD jest formatem, a nie słownikiem

Najpierw ważne rozróżnienie: JSON-LD to format, a schema.org to słownik. JSON-LD określa, jak zapisać znaczniki; typy Article, Product i Organization ze schema.org określają, co opisujemy. Wyniki rozszerzone stanowią warstwę funkcji zbudowaną nad nimi. Ten artykuł dotyczy formatu. Zastosowanie słownika w AI omawia tekst Schema Markup for AI.

JSON-LD jest rekomendacją W3C opublikowaną po raz pierwszy w 2014 roku. Powstał z myślą o interoperacyjności danych połączonych w internecie, zanim przyjął się w SEO. To wyjaśnia istnienie takich właściwości jak @id: JSON-LD nie jest zwykłym JSON-em. Korzysta ze składni JSON, ale deklaracja @context sprawia, że dane można identyfikować i łączyć. Bez niej parser nie wie, jak interpretować terminy.

JSON-LD nie jest też na stałe związany ze schema.org. Specyfikacja pozwala, aby @context wskazywał dowolny opublikowany słownik. JSON-LD odpowiada więc na pytanie „w jakim formacie?”, a schema.org — najczęstsza odpowiedź w wyszukiwaniu i AI — na pytanie „z jakiego słownika?”. Strona może poprawnie korzystać z innego słownika, ale nie będą to już znaczniki schema.org.

JSON-LD a Microdata i RDFa

Google obsługuje trzy sposoby zapisu danych strukturalnych:

JSON-LDMicrodataRDFa
Gdzie się znajdujeOsobny blok <script>Atrybuty itemprop w kodzie HTMLAtrybuty property w kodzie HTML
Czy ingeruje w widoczny HTML?NieTakTak
Czy można go wstrzyknąć przez JS lub menedżera tagów?Tak, bez komplikacjiNiewygodnieNiewygodnie
Stanowisko GoogleZalecanyObsługiwanyObsługiwany
Podatność na błędyNajniższaWyższa, bo splata się z HTMLWyższa, bo splata się z HTML

Zalecenie Google jest wyraźne, ale ma wąski zakres: “In general, Google recommends using JSON-LD for structured data if your site’s setup allows it, as it’s the easiest solution for website owners to implement and maintain at scale (in other words, less prone to user errors).” (tłumaczenie) „Ogólnie Google zaleca stosowanie JSON-LD do danych strukturalnych, jeśli pozwala na to konfiguracja witryny, ponieważ jest to najłatwiejsze rozwiązanie do wdrażania i utrzymywania na dużą skalę (innymi słowy, mniej podatne na błędy użytkownika)”.

Na tej samej stronie Google dodaje ważne zastrzeżenie: “All 3 formats are equally fine for Google, as long as the markup is valid and properly implemented per the feature’s documentation.” (tłumaczenie) „Wszystkie trzy formaty są dla Google równie odpowiednie, o ile znaczniki są poprawne i wdrożone zgodnie z dokumentacją danej funkcji”. Zalecenie dotyczy więc łatwości wdrożenia i liczby błędów, a nie szybkości parsowania czy przewagi rankingowej. Microdata nie jest karane; JSON-LD po prostu nie splata danych strukturalnych z kodem, który projektant może jutro zmienić.

Składnia: @context, @type, @id, właściwości i zagnieżdżanie

Oto opisany blok Article:

<script type="application/ld+json">
{
  "@context": "https://schema.org",          // the vocabulary — the common value for SEO
  "@type": "Article",                          // the entity type
  "@id": "https://example.com/post#article",   // a stable URI for this entity
  "headline": "How JSON-LD Works",            // a property (key/value)
  "datePublished": "2026-06-26",
  "author": {                                  // a nested entity
    "@type": "Person",
    "name": "Patrick Stox",
    "url": "https://patrickstox.com/"
  }
}
</script>
  • @context — ustanawia ramy semantyczne, czyli słownik. W znacznikach SEO opartych na schema.org zwykle przyjmuje wartość "https://schema.org", ale jest to konwencja, nie wymóg. Mapuje terminy na identyfikatory i mówi parserowi, jak interpretować kolejne nazwy właściwości. To dzięki niemu dane są połączone.
  • @type — deklaruje encję, na przykład Article, Product, Organization lub BreadcrumbList. Wybieraj najbardziej szczegółowy właściwy typ, np. NewsArticle zamiast Article, gdy odpowiada treści.
  • @id — unikalny URI identyfikujący zasób. Pozwala odwoływać się do encji z innych miejsc, ale nie jest wymagany zawsze. Specyfikacja dopuszcza anonimowe puste węzły, więc encje, do których nie trzeba się odwoływać, mogą nie mieć @id.
  • Właściwości — zwykłe pary klucz–wartość JSON korzystające z terminów słownika określonego w @context.
  • Zagnieżdżanie — encje podrzędne zapisuje się jako zagnieżdżone obiekty JSON, takie jak author powyżej, albo tablice obiektów.

Wzorzec @graph — rozwiązanie skalowalne

Większość stron opisuje więcej niż jedną encję: Organization, WebSite, BreadcrumbList oraz sam Article lub WebPage. Naiwnym rozwiązaniem są cztery osobne bloki <script> powtarzające dane. Alternatywą jest jeden blok z @graph: tablicą encji powiązanych przez @id. Ani specyfikacja JSON-LD, ani Google nie wymagają tego wzorca. Poprawne są też osobne bloki typowane, obiekty zagnieżdżone bez nadrzędnego @graph i puste węzły bez @id. W witrynie z wieloma powiązanymi encjami @graph ogranicza jednak powtarzanie danych Organization i WebSite:

Declare each entity once and connect the graph with stable `@id` references instead of repeating full objects. Źródło: Nested Schema

One Organization is referenced as publisher by the WebSite and Article. The WebPage belongs to the WebSite and is connected to the Article. Each entity is declared once, and the same stable ID string is reused for every reference.

© Patrick Stox LLC · CC BY 4.0 · 

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#org",
      "name": "Example Co",
      "url": "https://example.com/"
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com/",
      "publisher": { "@id": "https://example.com/#org" }   // reference, not a copy
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/post#webpage",
      "isPartOf": { "@id": "https://example.com/#website" },
      "breadcrumb": { "@id": "https://example.com/post#breadcrumb" }
    }
  ]
}
</script>

Zdefiniuj Organization raz, a w innych miejscach wskazuj go przez { "@id": "...#org" }, zamiast powtarzać nazwę, logo i URL. Tak działają główne wtyczki schema w systemach CMS. Bing opisuje tę zaletę następująco: JSON-LD “makes defining links and relationships between data and entities… easy because it supports nested data.” (tłumaczenie) „ułatwia definiowanie odsyłaczy i relacji między danymi i encjami, ponieważ obsługuje dane zagnieżdżone”.

Gdzie umieścić kod: <head> czy <body>

Google potwierdza, że oba miejsca działają: “You can put the JSON-LD data in the <head> or the <body> of the page.” (tłumaczenie) „Dane JSON-LD można umieścić w sekcji <head> lub <body> strony”. <head> jest konwencją, lecz wiele wtyczek CMS wstrzykuje kod pod koniec <body> i jest to poprawne. Bing dodaje, że kod może znaleźć się “in the header, body or foot of the page.” (tłumaczenie) „w nagłówku, treści lub stopce strony”. Przenoszenie poprawnego bloku z body do head niczego nie zmienia. Evidence for this claim Google permits JSON-LD in either the head or body of an HTML document for supported structured-data features. Scope: Google Search JSON-LD guidance; markup must still match visible page content. Confidence: high · Verified: Google: Structured data introduction

Dynamiczne generowanie JSON-LD i pułapka dotycząca robotów AI

JSON-LD można tworzyć dynamicznie za pomocą JavaScript. Google dokumentuje dwa sposoby:

Evidence for this claim Dynamically generated structured data is acceptable to Google when it is rendered and complies with content and quality guidelines. Scope: Google Search JavaScript and structured-data guidance; crawlability and rendering remain prerequisites. Confidence: high · Verified: Google: Generate structured data with JavaScript
  1. Google Tag Manager — tag Custom HTML zawierający JSON-LD i pobierający wartości ze zmiennych GTM. Unikaj dublowania danych strony i tagu.
  2. Własny JavaScript — programowe utworzenie elementu skryptu: 
    const script = document.createElement('script');
script.setAttribute('type', 'application/ld+json');
script.textContent = structuredDataText;
document.head.appendChild(script);

To działa w przypadku Googlebota, ponieważ Google renderuje stronę: “Google Search can understand and process structured data that’s available in the DOM when it renders the page.” (tłumaczenie) „Wyszukiwarka Google potrafi zrozumieć i przetworzyć dane strukturalne dostępne w DOM podczas renderowania strony”.

Istnieje jednak ważne zastrzeżenie. W testach kilka robotów AI, w tym GPTBot i ClaudeBot, nie wykonywało JavaScriptu. Jeśli JSON-LD powstaje dopiero po uruchomieniu skryptu po stronie klienta, taki robot go nie zobaczy, mimo że Googlebot odczyta kod po renderowaniu DOM.

Trzeba zachować precyzję: zachowanie Googlebota wynika z dokumentacji Google, natomiast informacje o robotach AI pochodzą z testów poszczególnych dostawców, nie z ich specyfikacji. Obsługa JavaScript może się zmienić i nie została tu sprawdzona dla każdego robota. Nie traktuj zdania „roboty AI pomijają JS” jako uniwersalnej reguły. Sprawdź robota, na którym Ci zależy, albo domyślnie renderuj kod po stronie serwera. Jeśli JSON-LD nie ma w HTML serwera i nie potwierdzono wykonywania JS przez robota, przyjmij, że kod jest niewidoczny. Dla widoczności w wyszukiwaniu AI umieszczaj JSON-LD w statycznym HTML po stronie serwera, chyba że zweryfikujesz inne zachowanie. Mechanikę renderowania omawia SEO JavaScript.

Jest też drugie zastrzeżenie dotyczące e-commerce. Google ostrzega, że dynamicznie generowane znaczniki Product “can make Shopping crawls less frequent and less reliable,” (tłumaczenie) „mogą sprawić, że indeksowanie na potrzeby Zakupów będzie rzadsze i mniej niezawodne”. To problem przy szybko zmieniających się cenach i dostępności, dlatego dane produktów warto renderować po stronie serwera.

Zasady, które mają realne konsekwencje

Najważniejsze wytyczne Google dotyczące danych strukturalnych są krótkie:

  • “Don’t mark up content that is not visible to readers of the page.” (tłumaczenie) „Nie oznaczaj treści, której czytelnicy nie widzą na stronie”.
  • “Don’t mark up irrelevant or misleading content, such as fake reviews.” (tłumaczenie) „Nie oznaczaj treści nieistotnych ani wprowadzających w błąd, takich jak fałszywe recenzje”.
  • “Put the structured data on the page that it describes.” (tłumaczenie) „Umieść dane strukturalne na stronie, którą opisują”.
  • “Use the most specific applicable type and property names defined by schema.org.” (tłumaczenie) „Używaj najbardziej szczegółowych właściwych typów i nazw właściwości zdefiniowanych w schema.org”.
  • Nie blokuj stron z danymi strukturalnymi przed Googlebotem przez robots.txt ani noindex.

Najważniejsza jest zasada widocznej treści. Opisywanie informacji, których nie ma na stronie, zawsze naruszało wytyczne, a egzekwowanie tej zasady zostało zaostrzone. Bing ostrzega: “even though the markup is not visible on your page, it is still read by the search engines, and putting spam data in the markup can hamper your presence.” (tłumaczenie) „choć znaczniki nie są widoczne na stronie, wyszukiwarki nadal je odczytują, a umieszczanie w nich spamu może zaszkodzić widoczności”.

Częste błędy w JSON-LD

  • Znaczniki nie odpowiadają widocznej stronie — najpoważniejszy problem z zasadami, np. ocena w JSON-LD, której nie widzi użytkownik.
  • Niepoprawny JSON — końcowy przecinek, nieucieczony cudzysłów lub typograficzne cudzysłowy z edytora tekstu (" zamiast prostego cudzysłowu) mogą unieważnić cały blok.
  • Błędne nazwy właściwości — wymyślone lub literówkowe właściwości nieistniejące w schema.org są ignorowane przez parser.
  • Zbyt ogólny typ — Thing lub Article zamiast właściwego Recipe albo NewsArticle ogranicza znaczenie danych.
  • Powielone, niespójne bloki Organization — różne nazwy, logo lub adresy URL powodują niejednoznaczność grafu.
  • Brak wymaganych właściwości dla docelowego wyniku rozszerzonego — każda funkcja ma własną listę pól.
  • Założenie, że każdy robot widzi kod wstrzyknięty przez JS — Google renderuje taki kod, ale niektóre roboty AI mogą go nie odbierać; sprawdzaj je osobno.

Walidacja JSON-LD

Pytanie „czy mój JSON-LD jest poprawny?” obejmuje cztery różne kwestie. Zaliczenie jednego testu nie oznacza zaliczenia pozostałych:

TestCo potwierdzaCzego nie potwierdza
Parsowanie JSON (dowolny linter lub etap parsowania w Rich Results Test)Składnia jest legalnym JSON-em: bez końcowych przecinków, nieucieczonych lub typograficznych cudzysłowówCzy właściwości należą do schema.org i czy Google coś wyświetli
Schema.org ValidatorWłaściwości i typy istnieją w słowniku schema.orgCzy Google obsługuje typ jako wynik rozszerzony i czy ma on wymagane pola
Rich Results TestZnaczniki na wyrenderowanej stronie spełniają wymagania konkretnego obsługiwanego typu GoogleCzy Google faktycznie wyświetli wynik oraz czy inne systemy wyszukiwania lub AI zinterpretują dane tak samo
Google Search Console — raporty rozszerzeń i wyników rozszerzonychCo Google rzeczywiście odczytało na aktywnych, zindeksowanych stronach w większej skaliStanu w czasie rzeczywistym, ponieważ raporty czekają na ponowne indeksowanie
  • Testuj adres URL, a nie tylko wklejony kod, jeśli strona korzysta z JS. Tryb kodu nie uruchamia skryptów ani nie rozwiązuje odwołań względnych jak test aktywnego URL-a, więc nie pokazuje końcowego bloku po renderowaniu.
  • Bing Webmaster Tools — Markup Validator — Bing waliduje JSON-LD od sierpnia 2018 roku.
  • Testy te nie mówią nic o robotach, które nie renderują JavaScript. Test URL-a potwierdza to, co widzi Google, a nie to, co otrzymuje robot pomijający JS.

Czy JSON-LD pomaga w SEO?

Realistyczne oczekiwania są następujące:

  • To nie jest sygnał rankingowy. John Mueller powiedział wprost, że dane strukturalne nie poprawiają pozycji witryny.
  • Kwalifikacja do wyników rozszerzonych. JSON-LD umożliwia gwiazdki, ceny, FAQ i breadcrumbs, ale nie gwarantuje ich wyświetlenia.
  • Pośredni wpływ na CTR. Bardziej atrakcyjny wynik może zdobyć więcej kliknięć.
  • Rozumienie encji. Dane pomagają systemom połączyć stronę ze znanymi encjami i Grafem wiedzy.
  • Wyszukiwanie AI. Fabrice Canel z Bing potwierdził w 2025 roku, że znaczniki schema pomagają modelom Microsoftu rozumieć treść. Zastrzeżenie opisane w Schema Markup for AI pozostaje ważne: to infrastruktura ujednoznaczniania, a nie bezpośrednia dźwignia cytowań.

Wdrażaj więc JSON-LD dla kwalifikacji do wyników rozszerzonych, jasności encji i rozumienia przez systemy AI — nie jako sztuczkę rankingową.

Ten artykuł należy do centrum danych strukturalnych. Zastosowanie słownika schema.org w AI omawia Schema Markup for AI, a mechanikę dynamicznego wstrzykiwania — SEO JavaScript.

Add an expert note

Pin an expert quote

New person? Create their unclaimed profile at /admin/experts/ → Pin a quote first.