JSON-LD - микроразметка материалов для выдачи сниппетов в поиске Google

Перевод статьи с ресурса moz.com для начинающих и знакомящихся с микроразметкой JSON-LD

Tags:

Руководство по JSON-LD для начинающих

Что такое JSON-LD?

JSON-LD расшифровывается как JavaScript Object Notation for Linked Data, что представляет собой многомерные массивы (представьте себе: список пар атрибут-значение).

Это формат реализации для структурирования данных, аналогичный Microdata и RDFa. Обычно, в контексте SEO, JSON-LD реализуется с использованием словаря Schema.org, совместной инициативы Google, Bing, Yahoo! и Yandex, созданной в 2011 году для создания единого словаря структурированных данных для веба. (Тем не менее, Bing и другие поисковые системы официально не заявили о своей поддержке реализаций JSON-LD для Schema.org.)

JSON-LD считается более простым в реализации, благодаря возможности просто вставить разметку в HTML-документ, в отличие от необходимости оборачивать разметку вокруг HTML-элементов (как это делается с Microdata).

Что делает JSON-LD?

JSON-LD аннотирует элементы на веб-странице, придавая данным структуру. Это позволяет поисковым системам лучше понимать содержимое, устранять неоднозначности и устанавливать связи между сущностями. В результате формируется более упорядоченная и понятная структура данных, что способствует созданию лучше организованного интернета в целом.

Что делает json-LD

JSON-LD преобразует неструктурированные данные в структурированные

Рисунок 1 — Концептуальная визуализация работы JSON-LD: обработка неструктурированного контента в интернете, его аннотирование и структурирование для получения организованного результата.

Таким образом, JSON-LD помогает поисковым системам, таким как Google и Яндекс, точнее интерпретировать информацию на сайте, что может улучшить отображение страницы в результатах поиска (например, с помощью расширенных сниппетов).

Где в HTML-коде страницы должен располагаться JSON-LD?

Google рекомендует размещать JSON-LD в разделе <head> HTML-документа. Однако допустимо также добавлять его и внутри <body>. Кроме того, Google способен обрабатывать динамически сгенерированные JSON-LD теги в DOM (объектной модели документа).

Коротко:

Лучше: <head>
Но можно: <body>
Динамические теги (например, загружаемые через JavaScript) тоже работают.

Это означает, что поисковые системы смогут распознать разметку независимо от её расположения в HTML, если она корректно сформирована.

Разбираем JSON-LD

Неизменяемые теги (Не нужно запоминать — просто копируйте и вставляйте)

<script type="application/ld+json">  
{  
  ...  
}  
</script>

Когда вы видите JSON-LD, первое, что должно бросаться в глаза — это тег <script>. Атрибут type="application/ld+json" сообщает браузеру: «Эй, здесь JavaScript, содержащий JSON-LD».

💡 Профессиональный совет

Всегда закрывайте теги сразу после открытия.
Как соль и перец идут вместе, так и открывающие фигурные скобки { требуют закрывающих }.
Важно: Если ваш JSON-LD не заключён в фигурные скобки {}, он не будет обработан. (Держите его «завёрнутым» в скобки!)

Таким образом, правильная структура JSON-LD гарантирует, что поисковые системы смогут корректно прочитать и использовать вашу разметку.

"@context": “http://schema.org”

Второй обязательный элемент в JSON-LD разметке — это @context со значением http://schema.org.

Этот параметр сообщает браузеру: «Эй, вот словарь, на который я ссылаюсь — ты можешь найти его по адресу http://schema.org».

Преимущество для SEO-специалиста:
Мы получаем доступ ко всем типам элементов (item types) и их свойствам (item properties), которые определены в Schema.org.

Пример разметки 📌 Пример структуры:

{
  "@context": "http://schema.org",
  "@type": "Article",
  "headline": "Пример статьи",
  "author": {
    "@type": "Person",
    "name": "Иван Петров"
  }
}

🔍 Обратите внимание:

Видите эту запятую после "http://schema.org"? Она говорит парсеру: «Данные продолжаются, не останавливайся».

💡 Профессиональный совет

Следите за запятыми (и всегда проверяйте разметку в Google’s Structured Data Testing Tool).
Пропущенная запятая = невалидная разметка. Даже опытные разработчики часто ошибаются в этом месте.

JSON-LD строго требует правильного синтаксиса, поэтому всегда проверяйте свою разметку перед публикацией!

"@type": “…”

Третий ключевой элемент JSON-LD разметки — это указание @type. После двоеточия здесь начинается аннотация данных. Параметр @type определяет тип размеченной сущности. Полный список всех доступных типов можно найти в официальной документации: https://schema.org/docs/full.html.

