Fixing JSON-LD Errors in WordPress

Where JSON-LD comes from on a WordPress site

Before fixing anything, it helps to know the usual suspects. Each one has its own way of being changed, and editing the wrong layer is the main reason fixes do not stick.

If you only remember one thing: never fix a plugin's output by editing the plugin's own files. Plugin updates overwrite those files. Changes belong in settings, in a child theme, or in a small site-specific plugin that uses the filters the plugin provides.

How WordPress breaks JSON-LD

Some faults are common to every platform, such as a trailing comma in a hand-written block. Others come from the way WordPress stores and processes content, and they catch out people who know JSON well:

• Script tags removed on save. WordPress filters post content for users who lack the unfiltered_html capability. On a standard single site only Administrators and Editors have it; on multisite only Super Admins do. When an Author or an Editor on a multisite network saves a post containing a Custom HTML block with a script tag, the script is stripped and the JSON is left as visible text or lost.
• Titles containing HTML entities. get_the_title() runs the title through WordPress's typography filter, which turns straight quotes and apostrophes into curly ones and may return them as HTML entities such as ’. A template that drops that into JSON-LD publishes the entity literally, so a name reads "Tom’s Bakery".
• Strings glued together by hand. Templates that build JSON by concatenating strings in PHP break the first time a product name contains a double quote, such as a 6" planter, or a description contains a line break.
• Escaping for the wrong context. Running values through esc_attr() or esc_html() turns quotes into ". That is correct for HTML attributes and wrong inside a JSON-LD script, where entities are not decoded.
• Shortcodes and blocks inside values. A description taken from post content can include unrendered shortcodes, block comments such as <!-- wp:paragraph --> or HTML tags. None of those belong in a text value.
• Empty custom fields. Fields from Advanced Custom Fields or similar plugins that have never been filled in can produce empty strings, null or false, giving values such as "price": "" or a date of false.
• Optimisation plugins. Minification, script combining and delayed script loading features are designed for JavaScript. Most leave JSON-LD alone, but if a block breaks only when optimisation is on, exclude application/ld+json scripts from those features.

Tracing a block to its source

WordPress sites rarely label their markup clearly, but there are reliable clues:

1. Class names on the script tag. Yoast SEO's graph has usually been output with a class such as yoast-schema-graph, and Rank Math's with a class containing rank-math-schema. Other plugins often add their own class or an id.
2. HTML comments. Many SEO plugins wrap their head output in comments naming the plugin. The block between those comments belongs to it.
3. Position. Blocks in the head usually come from plugins hooked to wp_head; WooCommerce has output its product data near the end of the page through wp_footer; blocks in the middle of the content come from the post itself or a page builder widget.
4. Query Monitor. This free plugin lists the functions attached to each hook, including wp_head and wp_footer, with the plugin or theme each belongs to. It narrows the search quickly on a busy site.
5. Elimination on staging. On a staging copy, deactivate plugins one at a time and reload the page. When a block disappears, you have its source. Do this on staging, never on the live shop.

Building JSON-LD safely in PHP

Whenever your own code outputs JSON-LD, build a PHP array and let WordPress encode it. wp_json_encode() handles quotes, line breaks and non-ASCII characters correctly, so no product name can break the block. The example below adds a small block to a custom post type called course, and is intended for a site-specific plugin or a child theme's functions.php.

add_action( 'wp_head', function () {
    if ( ! is_singular( 'course' ) ) {
        return;
    }
    $post_id = get_queried_object_id();
    $name    = html_entity_decode( get_the_title( $post_id ), ENT_QUOTES, 'UTF-8' );
    $summary = wp_strip_all_tags( get_the_excerpt( $post_id ) );

    $data = array(
        '@context'    => 'https://schema.org',
        '@type'       => 'Course',
        '@id'         => get_permalink( $post_id ) . '#course',
        'name'        => $name,
        'description' => $summary,
        'provider'    => array( '@id' => home_url( '/#organization' ) ),
    );

    $flags = JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_HEX_TAG;
    echo '<script type="application/ld+json">' . wp_json_encode( $data, $flags ) . '</script>' . PHP_EOL;
} );

