Technical SEO
How to Add Structured Data to WordPress (Plugins, Rank Math, and by Hand)
To add structured data to WordPress, you have three routes: let an SEO plugin such as Rank Math or Yoast output it, install a dedicated schema plugin, or write the JSON-LD yourself and print it from a snippet plugin, a must-use plugin or your theme. The set-up I recommend uses the first route for the sitewide graph and one of the other two for the types that matter to the business.
This guide compares the three routes and their trade-offs, then does the part the WordPress schema guides I read skip: overriding what the plugin outputs. I ran the Course and Event overrides below on a local WordPress 7.1.2 install with Rank Math 1.0.279, and the output shown is what that install printed.
Key takeaways
- Check what your SEO plugin already prints before adding anything. Two plugins describing the same page is an easy fault to create, and it is invisible until you read the page source.
- Rank Math’s free version includes Course and Event types, but its defaults are not the finished article: on my test install it appended the site name to course and event names and printed the course provider as a separate, unlinked organisation.
- The clean fix is a filter, not a second plugin. Rank Math’s per-type entity filters and Yoast’s
wpseo_schema_graphfilter let you change the plugin’s graph from a few lines of PHP that survive plugin updates. - Plugin schema-type menus lag behind Google. Rank Math still offers an online-only Event mode, but Google’s event documentation says events without a physical location are not supported.
- For Course, the markup on a single course page is only half the job. Google’s course list needs at least three courses and
ItemListmarkup on a summary page.
What WordPress outputs before you add anything
WordPress core prints no structured data of its own: on my test install (WordPress 7.1.2, the default Twenty Twenty-Five theme, no plugins) the page source had no JSON-LD at all. What you see on a typical site comes from the SEO plugin, the theme, or other plugins.
Start by opening the page source (not the browser inspector, which shows the DOM after scripts run) and searching for application/ld+json. Count the blocks and read the @type values in each. If you find an Organization from the theme and another from the SEO plugin, fix that before you add a single new type.
What Yoast prints by default
Yoast documents its output precisely. Its schema documentation says every page should attempt to output an Organization, a WebSite and a WebPage piece, joined in one @graph. On single posts it adds an Article connected to the WebPage, and pages with its FAQ or HowTo blocks get those pieces too.
Course and Event are not among the pieces that page lists. If you run Yoast and need either type, you add it yourself, which is covered below.
What Rank Math prints by default
Rank Math sets a default schema type per post type under Rank Math SEO → Titles & Meta, and lets you add more types per post from its Schema Generator. Its schema documentation lists Course and Event among the types in the free version. The Custom Schema builder, schema templates and display conditions are marked as PRO features.
On my test install, a page with no schema of its own still got a Person/Organization entity, a WebSite and a WebPage. Add a Course or Event from the Schema Generator and it joins the same graph.
Plugin type lists lag behind Google
A plugin offering a type does not mean Google still does anything with it. Two examples from pages I read in September 2026:
- Rank Math’s documentation still says it adds Sitelinks Search Box schema automatically when the Schema module is on. Google removed the sitelinks search box documentation in November 2024 because the feature is no longer shown in results.
- The Schema & Structured Data for WP & AMP plugin still lists
SpecialAnnouncementon its WordPress.org page. Special Announcement was one of the types Google said it would phase out in its June 2025 announcement.
Neither causes harm on its own. But it means the plugin’s menu is not a guide to what earns a search feature today. For that, use Google’s own documentation, or the type-by-type status in schema markup examples and structured data in SEO.
The three routes compared
| Route | Best for | What it costs | Where it breaks |
|---|---|---|---|
| SEO plugin defaults (Rank Math, Yoast) | The sitewide graph: organisation, website, web page, article, breadcrumbs | Nothing extra; you probably run one already | Types the plugin does not model well, and values it fills from the wrong field |
| Dedicated schema plugin | Many types edited by non-developers, with per-type forms | Another plugin to update, and a second schema source to reconcile | Duplicate entities when the SEO plugin also prints the same type |
| Hand-written JSON-LD | Types generated from your own data: LMS courses, event post types, product feeds | Developer time, and you own the maintenance | Nobody updates it when the page changes, unless it reads from the same fields the page does |
In practice the routes are layers: the SEO plugin for the base graph, then a schema plugin or code for the rest, depending on who will maintain it.
Route 1: use the SEO plugin you already have
This is the right default for articles, organisation details and breadcrumbs. The plugin already knows the canonical URL, author, dates and featured image, and keeps them in sync.
Before you trust it, fill in the settings it depends on: organisation or person, logo, social profiles. Rank Math’s knowledge graph settings and Yoast’s site representation settings feed every page. Left empty, they produce the thin Organization nodes described in Organization schema.
For Course and Event, Rank Math gives you a form per post. That works for a handful of pages. It stops working when the real data (cohort dates, prices, venue) lives in an LMS or an events plugin, because an editor then has to type the same facts twice and keep them matched by hand.
Route 2: add a dedicated schema plugin
A schema plugin earns its place when you need many types with editor-friendly forms and your SEO plugin does not cover them. Schema & Structured Data for WP & AMP is a common example: its WordPress.org page lists more than 35 schema types, Course and Event blocks for the editor, and 100,000+ active installations as of September 2026.
The cost is a second source of truth. If Rank Math prints an Organization and the schema plugin prints another, you now have two descriptions of your company on every page, and you have to switch one of them off in settings.
My rule: only add a schema plugin if you can name the types it will own, and switch those types off in the SEO plugin on the same day.
Route 3: write the JSON-LD yourself
Hand-written JSON-LD is the right call when the data already exists in WordPress in structured form: an LMS course post type, an events plugin’s fields, a custom post type with Advanced Custom Fields. The markup reads from the same fields the page template reads from, so it cannot drift from what visitors see.
That matters because Google’s general structured data guidelines say not to mark up content that is not visible to readers, and that Google won’t show a rich result for time-sensitive content that is no longer relevant. Markup generated from the page’s own fields meets both rules by default.
Where to put the code
You have three places to put it, in order of preference:
- A must-use plugin (a PHP file in
wp-content/mu-plugins/). It loads on every request, cannot be deactivated from the dashboard by accident, and survives theme changes. - A snippet plugin. WPCode and Code Snippets both store PHP snippets in the database and run them as if they were in
functions.php. Good for sites where no developer has file access. WPCode lists page-specific snippets among its Pro features. - A child theme’s
functions.php. Fine, but the schema then disappears if someone switches theme.
Pasting a static JSON-LD block into one page’s header box works for a single, rarely changing page, but nothing connects it to the content, so it goes stale first.
A hand-written Event block
This is the must-use plugin I ran on the test install. It builds an Event from custom fields, and switches off Rank Math’s own Event on the same pages so the page does not carry two.
<?php
/**
* Plugin Name: Hand-written Event JSON-LD
*/
// Stop Rank Math emitting its own Event on pages this file handles.
add_filter( 'rank_math/snippet/rich_snippet_event', function ( $value ) {
return is_singular() && get_post_meta( get_queried_object_id(), 'event_start', true ) ? true : $value;
} );
add_action( 'wp_head', function () {
if ( ! is_singular() ) {
return;
}
$id = get_queried_object_id();
$start = get_post_meta( $id, 'event_start', true );
if ( ! $start ) {
return;
}
$schema = [
'@context' => 'https://schema.org',
'@type' => 'Event',
'@id' => get_permalink( $id ) . '#event',
'name' => wp_strip_all_tags( get_the_title( $id ) ),
'description' => wp_strip_all_tags( get_the_excerpt( $id ) ),
'startDate' => $start,
'endDate' => get_post_meta( $id, 'event_end', true ),
'eventStatus' => 'https://schema.org/EventScheduled',
'location' => [
'@type' => 'Place',
'name' => get_post_meta( $id, 'venue_name', true ),
'address' => [
'@type' => 'PostalAddress',
'streetAddress' => get_post_meta( $id, 'venue_street', true ),
'addressLocality' => get_post_meta( $id, 'venue_city', true ),
'postalCode' => get_post_meta( $id, 'venue_postcode', true ),
'addressCountry' => get_post_meta( $id, 'venue_country', true ),
],
],
'offers' => [
'@type' => 'Offer',
'price' => (float) get_post_meta( $id, 'event_price', true ),
'priceCurrency' => 'GBP',
'availability' => 'https://schema.org/InStock',
'url' => get_post_meta( $id, 'event_booking_url', true ),
],
'organizer' => [
'@type' => 'Organization',
'name' => get_bloginfo( 'name' ),
'url' => home_url( '/' ),
],
];
wp_print_inline_script_tag(
wp_json_encode( $schema, JSON_UNESCAPED_SLASHES | JSON_HEX_TAG ),
[ 'type' => 'application/ld+json' ]
);
} );
With that file active, the page had one Event (mine) and Rank Math’s graph kept its WebSite and WebPage without an Event in it.
Three details in that code are worth copying even if you change everything else:
- Build an array and encode it. Do not echo field values into a JSON template string. A quote or line break in a field then breaks the JSON, and HTML escaping functions produce entities such as
"that end up in the data, because nothing decodes them inside a script tag. JSON_HEX_TAGencodes<and>, so a field containing</script>cannot close the tag early.wp_print_inline_script_tag()takes the script body and an array of attributes, and has been in core since WordPress 5.7. It keeps the output consistent with how WordPress prints its own inline scripts.
The full Event property rules (dates, time zones, eventStatus values, offers.url) are in Event schema.
How to override the plugin’s output for Course and Event
This is where WordPress sites with courses or events lose accuracy: the plugin prints a Course or Event, it validates, and nobody reads it again.
Here is what Rank Math 1.0.279 printed on my test install for a course page. I set the schema fields as post meta in the same shape the Schema Generator saves them, with the name and description left on their default variables (%seo_title% and %seo_description%). This is the Course entity, trimmed of the graph links:
{
"@type": "Course",
"name": "Technical SEO Foundations - Test Academy",
"description": "Six-week cohort course on crawling, indexing and schema.",
"provider": {
"@type": "Organization",
"name": "Test Academy",
"sameAs": "http://localhost:8841"
},
"offers": {
"@type": "Offer",
"price": "490",
"priceCurrency": "GBP",
"category": "Paid",
"availability": "InStock",
"validFrom": "2026-10-01"
},
"@id": "http://localhost:8841/technical-seo-foundations/#schema-4",
"publisher": {
"@id": "http://localhost:8841/#person"
}
}
Three things are wrong with it, and none shows up as an error in a validator:
- The name carries the site name.
%seo_title%resolves to the SEO title, which includes the separator and site name. Google’s course list documentation says each course must have a valid name and gives examples of what it treats as invalid, such as promotional phrases and prices in titles. A site-name suffix is not on that list, but it is not the course’s name either. The Event entity had the same suffix. - The provider is a stranger. The course’s
provideris a new, nested organisation with no@id, while the page’spublisherpoints at the site’s own entity. A parser sees two organisations where there is one. - Nothing reads the real course data. The start date and price were typed into the schema form. When the next cohort is scheduled in the LMS, the schema keeps the old date until someone remembers.
The Event on the same install had the site-name suffix too. Its dates were fine: Rank Math’s own filter rewrote 2026-11-12T10:00 as 2026-11-12T10:00:00+00:00 using the site’s time zone setting.
The override, as a must-use plugin
Rank Math runs every schema entity through a filter named after its type, rank_math/snippet/rich_snippet_{type}_entity. Its filter reference documents both that filter and rank_math/json_ld, which receives the whole graph. The code below uses both:
<?php
/**
* Plugin Name: Rank Math schema overrides (Course, Event)
*/
// Course: clean name, and next cohort, price and enrol link from the course's own fields.
add_filter( 'rank_math/snippet/rich_snippet_course_entity', function ( $entity ) {
$post_id = get_queried_object_id();
$entity['name'] = wp_strip_all_tags( get_the_title( $post_id ) );
$start = get_post_meta( $post_id, 'course_start_date', true );
if ( $start ) {
$entity['hasCourseInstance'] = [
[
'@type' => 'CourseInstance',
'courseMode' => get_post_meta( $post_id, 'course_mode', true ) ?: 'Online',
'courseSchedule' => array_filter( [
'@type' => 'Schedule',
'startDate' => $start,
'endDate' => get_post_meta( $post_id, 'course_end_date', true ),
] ),
],
];
}
$price = get_post_meta( $post_id, 'course_price', true );
if ( is_numeric( $price ) ) {
$entity['offers'] = [
'@type' => 'Offer',
'category' => $price > 0 ? 'Paid' : 'Free',
'price' => $price + 0,
'priceCurrency' => 'GBP',
'url' => get_post_meta( $post_id, 'course_enrol_url', true ) ?: get_permalink( $post_id ),
];
}
return $entity;
} );
// Event: clean name, booking URL and full schema.org status. Priority 20 runs
// after Rank Math's own callback (11), which rewrites the dates.
add_filter( 'rank_math/snippet/rich_snippet_event_entity', function ( $entity ) {
$post_id = get_queried_object_id();
$entity['name'] = wp_strip_all_tags( get_the_title( $post_id ) );
$booking = get_post_meta( $post_id, 'event_booking_url', true );
if ( $booking && isset( $entity['offers'] ) ) {
$entity['offers']['url'] = esc_url_raw( $booking );
}
if ( ! empty( $entity['eventStatus'] ) && 0 !== strpos( $entity['eventStatus'], 'http' ) ) {
$entity['eventStatus'] = 'https://schema.org/' . $entity['eventStatus'];
}
return $entity;
}, 20 );
// Graph-level changes: point every Course at the site's own entity, and add
// the ItemList that Google's course list needs to the courses hub page.
add_filter( 'rank_math/json_ld', function ( $data, $jsonld ) {
$publisher_id = $data['publisher']['@id'] ?? '';
foreach ( $data as $key => $entity ) {
if ( is_array( $entity ) && 'Course' === ( $entity['@type'] ?? '' ) && $publisher_id ) {
$data[ $key ]['provider'] = [ '@id' => $publisher_id ];
}
}
if ( is_page( 'courses' ) ) {
$courses = get_pages( [
'parent' => get_queried_object_id(),
'sort_column' => 'menu_order',
] );
// Google's course list needs at least three courses.
if ( count( $courses ) >= 3 ) {
$items = [];
foreach ( array_values( $courses ) as $i => $course ) {
$items[] = [
'@type' => 'ListItem',
'position' => $i + 1,
'url' => get_permalink( $course ),
];
}
$data['courseList'] = [
'@type' => 'ItemList',
'itemListElement' => $items,
];
}
}
return $data;
}, 100, 2 );
The priorities are not decoration. In Rank Math’s source, its own Event callback sits on the entity filter at priority 11, and the callback that adds @id, publisher and mainEntityOfPage to each entity runs on rank_math/json_ld at 99. My Event filter runs at 20 so it sees the rewritten dates, and the graph filter runs at 100 so the publisher @id already exists when it reads it.
Change the meta keys (course_start_date, event_booking_url and the rest) to wherever your LMS, events plugin or custom fields store the data. The point is that the schema and the page read the same values.
What it printed after the override
The same course page, after the must-use plugin was active:
{
"@type": "Course",
"name": "Technical SEO Foundations",
"description": "Six-week cohort course on crawling, indexing and schema.",
"provider": {
"@id": "http://localhost:8841/#person"
},
"hasCourseInstance": [
{
"@type": "CourseInstance",
"courseMode": "Online",
"courseSchedule": {
"@type": "Schedule",
"startDate": "2027-01-12",
"endDate": "2027-02-23"
}
}
],
"offers": {
"@type": "Offer",
"category": "Paid",
"price": "490",
"priceCurrency": "GBP",
"url": "http://localhost:8841/enrol/technical-seo-foundations/"
}
}
The hub page at /courses/ gained an ItemList with the three child course URLs. The Event’s name lost its suffix, its offer gained the booking URL, and eventStatus became https://schema.org/EventScheduled.
One thing I did not expect: Rank Math printed "price": "490" and "position": "1" as strings, although my code set integers. Its output function passes the whole graph through wp_kses_post_deep() before encoding, and that returns strings. Google’s own examples use numbers. I have not seen string values rejected, but if you need true numbers, print that entity yourself as in Route 3.
The course-page side of this (which properties to use and how to generate them for hundreds of courses) is covered in depth in Course schema.
The same override in Yoast
Yoast has no Course or Event piece to modify, so you add one. The wpseo_schema_graph filter receives the full graph and a context object, and Yoast’s documentation shows referencing its core pieces by their fixed IDs.
<?php
/**
* Plugin Name: Yoast Course piece
*/
add_filter( 'wpseo_schema_graph', function ( $graph, $context ) {
if ( ! is_singular( 'course' ) ) {
return $graph;
}
$post_id = get_queried_object_id();
$course = [
'@type' => 'Course',
'@id' => $context->canonical . '#course',
'name' => wp_strip_all_tags( get_the_title( $post_id ) ),
'description' => wp_strip_all_tags( get_the_excerpt( $post_id ) ),
'mainEntityOfPage' => [ '@id' => $context->main_schema_id ],
];
// The Organization or Person the site represents, as set in Yoast.
if ( $context->site_represents_reference ) {
$course['provider'] = $context->site_represents_reference;
}
$graph[] = $course;
return $graph;
}, 10, 2 );
I checked the filter signature and the canonical, main_schema_id and site_represents_reference properties against Yoast’s source on GitHub, but I did not run this block on a live Yoast install. Treat it as a starting point and read the output before you ship it.
What Google does with Course and Event markup in 2026
Both types have changed in the last two years, so check what the markup still leads to.
Course. Google’s June 2025 post Simplifying the search results page listed Course Info among the structured data features being phased out, and a September 2025 update removed it from Search Console reporting and the Rich Results Test. What remains is the course list. Its documentation, last updated 8 September 2026, requires name and description on each course, recommends provider, says you must mark up at least three courses, and requires carousel markup on a summary or all-in-one page. It also notes a display limit of 60 characters for the description, and that the feature is available in English. Rank Math’s own documentation notes that Google has phased out Course Info.
Event. Google’s Event documentation, also last updated 8 September 2026, says virtual experiences with no real-world component are not supported and that events must take place in a physical location. Google’s changelog records the removal of the online event properties on 5 June 2025. Rank Math’s Event form still offers online, offline and mixed attendance modes, and an online event URL field. Mark up online-only webinars if other consumers use the data, but do not expect Google’s event experience to show them.
The Event documentation also says each event must have its own URL, and that the event experience only supports pages that focus on a single event. For a WordPress events calendar, that means markup on each event’s single page, not on the calendar archive.
For how these rich results affect clicks, see do rich snippets help SEO.
Test before and after you ship
Every change to WordPress schema needs three checks:
- Paste the rendered URL into the Rich Results Test. For Course, Google’s documentation says to look at the “Course list item” section and ignore errors reported for other types.
- Read the page source for duplicates. Validators check each block. They do not tell you that two plugins described the same course.
- Watch Search Console’s rich result reports after deployment. A template change that drops a required field shows up there as a rise in invalid items.
The differences between the Rich Results Test, the Schema.org validator and the command-line options are in schema markup validators compared.
If you edit a filter and the output does not change, purge the page cache before you assume the code is wrong.
Which route to choose
- You run Rank Math or Yoast and need articles, organisation and breadcrumbs: stay on the plugin. Fill in its settings properly and check Article schema against what it prints.
- You need Course or Event and the data lives in an LMS or events plugin: keep the SEO plugin for the base graph and override or add the type with a filter, as above.
- Editors need to add many types without a developer: a dedicated schema plugin, with the overlapping types switched off in the SEO plugin.
- One landing page needs one extra type: a static JSON-LD block in a snippet plugin is acceptable, with a note in your content inventory saying where it lives.
The SGM Lektra case study shows the approach on a custom multi-domain WordPress build, with structured data deployed across the templates that mattered. If you would rather have that layer designed and tested once than audited every time a plugin updates, that is part of GEO and technical SEO consulting.
Frequently asked questions
Do I need a plugin to add structured data to WordPress?
No. WordPress can print JSON-LD from any PHP hooked to wp_head, so a must-use plugin or a child theme is enough. In practice many sites already run an SEO plugin that outputs a base graph, and the real decision is whether to extend that plugin’s output or replace part of it.
Can I run Rank Math and Yoast at the same time?
You should not. Both output a full graph with an organisation, website and web page on every URL, so running both gives every page two conflicting descriptions. Pick one, and if you need types it does not cover, add them through its filter.
How do I get Google rich snippets on a WordPress site?
Add structured data for a type Google still supports, fill in its required properties, and validate the live URL in the Rich Results Test. Google’s general guidelines are clear that valid markup makes a page eligible for a rich result but does not guarantee one. Check the type’s current status first, because several have been retired since 2023.
Should the JSON-LD go in the head or the body?
Either works. Google’s introduction to structured data describes JSON-LD as embedded in a script tag in the head or body, and says Google can read it when injected by JavaScript. On WordPress, hooking into wp_head is the simplest place because SEO plugins print there too, so all the page’s schema appears in one place.
Why does my Rank Math Course or Event name include the site name?
The default name field uses the %seo_title% variable, which, with default title settings, resolves to the full SEO title including the separator and site name. Change the field to the post title in the Schema Generator, or set name from get_the_title() in the rank_math/snippet/rich_snippet_course_entity or _event_entity filter so every course and event is fixed at once.
Is FAQ schema still worth adding in WordPress?
Not for a Google search feature: Google’s changelog says that feature is no longer shown in Google Search results. What changed, and where FAQ markup can still help, is covered in FAQ schema. If your SEO plugin adds FAQPage automatically from an FAQ block, it does no harm, but do not add FAQ blocks to pages only to get the markup.