How do I integrate a theme's schema output with Yoast SEO?

Definition: Integrating a theme's schema output with Yoast SEO means connecting its descriptions of entities, such as an organization or a book, to Yoast's structured data graph. The integration uses entity identifiers and the Schema API to extend existing data or add connected entities.

Key facts

• As of October 2026, Yoast's integration guidelines recommend adapting existing theme markup to its graph approach and disabling the theme's separate output when Yoast manages the completed graph.
• Yoast's schema specification describes a base graph containing WebPage, WebSite, and Organization, or Person for a personal website.
• Yoast's Schema API documentation provides wpseo_schema_graph_pieces for adding or removing graph pieces and wpseo_schema_<class> for changing an existing piece.

What structure does the integration use?

A graph is a collection of connected entity descriptions. A node is an individual entity description, and @id is its identifier. JSON-LD is the linked data format used for the output; @graph contains the nodes.

Yoast's specification assigns each distinct entity a top-level node and connects nodes through their IDs. Its base example links the website to its publishing organization with publisher, and the webpage to the website with isPartOf.

This structure gives the theme integration a specific task: identify which entities already exist and where additional information belongs. The specification extends the base graph according to the page's main entity and attributes.

How does the theme handle overlapping data?

Yoast's integration guidelines use Organization as the duplication example. When the theme's description is less extensive, it can become a reference to Yoast's organization node. When it contains more information, the integration can filter that Yoast node to include the additional data.

The same guidelines allow descriptions to share an @id when their values do not contradict each other, so consumers can combine them. Existing nested JSON-LD or microdata needs review for conflicting information before integration.

Which code connects the theme's entities?

Yoast's Schema API documentation describes custom graph pieces that extend Abstract_Schema_Piece and receive a Meta_Tags_Context object containing context variables. The developer registers additional pieces through wpseo_schema_graph_pieces. Changes spanning multiple nodes use wpseo_schema_graph.

For the connection itself, Yoast's integration guidelines distinguish a secondary item, linked with isPartOf, from the page's main subject, linked with mainEntityOfPage. The following PHP fragment follows its main-entity example:

$canonical = YoastSEO()->meta->for_current_page()->canonical;
$data['mainEntityOfPage'] = [ '@id' => $canonical ];

Here, $data is the entity's schema data array. The canonical URL identifies Yoast's WebPage node. The theme developer also checks whether Yoast SEO is running and manages the theme's output accordingly.

How can the output be inspected?

Yoast's Schema API documentation provides a development filter that formats its schema output for easier reading:

add_filter( 'yoast_seo_development_mode', '__return_true' );

The documentation recommends removing this setting for production. Its breadcrumb removal example also removes the breadcrumb property from WebPage, illustrating that removing a node requires attention to references elsewhere in the graph.

Related terms

• Structured data
• JSON-LD
• Schema.org @id
• Organization structured data

FAQ

Does this require disabling all of Yoast's schema?

Yoast's Schema API documentation supplies filters for individual pieces and the complete graph. You can use those integration points to retain and extend its output.

What if the website stops using Yoast SEO?

The integration guidelines say a theme can construct its own graph following Yoast's specification when Yoast SEO is absent. Your developer needs to account for that condition in the output logic.

Sources

1. Yoast, "Schema - Integration guidelines", undated
2. Yoast, "Schema - Specification", undated
3. Yoast, "Schema - API documentation", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer