Simple Structured Data implementation in Drupal using the JSON-LD format

Blog's Schema Mapping


There is no denying of the importance of Structured Data in today’s world. From improved SEO, content rich search engine results to reducing crawler's indexing errors and future proofing, Structured Data is becoming more and more relevant everyday. This document will guide through a simple Implementation of Structured Data in JSON-LD format (developer's preferred choice and Google's recommended format).

Out of the Box Functionality

A typical Drupal installation comes with some basic structured data implementation, However It's in RDFa format which is pretty much outdated by now. Default data structure mapping is made possible by RDF module which is now available as a core module since version 8.x and onwards. To take advantage of core functionality simply enable the module from the Extend menu in Admin toolbar.

Core RDF Module
Core RDF module

This module helps implement schema mapping for obvious content. For example, a schema type of "Article" is set on a Content type named “Article”. This is also true for “Events” and a few other content types. RDF module also helps map a few fields to their corresponding schema properties. Again this is true for obvious ones, for example, field Image usually maps to Image property, name, title, body and a few other generic fields are supported and mapped accurately.

A few drawbacks for implementing built-in schema mapping are that there could be a few errors in mapping on autopilot, especially for uncommon Content and Entities. Another shortcoming of RDF module is that it implements schema mapping in RDFa syntax, which is not the latest or most efficient mapping syntax, Therefore we will implement JSON-LD schema syntax for this example.

Default Mapping
Default schema mapping for Image by RDF module

Documentation on Drupal’s RDF module To edit/remove default implementation, use builtin hook_preprocess_HOOK() functions, for example: function rdf_preprocess_node(&$variables) to override default Schema implementation.

Implementing Basic JSON-LD Schema Mapping

Mapping Data

To implement Schema mapping using JSON-LD syntax, first step is to pick a Schema “type” for our content types in Drupal. A few considerations should be taken during this step as explained in Structured Data overview. For this we should visit and after some consideration on requirement and fields, we will implement Blog type ON our Article Content-type. Next we mapped the required properties for Schema type with fields available on our content-type in a similar fashion.

Marking Up Data

One great thing about JSON-LD is that it can be implemented anywhere on a web page as long and it is contained within its designated tags <script type="application/ld+json"></script>. RDFa, Microdata and other outdated syntax require each property to be declared on its mapped HTML element which can span implementation across many templates. This flexibility makes implementation much simpler. To collect field values to map with corresponding Schema properties, we can use Drupal's Hook_preprocess_node function as it would be an "entity level" division occurring once per Content-type instance. Next, simply declare a PHP associative array and start building such that array's “Keys” represent the "Properties" and the "Value" is assigned the data or field value we mapped in the first step to the particular property. See Example Below:

Mappings Array
PHP Schema array build out

The only trick here is to match the structure of our PHP array with that of JSON Data as shown in examples without the script tags. Once the array is populated JSON Encode it and add it to the "Variables," so it's available to our Twig template.

Output Schema Mapping

Next we need to pick a region of the page to output our schema mappings. Again having chosen JSON-LD format proves use at this stage as well.

  • JSON-LD data is wrapped in script tags, so its not displayed on the page.
  • JSON-LD could be outputted anywhere on the page.

So pick any template to output the Schema Mappings JSON data, inside <script type='application/ld+json'> tags. Our JSON encoded PHP array variable could be outputted in TWIG, however it's important to use the "Raw" filter so useful data is not escaped by default TWIG behavior.

<script type="application/ld+json">
     {{ schema_mapping_json|raw }}
Twig Output
Rendering Encoded Schema array on Twig

And there we have it. We can test our Schema implementation buy Copy Pasting the Page's source code into Google's testing tool.