JSON-LD разметка: гатовыя прыклады і генератар на PHP

JSON-LD разметка паведамляе пошукавым сістэмам у машыначытальным выглядзе, чым з'яўляецца старонка: артыкулам, таварам з коштам, кампаніяй з кантактамі, спісам пытанняў і адказаў. Наведвальнікі яе не бачаць, яна не замяняе добры кантэнт і сама па сабе не паднімае пазіцыі. Затое яна робіць старонку прыдатнай для пашыраных вынікаў, дапамагае пошукавікам звязаць вашыя старонкі з патрэбнай сутнасцю і дае ІІ-пошуку чысцейшая крыніца. Мы генеруем яе на кожнай старонцы integrono.com і іншых сваіх сайтаў, а гэты гайд - практычная версія гэтай працы.

JSON-LD, Microdata і RDFa

Слоўнік schema.org можна ўбудаваць трыма сінтаксісамі. Microdata і RDFa дадаюць атрыбуты ў HTML-тэгі, з-за чаго разметка пераплятаецца з шаблонамі. JSON-LD жыве ў адным блоку script асобна ад вёрсткі, яго прасцей генераваць, тэставаць і мяняць. Google рэкамендуе JSON-LD, і мы выкарыстоўваем менавіта яго ўсюды.

Прынцыпы да прыкладаў

• Апісвайце бачны кантэнт. Калі кошты, рэйтынгу ці FAQ няма на старонцы, іх не павінна быць і ў разметцы.
• Выкарыстоўвайце абсалютныя URL і кананічны адрас старонкі.
• Запаўняйце абавязковыя ўласцівасці цалкам і дадавайце рэкамендуемыя, калі ў вас ёсць рэальныя дадзеныя.
• Звязвайце сутнасці праз @id. Аўтар артыкула - арганізацыя, апісаная адзін раз з @id, а не новая копія кожны раз.
• Выкарыстоўвайце даты ў фармаце ISO 8601 (2026-10-28 або з часам і часавым поясам).
• Не выдумляйце водгукі і рэйтынгі. Фальшывы AggregateRating - частая прычына ручных санкцый.

Прыклад 1. Organization (і WebSite)

Размясціце на галоўнай старонцы або ўвогуле для сайта графе. Ён апісвае сутнасць, на якую спасылаецца астатняя разметка.

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "Example Studio",
  "url": "https://example.com/",
  "logo": "https://example.com/images/logo.png",
  "email": "[email protected]",
  "sameAs": [
    "https://github.com/example",
    "https://www.linkedin.com/company/example"
  ]
}

Прыклад 2. BreadcrumbList

Разметка хлебных крошак дазваляе Google паказваць шлях да старонкі замест волкага URL у выдачы. Яна павінна супадаць з бачнымі крошкамі.

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {"@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/"},
    {"@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog"},
    {"@type": "ListItem", "position": 3, "name": "JSON-LD guide", "item": "https://example.com/blog/json-ld-guide"}
  ]
}

Прыклад 3. Article

Для артыкулаў блога і гайдаў. Важныя ўласцівасці: загаловак, даты, аўтар, выдавец, выява і адрас старонкі.

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "JSON-LD structured data: examples",
  "description": "Short summary of the article.",
  "url": "https://example.com/blog/json-ld-guide",
  "mainEntityOfPage": "https://example.com/blog/json-ld-guide",
  "inLanguage": "en",
  "datePublished": "2026-08-23",
  "dateModified": "2026-10-28",
  "author": {"@id": "https://example.com/#organization"},
  "publisher": {"@id": "https://example.com/#organization"},
  "image": {"@type": "ImageObject", "url": "https://example.com/images/blog/json-ld.webp", "width": 1200, "height": 630}
}

Змяняйце dateModified толькі калі кантэнт сапраўды змяніўся. Абнаўленне даты пры кожным дэплоі - ціхі спосаб страціць давер.

Прыклад 4. Product з Offer

Для старонак тавараў з бачным коштам. Укажыце наяўнасць і валюту, а aggregateRating або review дадавайце, толькі калі рэальныя водгукі паказаны на старонцы.

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Example product",
  "description": "What it is and who it is for.",
  "image": ["https://example.com/images/product.webp"],
  "sku": "EX-001",
  "brand": {"@type": "Brand", "name": "Example"},
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/product/ex-001",
    "priceCurrency": "EUR",
    "price": "49.00",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition"
  }
}

Прыклад 5. Service з Offer

Для платных паслуг, напрыклад аўдыту з фіксаванай цаной або пагадзіннай кансультацыі. Такі патэрн мы выкарыстоўваем на старонках уласных паслуг.

{
  "@context": "https://schema.org",
  "@type": "Service",
  "name": "Architecture review",
  "serviceType": "Software architecture analysis",
  "provider": {"@id": "https://example.com/#organization"},
  "areaServed": "Worldwide",
  "offers": {
    "@type": "Offer",
    "price": "200",
    "priceCurrency": "EUR",
    "url": "https://example.com/services/architecture-review"
  }
}

