JSON-LD: Kompletny przewodnik po implementacji

Q: Jaka jest różnica między JSON-LD a Microdata?

JSON-LD to oddzielny blok skryptu w sekcji head. Microdata dodaje atrybuty itemscope, itemtype i itemprop bezpośrednio do elementów HTML. Google zaleca JSON-LD, bo łatwiej go utrzymać — zmiany w HTML nie wpływają na dane.

Q: Czy JSON-LD gwarantuje rozszerzone wyniki w Google?

Nie. Poprawny JSON-LD uprawnia do wyników rozszerzonych, ale ich nie gwarantuje. Google stosuje dodatkowe sygnały jakości i polityki. Użyj testu wyników rozszerzonych, by potwierdzić uprawnienia i brak brakujących właściwości.

Q: Ile bloków schematu mogę mieć na jednej stronie?

Nie ma sztywnego limitu. Typowa strona artykułu może mieć blok Article, FAQPage i BreadcrumbList — wszystkie są przetwarzane niezależnie przez Google. Unikaj duplikowania tego samego typu na stronie, by nie mylić parserów.

Q: Gdzie umieścić tag skryptu JSON-LD?

W sekcji dokumentu. To zalecane miejsce, bo schemat jest dostępny przed analizą treści. Niektóre implementacje umieszczają go na końcu body — Google obsługuje oba, ale head to najlepsza praktyka.

Q: Czy mogę dynamicznie generować JSON-LD w aplikacji Blazor?

Tak. W Blazor Server lub WASM JSON-LD tworzysz w OnInitialized lub OnInitializedAsync i renderujesz jako MarkupString w sekcji head przez MetadataComponent. Kluczowe jest, by schemat był renderowany po stronie serwera lub podczas prerenderingu, aby roboty widziały go w pierwszej odpowiedzi HTTP.

Q: Co się stanie, jeśli JSON-LD ma błąd składni?

Google zignoruje błędny blok bez komunikatu. Strona pozostanie zaindeksowana, ale straci uprawnienia do wyników rozszerzonych dla tego schematu. Zawsze waliduj za pomocą testu wyników rozszerzonych po wdrożeniu, zwłaszcza po zmianach modelu serializacji.

Q: Czy powinienem uwzględnić dateModified, nawet jeśli nic się nie zmieniło?

Tak. Ustaw dateModified na tę samą wartość co datePublished, jeśli artykuł nigdy nie był aktualizowany. Brak dateModified może obniżyć zaufanie Google do świeżości treści. Niektóre walidatory wyników rozszerzonych zgłaszają to jako ostrzeżenie.

Q: Czy schemat BreadcrumbList jest wymagany do rozszerzonych wyników okruszków?

Rozszerzone wyniki okruszków mogą pochodzić ze schematu BreadcrumbList lub z HTML, który Google automatycznie analizuje. Jawny schemat BreadcrumbList daje pełną kontrolę nad etykietami i URL na każdym poziomie, co jest bardziej niezawodne niż automatyczne wyciąganie.

Czym jest JSON-LD i dlaczego jest ważny dla SEO

JSON-LD (JavaScript Object Notation for Linked Data) to sposób kodowania danych strukturalnych w formacie JSON. Wyszukiwarki, jak Google, odczytują je, by zrozumieć znaczenie treści, nie tylko słowa kluczowe.

Gdy Google odczyta dane strukturalne, strona może wyświetlać rozszerzone wyniki — wzbogacone wizualnie, z ocenami, FAQ, obrazami artykułów, okruszkami i innymi funkcjami. Takie wyniki mają wyższy współczynnik klikalności niż zwykłe linki.

Google oficjalnie zaleca JSON-LD zamiast Microdata i RDFa, ponieważ można go umieścić w dowolnym miejscu strony — także w sekcji head — bez konieczności zmiany istniejącego HTML. Dane są całkowicie oddzielone od kodu.

Uprawnienia do wyników rozszerzonych

Poprawne oznaczenia schematu umożliwiają wyświetlanie FAQ, karuzel artykułów, okruszków i innych rozszerzonych funkcji w Google.

Więcej kliknięć przy tym samym rankingu

Jasność semantyczna

Dane strukturalne eliminują niejasności. Strona z pytaniami i odpowiedziami jest oznaczona jako FAQPage, dzięki czemu Google wyświetla ją jako rozszerzony wynik FAQ.

Poinformuj wyszukiwarki, co oferujesz

Brak zmian w HTML

