Schema Health: Fix Structured Data Issues in the Editor

SEOvault AI includes a Schema Health panel in the post editor that validates your structured data locally and helps you identify and fix issues before the page goes live. The panel shows the status of published schema, unfinished setup items, and provides actionable guidance.

Where to find Schema Health

Open any post or page in the WordPress editor. The Schema Health panel appears in the sidebar (usually under SEOvault AI meta box). The panel shows:

Status indicator – Healthy, Improvements available, Action required, or No schema detected
Emitted entities – summary of schema types that will be output
Unfinished setup – list of schema instances that need completion
Action buttons – Check schema, Check published page, Add schema, Review schema

How validation works

Schema Health runs two types of validation:

Local validation

Local validation checks the schema graph that SEOvault AI will output on the frontend. It uses bundled rules based on Schema.org vocabulary and Google Rich Result guidelines. Validation runs:

On post save – after the post meta is saved, the emitted graph is validated and cached
On demand – click “Check schema” to re-run validation with the current editor state
In the editor – as you type in the custom JSON field, the editor previews the graph that would be emitted

Local validation does not guarantee a Google rich result, but it catches common structural issues, missing required fields, and syntax errors.

Published-page validation

Published-page validation fetches the live page HTML and compares the actual JSON-LD output to SEOvault’s expected graph. This helps detect:

Conflicts with other plugins or theme code
Caching issues that prevent schema updates
Missing entities that should be present
Extra entities from third-party markup

Published-page validation is only available after the post is published and the page is publicly accessible.

Status states

The Schema Health panel shows one of the following states:

Healthy (✓) – No errors or warnings found. The emitted graph passes local validation rules.
Improvements available (●) – Recommendations are available to enhance schema (for example, adding an image to Article markup). These are optional but can improve rich result eligibility.
Action required (×) – Errors or warnings need attention before the schema can be trusted. These issues may prevent the schema from being useful to search engines.
No schema detected (—) – Schema output is disabled globally or no schema is configured for this page.
Check unavailable (!) – SEOvault could not complete the local check. This is not a schema validation result; try again.

Unfinished setup items

The panel lists schema instances that are not ready for output. These include:

Guided schema instances

Schema instances added via the guided form may be withheld if required fields are missing. Common reasons:

Missing image – Article, Event, Product, and Recipe types require an image
Missing author – Article and Recipe types require an author
Missing dates – Event and JobPosting require start date or date posted
Missing location – Event and JobPosting require a location or remote designation
Incomplete FAQ block – FAQ blocks need at least one complete question and answer pair
Incomplete How-to block – How-to blocks need a name and at least one complete step

Each setup item shows:

Schema type
Status badge (Draft, Needs information, Withheld)
Summary of what’s missing
Complete button (focuses the required field)
Remove button (deletes the instance)

Custom JSON

If you paste custom JSON-LD in the editor field, it is validated for syntax and structure. Issues include:

Invalid JSON syntax – the JSON cannot be parsed
Input too large – the custom JSON exceeds size limits
Invalid structure – the JSON does not match expected schema.org patterns

Invalid custom JSON is withheld from the published graph and does not suppress foundational schema output.

Step-by-step: fix schema issues

Open the post in the editor.
Look at the Schema Health panel status.
If the status is Action required or Improvements available:
- Review the top actions listed in the panel.
- Click “Review schema” to see detailed issue cards grouped by severity.
For unfinished setup items:
- Click “Complete” on an item to focus the required field.
- Fill in the missing information.
- The status updates automatically as you complete fields.
For custom JSON issues:
- Click “Complete” to focus the custom JSON field.
- Fix syntax errors or reduce the size.
- The panel previews the validated graph.
Click “Check schema” to re-run validation after making changes.
Save or update the post to persist changes.
After publishing, click “Check published page” to verify live output.

Caching behavior

Local validation results are cached for up to 7 days. The cache is invalidated when:

The post is saved
Schema settings change
Plugin version updates
Schema validation ruleset updates
The custom JSON field changes

Clicking “Check schema” bypasses the cache and runs fresh validation.

Notes and edge cases

Bundled rules only: Schema Health uses SEOvault’s bundled local rules. Passing validation does not guarantee a Google rich result. Always test with Google’s Rich Results Test.
Post type support: Schema Health is available for all public post types (posts, pages, and custom post types).
Autopilot mode only: Schema output and validation only work when the plugin is in Autopilot output mode.
Custom JSON mode: After migration, invalid custom JSON is withheld but does not block foundational schema. The editor preview shows the generated graph while the custom JSON is invalid.
Block-derived schema: FAQ and HowTo blocks are validated separately. Incomplete blocks are listed in the unfinished setup section.
Multiple entities: The emitted graph can contain multiple entities of the same type. Each entity must have a unique @id.
Conflict detection: If multiple sources define the same @id, the conflict is reported in the Review schema surface.