Catch the quiet failures at their source
Structured data often fails without taking a page down. An event can reference a performer or venue with @id even though that node was never included in the graph. Search tools surface the symptoms page by page; an audit can name the broken reference and its JSON-LD block.
The plugin checks all JSON-LD blocks in a content document. For known schema.org types, it verifies required properties; it indexes graph node definitions first, then resolves references in a second pass. Invalid JSON-LD is a finding too, not a skipped block.
Known types, concrete requirements
| Type | Required properties |
|---|---|
| MusicEvent | name, startDate, location, performer |
| MusicGroup / Place | name |
| Organization | name, url |
| WebPage / Person | name |
| FAQPage | mainEntity |
| BreadcrumbList | itemListElement |
The map is a representative default, not a claim that every site's schema policy is identical. The engine is deliberately framework-agnostic and returns plain findings so callers choose how to present them.
One engine, three entry points
The same WordPress-free audit engine powers three ways to catch regressions:
- WP-CLI:
wp schema-audit run [--limit=N]audits published content and exits non-zero when it finds errors, so CI or cron can enforce the result. - WordPress admin: Tools → Schema Audit runs on the last 100 published posts and displays post, block, and finding details. The action is nonce-checked and capability-gated.
- CI self-test: real good and broken fixtures assert both directions: valid data stays clean and invalid data is rejected.
$ wp schema-audit run
Success: audited 100 posts, 0 errors.Build confidence in both directions
An auditor that only tests the clean case might be blind; one that only tests broken data might reject everything. The self-test runs both pass and fail fixtures. In CI the PHP files are linted and both expected outcomes are asserted, so a regression makes the build fail instead of merely printing a warning.
The plugin is read-only: it audits and reports, never edits content. The engine has no WordPress calls, making the same logic testable without bootstrapping WordPress or coupling the rules to one interface.
Production engine, representative defaults
The engine is the production logic. The required-property map is a representative default; site-specific rule sets and deployment wiring are not included. The WordPress plugin is the reusable port of the standalone jsonld-schema-audit CLI, which helped take The DJ Calendar from hundreds of Rich Results warnings to zero across roughly a thousand pages.
Frequently asked questions
What does the wp-schema-audit plugin check?
It checks required properties for supported schema.org types, validates internal fragment @id references against definitions in the same graph, and reports malformed JSON-LD blocks.
How can I run the audit?
Use wp schema-audit run with WP-CLI, open Tools → Schema Audit in WordPress admin to check the last 100 published posts, or run the repository's CI self-tests against its good and broken fixtures.
Does the plugin change my content?
No. It is strictly read-only: it audits and reports findings without writing to posts or changing JSON-LD.
Does this replace Google's Rich Results Test?
No. It complements page-level testing by helping identify root causes across a content library, such as a missing referenced node or malformed JSON-LD block.