Прыклад 6. FAQPage

Разметка FAQ апісвае спіс пытанняў і адказаў, якія бачныя на старонцы. Улічыце, што з 2023 гады Google паказвае FAQ-снипеты толькі для абмежаванага круга аўтарытэтных сайтаў, таму не чакайце якія расчыняюцца адказаў у выдачы. Разметка застаецца валіднай, яе чытаюць іншыя пошукавікі і ІІ-сістэмы, і яна трымае FAQ у структуры, якую машыны могуць цытаваць.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Do I need structured data to rank?",
      "acceptedAnswer": {"@type": "Answer", "text": "No. It is not a ranking requirement, but it can make pages eligible for rich results."}
    }
  ]
}

Аб'яднайце ўсё ў адным @graph

На старонцы рэдка бывае адна сутнасць. Змесціце ўсё ў адзін script з дапамогай @graph і спасылайцеся на агульныя сутнасці па @id:

{
  "@context": "https://schema.org",
  "@graph": [
    {"@type": "Organization", "@id": "https://example.com/#organization", "name": "Example Studio"},
    {"@type": "Article", "headline": "...", "author": {"@id": "https://example.com/#organization"}},
    {"@type": "BreadcrumbList", "itemListElement": []},
    {"@type": "FAQPage", "mainEntity": []}
  ]
}

Бяспечная генерацыя JSON-LD на PHP

Не зьбірайце JSON радкамі ўручную. Звычка ў загалоўку ламае ўвесь блок, і пошукавік моўчкі яго ігнаруе. Збярыце масіў PHP і закадуйце яго. Важныя два наборы сцягоў: чытэльны Unicode і абарона HTML-кантэксту праз экранаванне слэшаў і тэгаў.

function jsonLdScript(array $graph): string
{
    $data = ['@context' => 'https://schema.org', '@graph' => $graph];
    $json = json_encode(
        $data,
        JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_HEX_TAG | JSON_HEX_AMP | JSON_THROW_ON_ERROR
    );
    return '<script type="application/ld+json">' . $json . '</script>';
}

$graph = [
    ['@type' => 'Organization', '@id' => $site . '/#organization', 'name' => 'Example Studio', 'url' => $site . '/'],
    [
        '@type'         => 'Article',
        'headline'      => $title,
        'url'           => $canonical,
        'datePublished' => $published,
        'dateModified'  => $modified,
        'author'        => ['@id' => $site . '/#organization'],
    ],
];
echo jsonLdScript($graph);

JSON_HEX_TAG ператварае < і > у escape-паслядоўнасці, таму карыстацкі кантэнт не зможа датэрмінова зачыніць тэг script. Перадавайце ў генератар тыя ж дадзеныя, з якіх будуецца старонка (загаловак, кошт, даты), каб разметка і бачны кантэнт не разыходзіліся. На шматмоўным сайце пераводзіце тэкставыя палі і задавайце inLanguage для кожнай лакалі: менавіта так зроблена разметка артыкулаў і FAQ у гэтым блогу.

Праверка і маніторынг

1. Rich Results Test – прыдатнасць для тыпаў пашыраных вынікаў Google.
2. Schema Markup Validator - агульны сінтаксіс schema.org для любога тыпу.
3. Справаздачы аб паляпшэннях у Search Console (хлебныя крошкі, тавары, FAQ і іншыя) - памылкі і папярэджанні ў маштабе сайта пасля сканавання старонак Google.
4. Юніт-тэст, які рэндэрытуе кожны шаблон і правярае, што JSON-LD парсіцца і ўтрымоўвае патрэбныя ключы, прадухіляе рэгрэсіі пасля рэфактарынгу.

Памылкі, якія каштуюць дорага

• Разметка кантэнту, якога няма на старонцы (схаваны FAQ, выдуманыя рэйтынгі, кошты, якія адрозніваюцца ад бачных).
• Некалькі канфліктуючых блокаў ад плагіна і шаблону з рознымі Organization.
• Адносныя URL, няслушныя даты або адсутнасць @id.
• Зламаны JSON з-за ручной зборкі радкоў і неэкранаваных двукоссяў.
• Разметка як трук для ранжыравання. Гэта інструмент яснасці, а старонка ўсё роўна павінна заслужыць пазіцыі.

Чым мы можам дапамагчы

Структураваныя дадзеныя - частка нашай працы па тэхнічным SEO: мы праектуючы схему для вашых шаблонаў, рэалізуемы генератар у вашым стэку і наладжваем праверкі, каб разметка заставалася карэктнай пасля рэлізаў. Калі жадаеце ўбачыць агульную карціну праблем сайта, пачніце з нашага чэк-ліста тэхнічнага SEO-аўдыту ці запішыцеся на кансультацыю.