JSON-LD umieszczany jest w tagu skryptu w sekcji head. Nie ingeruje w widoczny HTML, więc dodawanie lub aktualizacja schematu nie zagraża układowi ani dostępności.

Czysty podział odpowiedzialności

JSON-LD kontra Microdata i RDFa

Istnieją trzy formaty osadzania danych schema.org na stronach. Google rozumie wszystkie, ale różnią się sposobem stosowania i utrzymania.

Format	Miejsce składni	Utrzymanie	Wpływ na SEO	Rekomendacja Google
JSON-LD	Oddzielny tag skryptu	Łatwe — bez zmian w HTML	Pełne wsparcie wyników rozszerzonych	Zalecane
Microdata	Atrybuty w HTML	Wysokie — ściśle powiązane z kodem	Pełne wsparcie wyników rozszerzonych	Obsługiwane
RDFa	Atrybuty w HTML	Wysokie — ściśle powiązane z kodem	Pełne wsparcie wyników rozszerzonych	Obsługiwane

Dlaczego JSON-LD jest łatwiejszy w utrzymaniu

W Microdata i RDFa atrybuty schematu są rozproszone w HTML. Zmiana szablonu może nieoczekiwanie uszkodzić dane. JSON-LD to samodzielny blok — aktualizujesz skrypt, bez wpływu na HTML.

Naucz się stosować meta tagi HTML, Open Graph i dane strukturalne JSON-LD.
Praktyczne strategie SEO dla lepszej widoczności i pozycji w wyszukiwarkach.
Projekty praktyczne obejmujące responsywny design i optymalizację wydajności.

Poznaj kurs tworzenia stron

Podstawowe typy schematów i ich zastosowanie

Schema.org definiuje setki typów, ale kilka obejmuje większość treści. To one odblokowują rozszerzone wyniki w Google.

Typ schematu	Zastosowanie	Typ wyniku rozszerzonego
Article	Posty na blogu, poradniki, artykuły	Karuzela artykułów, Najważniejsze wiadomości
FAQPage	Strony z pytaniami i odpowiedziami	FAQ w wynikach wyszukiwania
BreadcrumbList	Strony z hierarchią nawigacji	Ścieżka okruszków pod adresem URL
WebSite / WebPage	Strona główna, strony centralne, landing pages	Pole wyszukiwania i rozpoznawanie encji
SoftwareApplication	Aplikacje, narzędzia, oprogramowanie	Rozszerzony wynik aplikacji z oceną i ceną

Słownik Schema.org

Wszystkie typy schematów są zdefiniowane na schema.org. Właściwość @context w JSON-LD wskazuje parserom słownik schema.org. Można łączyć wiele typów na jednej stronie — Google przetwarza każdy blok osobno.

Implementacja schematu artykułu

Schemat artykułu to najważniejszy typ dla stron z treściami. Informuje Google o tytule, opisie, dacie publikacji, autorze i wydawcy — minimalny zestaw do wyników rozszerzonych.

Poniższa klasa C# to model serializacji. Każde pole odpowiada właściwości JSON-LD przez atrybut JsonPropertyName.

C#Klasa ArticleSchema w C# (JsonLdService.cs)

private class ArticleSchema
{
    [JsonPropertyName("@context")]
    public string Context { get; } = "https://schema.org";

    [JsonPropertyName("@type")]
    public string Type { get; } = "Article";

    [JsonPropertyName("headline")]
    public string? Headline { get; set; }

    [JsonPropertyName("description")]
    public string? Description { get; set; }

    [JsonPropertyName("image")]
    public string? Image { get; set; }

    [JsonPropertyName("url")]
    public string? Url { get; set; }

    [JsonPropertyName("author")]
    public Organization? Author { get; set; }

    [JsonPropertyName("publisher")]
    public ArticlePublisher? Publisher { get; set; }

    [JsonPropertyName("datePublished")]
    public string? DatePublished { get; set; }

    [JsonPropertyName("dateModified")]
    public string? DateModified { get; set; }

    [JsonPropertyName("articleSection")]
    public List<string>? ArticleSection { get; set; }
}

Wymagane właściwości to: headline, image, datePublished, dateModified, author i publisher. Tablica articleSection jest opcjonalna, ale zalecana — wskazuje zakres tematyczny artykułu.

