Schema.org Metatag

This project extends Drupal's Metatag module to display structured data as JSON LD in the head of web pages. Read more about Schema.org, JSON LD, and how this module works in an article on Lullabot.com, Create SEO Juice From JSON LD Structured Data in Drupal.

Since the Schema.org list is huge, and growing, this module only provides a subset of those values. But it is designed to be extensible. The current list of Schema.org top-level (entity) object types includes:

Many second-level properties are available to use on the above, including:

Using the override system in Metatag module you can define default structured data values for all content types, override the global content defaults for a particular content type, or even override everything else on an individual node to provide specific values for that node. Hard-code properties or identify patterns using token replacements.

Validation

Additional Resources

Known Issues

The Drupal 7 version requires a minimum of PHP 5.5, for easiest compatibility between the D7 and D8 code.
The Drupal 7 Zen theme strips out part of the JSON LD element, invalidating the result. Use a different theme or see the Zen issue: #2934644: Don't remove type="application/ld+json" in zen_process_html_tag().
To populate the image width and height properties, use the appropriate tokens. In Drupal 8, the core Token module provides image height and width token. For example, the token [node:field_image:0:width] will be replaced with the width of the first image in field_image on the current node. In Drupal 7, you'll need to enable the Imagecache Token module, which provides the tokens for image dimensions which are missing in Drupal 7.

Upgrading from 8.x-1.x to 8.x-2.x

The Schema Audit sub-module was deprecated in 8.x-1.x and removed from 8.x-2.x. Before upgrading from 8.x-1.x to 8.x-2.x ensure the Schema Audit module is not installed.

There are some API changes in 8.x-2.x, but the configuration is identical. If you have been using 8.x-1.x and are not using custom code, you should be able to seamlessly switch to 8.x-2.x. If you are using custom code, you'll need to review the changes.

See the documentation guide links on the project page for more information.

Development Roadmap and Instructions

The 8.x-1.x and 7.x-1.x versions are in sync, the same content types, properties, etc. They're able to share Traits and the SchemaMetatagManager code with few changes between the versions. Both of these branches are stable and will not get any new features.

There is a new 8.x-2.x branch that will become the recommended branch for D8. It consists of a re-architecture that includes a PropertyType plugin that maps to Schema.org objects and a service that parses information from a Schema.org json export. By adding some extra information to the Tag plugin, you can indicate which PropertyType each plugin uses, and what Schema.org objects to display as options.

Example JSON LD

Using this module, the code in the head of the page might end up looking like this:

<script type="application/ld+json">{
    "@context": "http://schema.org",
    "@graph": [
        {
            "@type": "Article",
            "description": "Curabitur arcu erat, accumsan id imperdiet et, porttitor at sem. Donec sollicitudin molestie malesuada. Donec sollicitudin molestie malesuada. Donec rutrum congue leo eget malesuada. Nulla quis lorem ut libero malesuada feugiat. Vestibulum ac diam sit amet quam vehicula elementum sed sit amet dui.",
            "datePublished": "2009-11-30T13:04:01-0600",
            "dateModified": "2017-05-17T19:02:01-0500",
            "headline": "Curabitur arcu erat]",
            "author": {
                "@type": "Person",
                "name": "Minney Mouse",
                "sameAs": "https://example.com/user/2"
            },
            "publisher": {
                "@type": "Organization",
                "name": "Example.com",
                "sameAs": "https://example.com/",
                "logo": {
                    "@type": "ImageObject",
                    "url": "https://example.com/sites/default/files/logo.png",
                    "width": "600",
                    "height": "60"
                }
            },
            "mainEntityOfPage": {
                "@type": "WebPage",
                "@id": "https://example.com/story/example-story"
            },
        },
    ]
}</script>

Recommended Workflow for Tokens and Overrides

The best way to use this functionality is to take advantage of tokens to pull the right information from the content item, setting up the appropriate tokens for each content type on the global metatag settings page. When configured this way, the JSON-LD on each node will automatically contain the right values, values which match the content being viewed.

It is possible to configure the metatag module to override each individual node with different values by adding a metatag field to the content type. In this workflow you assume editors will manually input content directly into the metatag form when they edit the nodes. But there are several reasons why this workflow is likely to be a problem:

Validation of Schema.org data can be challenging. The best way to be sure it validates is to configure it globally using tokens to pull in contextual data, test the results, and lock it down.
If you expose the configuration to editors, they will be able to change all values, not just one or two. They may not realize that their changes will invalidate the results, or even know how to validate them.
Editors are unlikely to know how to use tokens, or what to do with tokens that are already there.
The metatag fields are not large enough to contain large paragraphs of text typed in manually. There's plenty of room to pull in multiple paragraphs of text using a field token, but not by typing the text into the metatag field.
One of the expectations of Schema.org is that the JSON-LD represents the same information that is already on the page. It should not contain different values. Using tokens to pull the existing data into the metatags is consistant with that goal. Typing different information into individual nodes is not.

Supporting organizations:

Lullabot

Cascade Public Media

Mediacurrent

Project information

Seeking co-maintainer(s)
Maintainers are looking for help reviewing issues.
Module categories: Search Engine Optimization (SEO)
Ecosystem: Metatag
51,416 sites report using this module
Created by KarenS on 18 May 2017, updated 4 November 2023
Stable releases for this project are covered by the security advisory policy.
Look for the shield icon below.