Yoast SEO Schema API

There is a full API to change the Yoast SEO schema output.

Table of Contents

To disable Schema entirely

If you return false or an empty array on the wpseo_json_ld_output filter, you disable all Yoast SEO's schema output.

add_filter( 'wpseo_json_ld_output', '__return_false' );

To add or remove graph pieces

As the documentation clearly shows we output a lot of graph pieces on some pages. You might want to remove some, or better yet, add your own. To do this you should use the wpseo_schema_graph_pieces filter.

Each of our graph pieces implements a WPSEO_Graph_Piece interface. We pass each of these pieces a WPSEO_Schema_Context object which has a lot of context variables. A good example of that can be found in our example use case, and deeper examples can be found here on Github.

Change a graph pieces' data

If you want to change the output of a certain piece, hook into our wpseo_schema_<class> filter. For instance:

add_filter( 'wpseo_schema_article', 'example_change_article' );

/**
 * Change @type of Article Schema data.
 *
 * @param array $data Schema.org Article data array.
 *
 * @return array $data Schema.org Article data array.
 */
function example_change_article( $data ) { 
  $data['@type'] = 'NonsensePage'; 
  return $data; 
}

To add images to your Schema

If you want to add an image to an object programmatically, you can do it as follows:


add_filter( 'wpseo_schema_article', 'example_change_article' );

/**
 * Add images to Article Schema data.
 *
 * @param array $data Schema.org Article data array.
 *
 * @return array $data Schema.org Article data array.
 */
function example_change_article( $data ) { 
  // This is the attachment ID for our image.
  $image_id = 12345; 
  
  // We instantiate the image class, it always needs an $id, so the output can be referenced by other graph pieces.
  $id = "#image_12345";
  $schema_image = new WPSEO_Schema_Image( $id );

  // Now we just generate and add the image output.
  $data['image'] = $schema_image->generate_from_attachment_id( $image_id );

  return $data; 
}

More specific filters

Enable / disabling graph pieces by filter

Sometimes you might want to enable or disable a graph piece based on other variables then the graph piece itself can determine. For instance, you might always want to show a Personon your site. You can do this by hooking into the wpseo_schema_needs_<class-name> filter. In this particular case, the code would look like this:

add_filter( 'wpseo_schema_needs_person', '__return_true' );

It really is as simple as returning true on that to always show it, but you can of course also hook a function there with more precise logic.

Social profiles

If you want to change which profiles to show on an author page, you can hook into our wpseo_schema_person_social_profiles filter. We do this on yoast.com to add people's GitHub and WordPress profile as well as their personal sites to their sameAs output:

add_filter( 'wpseo_schema_person_social_profiles', 'yoast_add_social_profiles' );

/**
 * Adds social profiles to our sameAs array.
 *
 * @param array $profiles Social profiles.
 *
 * @return array $profiles Social profiles.
 */
function yoast_add_social_profiles( $profiles ) {
  array_push( $profiles, 'github', 'personal', 'wordpress' );

  return $profiles;
}

Other filters

We also have some more specific filters for convenience:

  • wpseo_schema_webpage_type - changes the page type, so could be used to make the above example even simpler.
  • disable_wpseo_json_ld_search - disables the search potentialAction that we add on every page if you simply return true on it.
  • wpseo_json_ld_search_url - allows you to change the search URL for your site.
  • wpseo_schema_article_post_type - allows changing for which post types we output the Article graph piece.
  • wpseo_schema_person_user_id - allows changing the ID of the user we use to represent your site, should your site represent a person.