Схема разметки type

Как это работает?

В примере ниже:

{
  "@context": "http://schema.org",
  "@type": "Person",
  "name": "Иван Иванов"
}

@type сообщает: «Эй, здесь используется тип Person (его описание можно найти по адресу http://schema.org/Person)».

Если ввести эту ссылку в браузер, откроется документация Schema.org с:

Техническими спецификациями этого типа
Списком допустимых свойств (item properties)
Часто — примерами использования

Вложенные @type

При использовании вложенных структур потребуется указывать @type для каждого уровня. Это особенно важно в разметке:

Товаров (Product)
Хлебных крошек (BreadcrumbList)
Организаций с сотрудниками (Organization → Employee)

Пример вложенности:

{
  "@context": "http://schema.org",
  "@type": "Product",
  "brand": {
    "@type": "Brand",
    "name": "Nike"
  }
}

💡 Профессиональный совет:

Всегда проверяйте допустимые свойства для вашего @type на Schema.org. Например, для Person обязательным может быть name, а для Product — offers.
Используйте инструмент проверки структурированных данных Google, чтобы убедиться в отсутствии ошибок.

Ошибка → Пропущенный @type или его неверное указание сделает разметку бесполезной для поисковых систем!

Пары “атрибут-значение”

Следующий шаг — аннотирование информации о выбранном типе сущности (@type). Допустимые свойства для каждого типа можно найти на соответствующей странице Schema.org.

Синтаксис JSON-LD для свойств

Каждое свойство в разметке состоит из двух элементов:

Свойство (Item Property)
- Должно быть взято из словаря Schema.org.
- Обязательно заключайте в двойные прямые кавычки (" ").
  🔹 Важно: Использование фигурных (“ ”) или одинарных (' ') кавычек приведёт к ошибке валидации!
- Должно принадлежать к разрешённым свойствам для выбранного @type (указаны в документации Schema.org).
Значение (Value)
- Сюда вписывается конкретное значение свойства.
- Правила форматирования:
  - Текстовые строки и URL: всегда в двойных кавычках ("пример").
  - Числа (целые, дробные): можно без кавычек (42), но допустимо и с ними ("42" — тогда тип данных будет строковым).
  - Несколько значений: используйте квадратные скобки (["значение1", "значение2"]).

Примеры

✅ Корректно:

{
  "@type": "Book",
  "name": "Война и мир",
  "isbn": "978-5-699-12014-7",  // Строка в кавычках
  "price": 599.99,               // Число без кавычек
  "author": ["Лев Толстой", "Иван Тургенев"]  // Массив значений
}

❌ Ошибки:

Фигурные кавычки: “Война и мир” → невалидно.
Пропущенные кавычки: name: Война и мир → синтаксическая ошибка.
Неразрешённое свойство: "pageCount": 1225 (если @type не поддерживает это свойство).

💡 Профессиональный совет:

Всегда сверяйтесь со списком свойств для вашего @type.
Для сложных случаев (например, товары с вариантами) используйте вложенные структуры и массивы.
Проверяйте разметку в Google Rich Results Test — он покажет не только ошибки, но и потенциальные улучшения.

Запомните:
Правильный синтаксис — это не педантичность, а необходимость. Поисковые системы обрабатывают только безупречно оформленные данные!

Квадратные скобки [ ] в JSON-LD

Квадратные скобки используются, когда у свойства есть несколько значений.

Примеры использования:

Несколько значений одного свойства
Например, если у человека два имени:
```
"givenName": ["Джейсон", "Деруло"]
```
Здесь скобки говорят: «У этого свойства несколько значений — у Джейсона Деруло два имени».
Ссылки на соцсети (sameAs)
Часто применяется для перечисления профилей в соцсетях:
```
"sameAs": [
  "https://facebook.com/jasonderulo",
  "https://twitter.com/jasonderulo",
  "https://instagram.com/jasonderulo"
]
```

Важные правила:

Запятая после последнего элемента не ставится

"sameAs": [
   "https://facebook.com/jasonderulo",  // запятая
   "https://twitter.com/jasonderulo"     // НЕТ запятой в конце
 ]

Отсутствие запятой означает конец списка.

Не путать с фигурными скобками {}
Квадратные скобки — только для перечисления однотипных значений, а фигурные — для вложенных объектов (например, адреса или организации).

💡 Профессиональный совет:

Используйте квадратные скобки для:
- Списков (например, авторов книги).
- Альтернативных URL (например, sameAs для соцсетей).
- Любых свойств, допускающих множественные значения по Schema.org.
Всегда проверяйте, поддерживает ли выбранный @type множественные значения для конкретного свойства.

Ошибка → Лишняя запятая после последнего элемента вызовет ошибку валидации!

Пример корректной и некорректной разметки:
✅ Правильно:

"author": ["Лев Толстой", "Фёдор Достоевский"]

❌ Неправильно:

"author": ["Лев Толстой", "Фёдор Достоевский",]

→ Лишняя запятая после последнего элемента.

Для проверки используйте Google’s Structured Data Testing Tool.

Вложенность (Nesting) в JSON-LD

Вложенность означает организацию данных слоями, где одни объекты содержат другие объекты. Это можно сравнить с матрешкой, где большая кукла содержит внутри меньшую — так же и данные могут быть структурированы иерархически.

Зачем нужна вложенность?

Некоторые свойства относятся только к определенным типам сущностей. Например, в разметке события (Event):

name может означать название события,
но внутри могут быть вложены свойства performer (исполнитель) и venue (место проведения), у которых тоже есть свои name.

Без вложенности поисковые системы не поймут, к чему относится каждое свойство.

Как правильно вкладывать данные в JSON-LD

Начните с основного типа (@type)
Например, Event.
Укажите свойство, требующее вложенности
Например, performer или offers.
Откройте фигурные скобки { } для нового объекта
Внутри укажите:
- @type (тип вложенной сущности, например Person или Offer),
- его свойства и значения.
Закройте вложенный объект
- Не ставьте запятую перед закрывающей скобкой }.
- Запятая после } нужна, только если дальше идут другие свойства.

