JSON-LD

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

Attention. If you embed micro markup using a plugin, you'll probably need to modify it. To do this, contact the plugin developer or another professional with development skills.
  1. Markup principles
  2. Types of content that can have markup
  3. How to mark up content
  4. Markup example

Markup principles

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 the 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.
To mark up multiple entities on a page, you can use:

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":"Иван Иванов"}, 
        {"@type":"Person", "name":"Петр Петров"}]
    },
    {
     "@type": "NewsArticle",
     "@id": "https://www.example-news.com/life/weather/moscow#zao",  
     "datePublished": "2018-12-11T09:56:49Z",
     "author": [{"@type":"Person", "name":"Иван Иванов"}, 
        {"@type":"Person", "name":"Алексей Алексеев"}]
    }
  ]
}
</script>

Read more about JSON-LD.

Types of content that can have markup

Yandex Metrica supports markup for the following content:

Other types of content will not be included in Yandex Metrica reports even with the correct 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#сao"
        }
  }
  </script>

@id can be used to calculate full scrolls and full reads. If used as an ID:

  • The article URL is specified, Yandex Metrica detects the fragment after the # (#fragment). Then Yandex Metrica searches for the HTML element in the article containing this fragment (id="fragment" attribute). If the fragment is found, indicators are calculated. The Article URL is also processed.
  • If a random value is picked and head contains a JSON-LD code, then the indicators are calculated according to the contents of the body. If the body code is located inside another HTML element, then the parent element for the markup is used for calculations. This is why data in the report may not be entirely accurate. Calculations are also performed this way if the Article URL ends with a # and no fragments follow it.
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": "The temperature in Moscow broke the record set in 1922",
"alternativeHeadline": "Temperature in November exceeds 12°C"

In the report, the article is called “The temperature in Moscow broke the record set in 1922 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. This counts the number of characters in the text, which is necessary for determining content volume and calculating scroll depth and read depth metrics.

"text": "On Wednesday, November 6, the temperature in Moscow broke the record set in 1922. According to the Fobos center, the air temperature was 12.1°C."
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.
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":"Peter 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":"Иван Иванов"} 
      }
}
</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": [
    {"@type": "Event", "name": "Heat"},
    {"@type": "Event", "name": "Moscow"}
]

Type (@type) is optional or specify any type that is supported by the standard.

If the name key isn't found, the system will try to find the values in the alternateName key.

Dates of publication and revisions

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"
Rubric

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. We recommend inserting a URL fragment after a #. The indicators will be calculated based on the content the URL fragment points to. Learn more.

"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.

Markup example

Below you can see an example of news markup.

<script type="application/ld+json">
{
   "@context":"http://schema.org",
   "@graph": [
       {
         "@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"
                 }
               }
            ]
        },
        {
          "@type": "NewsArticle",
          "@id": "https://www.example-news.com/life/weather/moscow#cao",
          "headline": "The temperature in Moscow broke the record set in 1922",
          "alternativeHeadline": "Temperature in November exceeds 12°C",
          "datePublished":"2018-12-11T08:56:49Z",
          "dateModified":"2018-11-06T09:26:10+04:00",
          "text": "On Wednesday, November 6, the temperature in Moscow broke the record set   in 1922. According to the Fobos center,           the air temperature was 12.1°C.",
          "author": [
              {"@type":"Person", "name":"Ivan Ivanov"}, 
              {"@type":"Person", "name":"Peter Petrov"}
           ],
          "about":{
              "@type": "Event",
              "name": "Moscow"
          },
          "url": "https://www.example-news.com/life/weather/moscow#cao"
        }
    ]
}
</script>