HTMLWynik JSON-LD schematu artykułu

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "JSON-LD Schema Markup: Complete SEO Implementation Guide",
  "description": "Learn how to implement JSON-LD structured data for Article, FAQPage, BreadcrumbList, WebSite, and WebPage schema types.",
  "image": "https://ghostlyinc.com/images/web/jsonldguide/opengraph/hero-1200.png",
  "url": "https://ghostlyinc.com/en/json-ld-schema-markup-seo-guide/",
  "author": {
    "@type": "Organization",
    "name": "GhostlyInc",
    "url": "https://ghostlyinc.com"
  },
  "publisher": {
    "@type": "Organization",
    "name": "GhostlyInc",
    "logo": {
      "@type": "ImageObject",
      "url": "https://ghostlyinc.com/images/logo.png"
    }
  },
  "datePublished": "2026-03-28T10:00:00Z",
  "dateModified": "2026-03-28T10:00:00Z",
  "articleSection": [
    "What is JSON-LD and why it matters for SEO",
    "JSON-LD vs. Microdata vs. RDFa",
    "Core schema types and when to use them",
    "Article schema implementation"
  ]
}
</script>

Autor i wydawca są typu Organization. W blogach osobistych autor może być Person z nazwą i URL.

Schemat FAQ dla rozszerzonych fragmentów

Schemat FAQPage tworzy rozszerzone wyniki FAQ — rozwijane pytania i odpowiedzi wyświetlane bezpośrednio w wynikach Google pod listingiem strony. Zwiększa to widoczność i CTR.

Klasa FaqPage zawiera listę pytań. Każde musi mieć nazwę (pytanie) i acceptedAnswer z tekstem (odpowiedź).

C#Klasa FaqPage w C# (JsonLdService.cs)

private class FaqPage
{
    [JsonPropertyName("@context")]
    public string Context { get; } = "https://schema.org";

    [JsonPropertyName("@type")]
    public string Type { get; } = "FAQPage";

    [JsonPropertyName("@id")]
    public string? Id { get; set; }

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("mainEntity")]
    public List<FaqEntity>? MainEntity { get; set; }
}

private class FaqEntity
{
    [JsonPropertyName("@type")]
    public string Type { get; } = "Question";

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("acceptedAnswer")]
    public FaqAnswer? AcceptedAnswer { get; set; }
}

private class FaqAnswer
{
    [JsonPropertyName("@type")]
    public string Type { get; } = "Answer";

    [JsonPropertyName("text")]
    public string? Text { get; set; }
}

Wynik to pojedynczy blok FAQPage z tablicą mainEntity. Każdy element to Question z acceptedAnswer. Google obsługuje do 10 pytań na stronę.

HTMLWynik JSON-LD schematu FAQ

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "@id": "https://ghostlyinc.com/en/json-ld-schema-markup-seo-guide/#faq",
  "name": "Frequently asked questions",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is the difference between JSON-LD and Microdata?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "JSON-LD is a separate script block that lives in the head and does not touch HTML. Microdata adds attributes directly to HTML elements. Google recommends JSON-LD for its maintainability."
      }
    },
    {
      "@type": "Question",
      "name": "How many FAQ questions can I mark up?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Google supports up to ten questions per page for the FAQ rich result. Additional questions are still valid schema but will not appear in the search result enhancement."
      }
    }
  ]
}
</script>

Właściwość @id w bloku FAQPage wiąże schemat z konkretnym fragmentem URL. To najlepsza praktyka przy wielu blokach schematu na stronie, ułatwiająca identyfikację.

BreadcrumbList do nawigacji

Schemat BreadcrumbList informuje Google o hierarchicznej ścieżce od strony głównej do bieżącej. Google wyświetla wtedy okruszki zamiast surowego URL.

Klasa C# tworzy listę elementów ListItem z pozycją, nazwą i adresem URL. Pozycja jest numerowana od 1 — strona główna to 1.

C#Klasa BreadcrumbListSchema w C# (JsonLdService.cs)

private class BreadcrumbListSchema
{
    [JsonPropertyName("@context")]
    public string Context { get; } = "https://schema.org";

    [JsonPropertyName("@type")]
    public string Type { get; } = "BreadcrumbList";

    [JsonPropertyName("itemListElement")]
    public List<BreadcrumbListElement>? ItemListElement { get; set; }
}

private class BreadcrumbListElement
{
    [JsonPropertyName("@type")]
    public string Type { get; } = "ListItem";

    [JsonPropertyName("position")]
    public int Position { get; set; }

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("item")]
    public string? Item { get; set; }
}

Wynik JSON umieszcza każdy okruszek jako itemListElement. Google wymaga co najmniej dwóch elementów, ostatni to URL bieżącej strony.

