Schema.org Metatag

Extends Drupal's Metatag module to display Schema.org structured data as JSON-LD in the head of web pages.

schema_metatag
59,150 sites
148
drupal.org
api integration
SEO schema.org json-ld structured-data metatag rich-snippets search-engine-optimization
Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10, 9 v3.0.3
composer require 'drupal/schema_metatag:^3.0'

Overview

Schema.org Metatag extends Drupal's Metatag module to display structured data as JSON-LD in the head of web pages. This enables rich snippets and enhanced search engine results by providing Schema.org vocabulary markup that search engines like Google can understand and use to display enhanced search results.

The module allows you to either hard-code Schema.org properties or identify patterns using token replacements. 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.

The module provides a plugin-based architecture with property type plugins for various Schema.org data types, allowing for complex nested structured data with proper @type definitions. Multiple submodules are provided for specific Schema.org types like Article, Product, Event, Organization, etc.

Features

  • Renders Schema.org structured data as JSON-LD format in HTML head
  • Integrates seamlessly with Drupal's Metatag module
  • Supports token replacements for dynamic property values
  • Provides 43 property type plugins for Schema.org data types (Text, Number, Date, Organization, Person, ImageObject, etc.)
  • Supports complex nested Schema.org structures with proper @type hierarchies
  • Includes @graph wrapper for multiple Schema.org objects on a single page
  • Provides pivot functionality for multiple values in structured data
  • 21 submodules for specific Schema.org types (Article, Product, Event, Organization, etc.)
  • Extensible architecture allowing custom Schema.org types to be added
  • Uses Schema.org vocabulary data file for type hierarchies and property definitions
  • Caches Schema.org object trees and property information for performance
  • Supports visibility states for form elements based on @type selection

Use Cases

Article Rich Snippets for Blog Posts

Enable the schema_article submodule and configure default Schema.org Article metatags for blog content types. Set @type to BlogPosting, use tokens for headline ([node:title]), description ([node:summary]), datePublished ([node:created:html_datetime]), dateModified ([node:changed:html_datetime]), author name ([node:author:display-name]), and publisher organization. This enables Google to display rich snippets with author info, publish dates, and article previews in search results.

Product Rich Results for E-commerce

Enable the schema_product submodule and configure Product structured data for product content types. Include offer information with price, priceCurrency, and availability. Add aggregate ratings if using a rating system. This enables Google Shopping integration and rich product snippets showing price, availability, and star ratings directly in search results.

Local Business Organization Data

Enable the schema_organization submodule and configure Organization or LocalBusiness structured data for your site. Include name, logo, address, contact points, and opening hours. Set this as a global default to appear on all pages. This helps search engines understand your business identity and can trigger knowledge panel displays.

Event Listings with Structured Data

Enable the schema_event submodule and configure Event structured data for event content types. Include startDate, endDate, location (using Place property type with address), performer, and offers for ticketing information. This enables event rich results in Google Search showing dates, locations, and ticket prices.

Recipe Rich Results for Food Sites

Enable the schema_recipe submodule for recipe content types. Configure properties for prepTime, cookTime, recipeIngredient, recipeInstructions (using HowToStep), nutrition information, and aggregate ratings. This enables recipe rich results with cook times, ratings, and calorie information in search results.

FAQ Page Structured Data

Enable the schema_qa_page submodule and configure FAQPage structured data for FAQ content. Add Question items with acceptedAnswer using the proper property types. This enables FAQ rich results where questions and answers appear directly in search results, taking up more SERP real estate.

Sitelinks Searchbox

Enable the schema_web_site submodule and configure WebSite structured data with potentialAction set to SearchAction. Configure the target URL to your site's search page with the query parameter. This can enable the sitelinks searchbox feature in Google Search, allowing users to search your site directly from Google.

Video Content Rich Results

Enable the schema_video_object submodule for video content types. Configure thumbnailUrl, uploadDate, duration, description, and contentUrl. This enables video rich results with thumbnail previews and duration badges in search results.

Job Posting Structured Data

Enable the schema_job_posting submodule for job listing content. Configure title, description, hiringOrganization, jobLocation, baseSalary, and employmentType. This enables job posting rich results that can appear in Google for Jobs, increasing visibility for job listings.

Breadcrumb Navigation

Configure BreadcrumbList structured data to help search engines understand your site's hierarchy. This can improve how breadcrumbs appear in search results, replacing the URL with a readable navigation path.

Tips

  • Use the Google Rich Results Test (https://search.google.com/test/rich-results) to validate your JSON-LD output
  • Always include required properties for each Schema.org type - check Google's documentation for specific requirements
  • Use tokens for dynamic values like [node:title], [node:created:html_datetime], [node:field_image:url] to auto-populate structured data
  • For image dimensions, use tokens like [node:field_image:0:width] and [node:field_image:0:height] from the Token module
  • Configure global defaults first, then override at the content type level, then at the individual entity level if needed
  • The module renders JSON-LD in the @graph format, allowing multiple Schema.org objects on a single page
  • Use the 'pivot' option when you have multiple values (like multiple authors or offers) to create separate objects for each
  • Enable only the submodules you need - each adds additional Schema.org type groups to the Metatag configuration
  • Copy the schema_article_example module structure when creating custom Schema.org type extensions
  • Clear caches after installing new submodules to ensure new metatag groups appear in configuration

Technical Details

Hooks 2
hook_metatag_tags_alter

Allows modules to alter Schema Metatag tag definitions. Can be used to change property types, tree parents, tree depth, or enable multiple values for specific tags.

hook_schema_metatag_property_type_plugins_alter

Allows modules to alter Schema Metatag property type plugin definitions. Can be used to modify property types, sub-properties, and tree configurations for property type plugins.

Troubleshooting 7
JSON-LD not appearing in page source

Verify the module is enabled and configured correctly in Metatag settings. Check that at least the @type property is set for your Schema.org group. The module skips rendering if only @type is set with no other properties.

Token values not being replaced

Ensure token syntax is correct and the Token module is installed. Check that the entity context is available - some tokens require being on a specific entity page. Use Devel's token browser to verify token names.

Image dimensions not appearing

Use the specific image field tokens with index and property, e.g., [node:field_image:0:width] instead of generic image tokens. The core Token module provides these image dimension tokens.

Google validation errors for missing required properties

Review Google's structured data documentation for required properties for each type. Ensure all REQUIRED fields are filled in the Metatag configuration. Some types like Article require author and publisher even though Schema.org marks them as optional.

Serialization errors or broken structured data

This can occur when token replacements are different lengths than original tokens. The module includes automatic length recomputation, but if issues persist, check for special characters or newlines in token values.

Form elements not showing visibility states correctly

The visibility states depend on the @type selector. Ensure the @type property is configured first in the form. The module handles both main Metatag form and field widget form selectors differently.

Submodule metatag groups not appearing

After enabling a submodule, clear all caches. If still not appearing, verify the submodule's dependencies are met (e.g., schema_item_list requires metatag_views).

Security Notes 4
  • The module sanitizes output by removing HTML tags and converting values to plain text before JSON-LD encoding
  • Token values are processed through Drupal's render system which handles XSS prevention
  • The serialize/unserialize functions include safeguards against object injection attacks by using allowed_classes parameter
  • Image URL handling converts relative paths to absolute URLs and extracts src from img tags safely