Three details matter. html_entity_decode() turns the entities from the title filter back into real characters. wp_strip_all_tags() removes HTML from the excerpt. JSON_HEX_TAG encodes angle brackets, which keeps a stray </script> inside a value from ending the block early; include it whenever you use JSON_UNESCAPED_SLASHES, which otherwise removes that protection. The provider reference assumes your SEO plugin defines the organisation with that identifier, so check the live output and match it exactly.

Changing what the SEO plugin outputs

Most problems with SEO plugin markup should be fixed in the plugin's settings first: the organisation name and logo, whether the site represents a person or an organisation, the default article type, and per-post schema options. When settings are not enough, the major plugins provide filters. Plugin APIs change between versions, so confirm the names against the plugin's current developer documentation before relying on them.

Yoast SEO

Yoast outputs one @graph built from separate pieces. It has offered a filter for each piece, named after it, and one for the whole graph. This adds a property to the Article piece:

add_filter( 'wpseo_schema_article', function ( $data ) {
    if ( is_singular( 'post' ) ) {
        $data['articleSection'] = 'Garden projects';
    }
    return $data;
} );

Yoast has also provided a filter, wpseo_json_ld_output, that turns the whole graph off. Use it only if another tool will supply everything instead, because removing the graph also removes the organisation, website and breadcrumb data other markup may be pointing at.

Rank Math

Rank Math passes its whole schema array through the rank_math/json_ld filter, keyed by entity. Hooking it at a late priority lets you adjust or remove entries after Rank Math has built them:

add_filter( 'rank_math/json_ld', function ( $data, $jsonld ) {
    if ( isset( $data['publisher'] ) && is_array( $data['publisher'] ) ) {
        $data['publisher']['name'] = 'Kestrel Garden Supplies';
    }
    return $data;
}, 99, 2 );

Print the array to a log on staging before changing it, as the keys depend on your settings and the page type. The same principle applies to All in One SEO, SEOPress and others: find the documented filter, change the data it passes, and return it.

The fix, step by step

WooCommerce, block themes and page builders

WooCommerce product data

WooCommerce builds Product structured data from the product's own fields: price, stock status, SKU, reviews and images. It has provided a woocommerce_structured_data_product filter for changing the Product array, which is the right place to add a GTIN or brand held in a custom field. To remove WooCommerce's output entirely because another tool owns products, a commonly used approach is to unhook its output method from the footer:

add_action( 'init', function () {
    if ( function_exists( 'WC' ) && isset( WC()->structured_data ) ) {
        remove_action( 'wp_footer', array( WC()->structured_data, 'output_structured_data' ), 10 );
    }
} );

Test on staging and confirm the Product block has gone and the replacement is present, because removing product markup without a replacement loses product results. If products are variable, check what the markup says for the default variant against what the page shows on first load.

Block themes and the Site Editor

With a block theme, templates live in the Site Editor rather than PHP files. A Custom HTML block placed in a template part, such as the header, appears on every page that uses it. That is a tidy place for a site-wide block, and an easy place to forget one. Check template parts as well as posts when hunting for a stray block.

Page builders

Builders such as Elementor or Divi store content in their own format, and widgets like FAQ, star rating or business details may output markup of their own. If a builder widget produces a type your SEO plugin also outputs, switch off the widget's schema option. Hand-written JSON-LD in a builder's HTML widget is subject to the same user role rules as the block editor.

Keeping WordPress JSON-LD healthy

• Keep custom schema code in one site-specific plugin. It survives theme changes, can be version-controlled, and gives you one place to look.
• Test updates on staging first. SEO plugin and WooCommerce updates occasionally change schema output. Run the JSON Checker on staging after updating and before going live.
• Check new plugins for markup. Reviews, events, recipe and booking plugins often add structured data by default. Look at their settings the day you install them.
• Keep JSON-LD out of the content editor. Hand-written blocks in posts are invisible to anyone reviewing the theme and are easily damaged by role restrictions.

More on reading findings is in the JSON-LD Schema Guide. If your markup comes from an AI generator, see AI schema in WordPress, and for identifier mismatches between plugins, duplicate or missing @id.