HTMLWynik JSON-LD schematu BreadcrumbList

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://ghostlyinc.com/en/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Web SEO Hub",
      "item": "https://ghostlyinc.com/en/web-seo/"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "JSON-LD Schema Markup: Complete SEO Implementation Guide",
      "item": "https://ghostlyinc.com/en/json-ld-schema-markup-seo-guide/"
    }
  ]
}
</script>

Rozszerzone wyniki okruszków pojawiają się pod tytułem strony w wynikach. Poprawiają UX i dają pewność co do struktury witryny.

Schemat WebSite i WebPage

Schemat WebSite i WebPage tworzy podstawowy graf encji witryny. WebSite określa witrynę — nazwę, URL, język i wydawcę. WebPage opisuje stronę i łączy ją z WebSite przez isPartOf.

Obie klasy stosują ten sam wzorzec JSON-LD. @id WebSite to domena główna, @id WebPage to pełny URL strony.

C#Klasy WebSiteSchema i WebPageSchema w C# (JsonLdService.cs)

private class WebSiteSchema
{
    [JsonPropertyName("@context")]
    public string Context { get; } = "https://schema.org";

    [JsonPropertyName("@type")]
    public string Type { get; } = "WebSite";

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("url")]
    public string? Url { get; set; }

    [JsonPropertyName("inLanguage")]
    public string? InLanguage { get; set; }

    [JsonPropertyName("publisher")]
    public Organization? Publisher { get; set; }
}

private class WebPageSchema
{
    [JsonPropertyName("@context")]
    public string Context { get; } = "https://schema.org";

    [JsonPropertyName("@type")]
    public string Type { get; } = "WebPage";

    [JsonPropertyName("@id")]
    public string? Id { get; set; }

    [JsonPropertyName("name")]
    public string? Name { get; set; }

    [JsonPropertyName("description")]
    public string? Description { get; set; }

    [JsonPropertyName("url")]
    public string? Url { get; set; }

    [JsonPropertyName("inLanguage")]
    public string? InLanguage { get; set; }

    [JsonPropertyName("isPartOf")]
    public WebSiteReference? IsPartOf { get; set; }
}

Właściwość inLanguage używa kodów językowych BCP 47 (np. en, de, fr). Link isPartOf łączy WebPage z WebSite przez @id domeny, co pomaga Google zbudować model encji witryny.

HTMLWynik JSON-LD schematu WebSite i WebPage

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "GhostlyInc",
  "url": "https://ghostlyinc.com",
  "inLanguage": "en",
  "publisher": {
    "@type": "Organization",
    "name": "GhostlyInc",
    "url": "https://ghostlyinc.com"
  }
}
</script>

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "@id": "https://ghostlyinc.com/en/json-ld-schema-markup-seo-guide/",
  "name": "JSON-LD Schema Markup: Complete SEO Implementation Guide",
  "description": "Learn how to implement JSON-LD structured data for Article, FAQPage, BreadcrumbList, WebSite, and WebPage schema types.",
  "url": "https://ghostlyinc.com/en/json-ld-schema-markup-seo-guide/",
  "inLanguage": "en",
  "isPartOf": {
    "@type": "WebSite",
    "@id": "https://ghostlyinc.com"
  }
}
</script>

Najlepsze praktyki implementacji

Metoda WrapInScriptTag to jedyne miejsce, gdzie ciągi JSON stają się poprawnymi blokami JSON-LD. Opakowuje schemat w tag script z typem MIME application/ld+json.

To metoda wywoływana przez wszystkie budownicze schematów — Article, FAQPage, BreadcrumbList, WebSite i WebPage przekazują do niej swój JSON.

C#Metoda WrapInScriptTag (JsonLdService.cs)

private static MarkupString WrapInScriptTag(string json)
{
    var builder = new StringBuilder();
    builder.AppendLine("<script type=\"application/ld+json\">");
    builder.AppendLine(json);
    builder.AppendLine("</script>");

    return new MarkupString(builder.ToString());
}

Obiekt SchemaContext to punkt startowy metody BuildSchema. Zawiera wszystkie dane potrzebne do budowy pełnego zestawu bloków schematu — typ, metadane, FAQ, okruszki i dane artykułu.

C#Logika dystrybucji BuildSchema (JsonLdService.cs)