Пример вложенности

Разметка музыкального события:

{
  "@context": "http://schema.org",
  "@type": "MusicEvent",
  "name": "Концерт Jason Aldean",
  "performer": {  // ← Начало вложенного объекта
    "@type": "MusicGroup",
    "name": "Jason Aldean",
    "sameAs": "https://www.jasonaldean.com"
  },  // ← Запятая, потому что дальше есть еще свойства
  "location": {
    "@type": "Place",
    "name": "Мэдисон-Сквер-Гарден",
    "address": "Нью-Йорк, США"
  }  // ← Нет запятой, это последнее свойство
}

Чек-лист по вложенности

✅ Используйте свойства, допустимые для родительского @type (см. Schema.org).
✅ Значение вложенного объекта заключайте в { }.
✅ Указывайте @type для вложенной сущности.
✅ Добавляйте обязательные свойства для вложенного типа (например, price для Offer).
❌ Не ставьте запятую перед } (это вызовет ошибку).
✅ Запятая после }, если дальше идут другие свойства.

Где чаще всего встречается вложенность?

Товары (Product):
- Цена и условия предложения вкладываются в offers (@type: Offer).
- Отзывы — в review (@type: Review).
Организации (Organization):
- Адрес (@type: PostalAddress),
- контакты, учредители.
Рецепты (Recipe):
- Ингредиенты, инструкции, питательная ценность.

💡 Профессиональный совет:

Делайте отступы для вложенных объектов — так код легче читать.
Проверяйте обязательные свойства для вложенных типов на Schema.org.
Тестируйте разметку в Google Rich Results Test.

Ошибка → Пропущенный @type во вложенном объекте или лишние/недостающие запятые сделают разметку нерабочей!

Пример ошибки:
❌ Неправильно:

"performer": {
  "name": "Jason Aldean"  // ← Нет @type!
}

✅ Исправлено:

"performer": {
  "@type": "MusicGroup",
  "name": "Jason Aldean"
}

Распространённые ошибки в JSON-LD разметке

Если ваша разметка не проходит валидацию в Google’s Structured Data Testing Tool, проверьте этот список типичных проблем.

1. Синтаксические ошибки

Кавычки: прямые vs. фигурные

✅ Правильно: "" (прямые двойные кавычки).
❌ Ошибка: “” (фигурные кавычки, которые могут появиться при копировании из Word/Excel).

Запятые

Пропущенная запятая между свойствами → разметка не валидируется.
Лишняя запятая после последнего элемента в объекте или массиве → ошибка.
Как найти: В инструменте тестирования ищите красный крестик (✗) слева — он часто указывает на проблему с запятой.

Пример:

// ❌ Ошибка (лишняя запятая)
"author": {
  "@type": "Person",
  "name": "Иван Иванов",  // ← Запятая не нужна, это последнее свойство
}

// ✅ Исправлено
"author": {
  "@type": "Person",
  "name": "Иван Иванов"
}

2. Ошибки словаря Schema.org

Использование свойств, недопустимых для данного @type.
Пример: Свойство author не поддерживается для @type: Product.
Пропуск обязательных свойств.
Пример: Для Offer обязательно указание price и priceCurrency.

