JSON-LD

JSON-LD is a markup method that renders data using Linked Data (LD) objects.

Markup

Data in JSON-LD format is described by a set of comma-separated key-value pairs. The format provides reserved keys to define the description context or link the objects in different ways. For example, @context defines the object vocabulary (in this case — Schema.org), while @type defines the type of the entity described. For the full list of reserved keys, see JSON-LD documentation.

The entity is described in curly brackets { } within the <script> tag with the attribute type="application/ld+json" or type="ld+json". Indicate that the Schema.org vocabulary is used for markup: "@context":"http://schema.org". Use the @type key to specify the Schema.org class defining the entity described. Mark up the properties of the entity: use the properties of the specified Schema.org class as keys.

You can use a graph (@graph) to mark up multiple entities on a page. For each node of the graph, specify @id — a link to the page section containing the described entity.

The example below describes two news articles "@type":"NewsArticle". The article identifier ( @id key), publication date (datePublished key), and the article authors (author key) are specified as an array of two elements. The authors are described using nested entities of the Person class.

<script type="application/ld+json">
{  
  "@context": "http://schema.org",
  "@graph" : [
    {
     "@type": "NewsArticle",
     "@id": "https://www.example-news.com/life/weather/moscow#cao",  
     "datePublished": "2018-12-11T08:56:49Z",
     "author": [{"@type":"Person", "name":"Ivan Ivanov"}, 
        {"@type":"Person", "name":"Peter Petrov"}]
    },
    {
     "@type": "NewsArticle",
     "@id": "https://www.example-news.com/life/weather/moscow#zao",  
     "datePublished": "2018-12-11T09:56:49Z",
     "author": [{"@type":"Person", "name":"Ivan Ivanov"}, 
        {"@type":"Person", "name":"Alexey Alexeyev"}]
    }
  ]
}
</script>

Read more about JSON-LD.

Types of content that can have markup

How to mark up content

Follow the guidelines below to make sure that your markup is processed correctly by Yandex.Metrica. To get more complete statistics, we recommend that you mark up all the content elements, but only three are required: identifier, headline, and text. If you already use JSON-LD, see if the markup on your website meets these requirements. The code examples in the guidelines aren't the only correct markup option.

Markup can be added to the site automatically — for example, using WordPress plugins. Before use, make sure that the selected plugin allows you to pass all the necessary markup elements to the page code.

Attention. If there are several content units on a single page, mark each of them separately so that statistics are collected correctly.

Specify the following content elements (mandatory elements are marked with an asterisk):

Identifier*

The identifier is specified using the reserved @id key. Yandex.Metrica uses it to distinguish between different content. The identifier isn't shown in reports. Examples of identifiers are a content link or an arbitrary unique value.

"@id": "https://www.example-news.com/life/weather/moscow#cao"

If the @id key is not found, the system tries to find it in the nested entities within the mainEntity or mainEntityOfPage keys.

<script type="application/ld+json">
{  
  "@context": "http://schema.org",  
  "@type": "NewsArticle",  
  "mainEntityOfPage": {
         "@type": "WebPage",
         "@id": "https://www.example-news.com/life/weather/moscow#cao"
      }
}
</script>
Headline*
The headline is shown in Yandex.Metrica reports. It can be specified in the headline or alternativeHeadline keys. If both keys are found, their values are separated by a space. For example, if the headlines are marked up like this:
"headline": "1922 record temperature broken in Moscow",
"alternativeHeadline": "November temperature exceeds 12°C"

In the report, the article is called “1922 record temperature beaten in Moscow Temperature in November exceeds 12°C”.

If none of the above keys are found, the value of the name or itemReviewed key is used as the headline (for the Review class).

Text*

The text must be contained in the text key. The text defines the number of characters. This is necessary to determine the volume of materials and calculate scroll depth and read depth metrics.

"text": "The temperature in Moscow on Wednesday, November 6 
broke the record set in 1922. The air temperature was 12.1°C 
  according to the Fobos center."
If the text key is not found, the following content is taken as text:
  • Content of the anchored element from the url or @id key value:

     "@context" : "https://schema.org",
     "@type" : "Article",
     "url":"https://www.example-news.com/life/weather/moscow#cao"
  • Content of the node embedding the entity described (if it is something other than <head>).

  • Content of the <body> page in all other cases.

When calculating the text size, the tag characters are ignored.

Note. You can get complete statistics for content with text longer than 500 characters. Content with shorter text is only taken into account in recirculation.
Author

The author is specified using the author key. If there are several authors, list them in an array.

 "author": [
    {"@type": "Person","name": "Ivan Ivanov"}, 
    {"@type":"Person", "name":"Pyotr Petrov"}
  ]

If the key was not found, the system will try to find it in the nested entities in the mainEntity or mainEntityOfPage keys.

<script type="application/ld+json">
{  
  "@context": "http://schema.org",  
  "@type": "NewsArticle", 
  "@id": "12345", 
  "mainEntityOfPage": {
         "@type": "WebPage",
         "author": {"@type":"Person", "name":"Ivan Ivanov"} 
      }
}
</script>

With this data, you can view statistics for individual authors.

Topic

You can mark up keywords and hashtags as topics. Specify topics in the about key:

"about": ["Heat", "Moscow"]

If no about key was found, the system will try to find the values in the name or alternateName keys.

Dates of publication and revision

The dates of publication and revision are specified in the datePublished and dateModified keys. Dates are written in ISO 8601 format.

"datePublished":"2018-12-11T08:56:49Z",
"dateModified":"2018-11-06T09:26:10+04:00"
Category

A category is a section of a website dedicated to a specific topic. To mark up a category, use the BreadcrumbList key. It describes a chain of linked web pages (“breadcrumbs”), which usually ends with the current content. In the BreadcrumbList, define multiple ListItem type entities in the itemListElement key, and describe the current and broader categories.

Category nesting can be defined by the position key. For example, the “Life” category may contain nested categories like “Weather” and “Incidents”. If "position":"1", the content is at the top level (“Life”). If "position"="2", it's at the second level (“Weather”).

The content category is the value of the name key with the highest position value.

Note. At the moment, the statistics show two levels of category nesting.
{
  "@context":"http://schema.org",
  "@type":"BreadcrumbList",
  "itemListElement":[
    {
      "@type":"ListItem",
      "position":1,      
      "item":{
          "@id":"//example-news.ru/life",
          "name":"Life"}
    },
    {
      "@type":"ListItem",
      "position":2,
      "item":{
          "@id":"//example-news.ru/life/weather",
          "name":"Weather"}
    }]
}
Content URL

The content URL must be included in the url key.

"url": "https://www.example-news.com/life/weather/moscow#cao"

If the markup is correct and the tag is properly enabled, statistics on the content will soon start to be collected in Yandex.Metrica.