public SchemaBuildResult BuildSchema(SchemaContext context)
{
    if (context == null) throw new ArgumentNullException(nameof(context));

    var jsonLd = new List<MarkupString>();

    switch (context.PageType)
    {
        case PageSchemaType.Home:
            jsonLd.Add(WebSite(context));
            jsonLd.Add(WebPage(context));
            break;
        case PageSchemaType.Article:
            jsonLd.Add(Article(context.Article!));
            break;
        case PageSchemaType.Tool:
            jsonLd.Add(WebPage(context));
            jsonLd.Add(SoftwareApplication(context.SoftwareApplication!));
            break;
        case PageSchemaType.Hub:
            jsonLd.Add(WebPage(context));
            break;
    }

    if (context.Faqs != null && context.Faqs.Count > 0)
    {
        jsonLd.Add(FAQ(context.Faqs.ToList(), context.FaqTitle, context.Url));
    }

    if (context.ParentHierarchy.Count > 0)
    {
        jsonLd.Add(BreadcrumbList(BuildBreadcrumbItems(context)));
    }

    return new SchemaBuildResult(jsonLd, context.PageType == PageSchemaType.Article);
}

Przełącznik dystrybucji umożliwia komponowanie budowniczego schematu. FAQ i okruszki są zawsze dodawane, niezależnie od typu strony. Każdy typ strony może mieć FAQ lub okruszki bez zmiany logiki.

Testowanie i walidacja schematu

Poprawna składnia JSON-LD nie gwarantuje wyników rozszerzonych. Narzędzia Google sprawdzają składnię i zgodność z polityką dla każdego typu wyniku.

Test wyników rozszerzonych

Użyj search.google.com/test/rich-results, by przetestować URL lub wkleić HTML. Google potwierdza wykryte typy wyników i wskazuje brakujące właściwości.

Oficjalne narzędzie Google do sprawdzania uprawnień

Walidator oznaczeń schematu

validator.schema.org sprawdza oznaczenia względem specyfikacji schema.org niezależnie od polityk Google. Pomocny przy literówkach i niezgodnościach typów.

Walidacja składni Schema.org

Google Search Console

Sekcja Ulepszenia w Search Console raportuje błędy i ostrzeżenia schematu na wielu stronach. Używaj do monitoringu po wdrożeniu.

Monitoruj na dużą skalę po wdrożeniu

Najczęściej zadawane pytania

01 Jaka jest różnica między JSON-LD a Microdata?

02 Czy JSON-LD gwarantuje rozszerzone wyniki w Google?

03 Ile bloków schematu mogę mieć na jednej stronie?

04 Gdzie umieścić tag skryptu JSON-LD?

05 Czy mogę dynamicznie generować JSON-LD w aplikacji Blazor?

06 Co się stanie, jeśli JSON-LD ma błąd składni?

07 Czy powinienem uwzględnić dateModified, nawet jeśli nic się nie zmieniło?

08 Czy schemat BreadcrumbList jest wymagany do rozszerzonych wyników okruszków?

JSON-LD: Kompletny przewodnik po implementacji SEO

Czym jest JSON-LD i dlaczego jest ważny dla SEO

Uprawnienia do wyników rozszerzonych

Jasność semantyczna

Brak zmian w HTML

JSON-LD kontra Microdata i RDFa

Opanuj nowoczesne tworzenie stron z SEO

Podstawowe typy schematów i ich zastosowanie

Implementacja schematu artykułu

Schemat FAQ dla rozszerzonych fragmentów

Schemat WebSite i WebPage

Najlepsze praktyki implementacji

Testowanie i walidacja schematu

Test wyników rozszerzonych

Walidator oznaczeń schematu

Google Search Console

Najczęściej zadawane pytania

Odpowiedzi na najczęstsze pytania o oznaczenia JSON-LD

Czym jest JSON-LD i dlaczego jest ważny dla SEO

Uprawnienia do wyników rozszerzonych

Jasność semantyczna

Brak zmian w HTML

JSON-LD kontra Microdata i RDFa

Opanuj nowoczesne tworzenie stron z SEO

Podstawowe typy schematów i ich zastosowanie

Implementacja schematu artykułu

Schemat FAQ dla rozszerzonych fragmentów

BreadcrumbList do nawigacji

Schemat WebSite i WebPage

Najlepsze praktyki implementacji

Testowanie i walidacja schematu

Test wyników rozszerzonych

Walidator oznaczeń schematu

Google Search Console

Najczęściej zadawane pytania

Odpowiedzi na najczęstsze pytania o oznaczenia JSON-LD

Powiązane materiały