Решение:

Всегда сверяйтесь с документацией Schema.org для вашего @type.
Проверяйте разметку в тестере Google.

3. Нарушение правил Google

Размеченные данные должны быть видны на странице.
Пример: Если в JSON-LD указан рейтинг 5.0, а на странице его нет — это нарушение.
Запрещены манипулятивные практики.
Пример: Добавление ложных отзывов или несвязанных сущностей для обхода алгоритмов.

Что делать:

Ознакомьтесь с Google’s Structured Data Policies.
Убедитесь, что контент в разметке соответствует содержимому страницы.

4. Проблемы при копировании из Microsoft Office

Word/Excel автоматически заменяют кавычки на фигурные (“”).
Добавляют невидимые символы форматирования.

Решение:

Используйте HTML-редактор (например, VS Code, Sublime Text).
Вставляйте текст через «Вставить как обычный текст» (Ctrl+Shift+V).

Итоговый чек-лист

Кавычки: Только прямые ("").
Запятые: Ни лишних, ни пропущенных.
Словарь: Только разрешённые свойства для @type.
Контент: Разметка = содержимое страницы.
Проверка: Всегда тестируйте в Google Rich Results Test.

💡 Совет: Для сложных типов (например, Product с Review) используйте пошаговую проверку — сначала базовые свойства, затем вложенные объекты.

Ошибка → Даже одна пропущенная кавычка или запятая может привести к тому, что Google проигнорирует всю разметку!

Процесс добавления JSON-LD на сайт

Создание JSON-LD разметки зависит от вашего уровня знакомства с синтаксисом JSON-LD и словарем Schema.org. Ниже приведен пошаговый процесс для новичков, который поможет вам разобраться в основах и создать эффективную разметку.

1. Определите цель разметки

📌 Вопросы, которые нужно задать себе:

Что вы хотите разметить?
Убедитесь, что выбранный вами контент можно аннотировать с помощью Schema.org. Некоторые вещи могут казаться логичными, но не иметь подходящего типа в словаре.
Зачем вам это нужно?
Определите, есть ли практическая польза (например, улучшение сниппетов в поиске) или вы просто экспериментируете. Разметка должна помогать поисковым системам лучше понимать ключевую информацию на странице.

2. Изучите документацию и примеры

Проверьте, поддерживает ли Google ваш тип разметки.
Откройте официальную документацию Google и найдите примеры.
Не изобретайте велосипед!
Используйте готовые примеры от Google или Schema.org, адаптируя их под свои нужды.

3. Откройте страницу типа данных на Schema.org

Перейдите на Schema.org и найдите нужный @type (например, Product, Article).
Ознакомьтесь с:
- Описанием типа,
- Обязательными и рекомендуемыми свойствами,
- Примерами использования.

4. Скопируйте “неизменяемые” элементы

Начните с базовой структуры:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "ТипДанных"
}
</script>

Не забывайте, что тег <script> обязателен!

5. Определите свойства и их значения

Выпишите свойства, которые хотите добавить (например, для Product: name, description, image).
Пока не думайте о синтаксисе — просто составьте список.

6. Добавьте синтаксис JSON-LD и вложенности

Заполните свойства, соблюдая правила:
- Кавычки: только "".
- Запятые: между свойствами, но не после последнего.
Для вложенных объектов (например, offers в Product) используйте фигурные скобки {} и указывайте @type.

Пример для товара:

{
  "@context": "http://schema.org",
  "@type": "Product",
  "name": "Смартфон XYZ",
  "image": "https://example.com/image.jpg",
  "offers": {
    "@type": "Offer",
    "price": "299.99",
    "priceCurrency": "USD"
  }
}

7. Протестируйте разметку

Используйте Google’s Structured Data Testing Tool.
Убедитесь, что:
- Нет ошибок (красных крестиков),
- Все свойства распознаются.

8. Добавьте разметку на сайт

Способ 1: Вставьте код в <head> страницы.
Способ 2: Для динамического контента согласуйте с разработчиками (например, генерация через CMS).
Дополнительно: Используйте itemID и itemRef для сложных структур (подробнее в статье Moz).

9. Делитесь опытом!

У вас есть вопросы или интересные кейсы по JSON-LD? Делитесь в комментариях!

Итог:

Планируйте → Изучайте → Копируйте → Тестируйте → Внедряйте.
Избегайте типичных ошибок: неправильные кавычки, запятые, нарушение правил Google.
Используйте инструменты валидации на каждом этапе.

Теперь вы готовы создавать SEO-оптимизированную разметку!

Подробнее о JSON-LD смотри официальную документацию