Schema Markup Without a Plugin: Hand-Rolled JSON-LD That Validates
You don’t need another WordPress plugin to ship useful structured data. Write JSON-LD, validate it, and keep it honest.
Part of the AI Search Visibility series. Start here: Technical SEO checklist for business sites.
Plugin marketplaces make structured data look like a toggle. Then you get five overlapping graphs, outdated priceCurrency fields, and a Rich Results report full of warnings. Hand-rolling JSON-LD sounds old-fashioned. For many marketing sites it’s still the cleanest path.
Pick types you can defend
Only mark up what’s true on the page. Common, useful types:
Organization/WebSiteon the homepage.ArticleorBlogPostingon editorial URLs.FAQPagewhen the FAQs are visible to users - not hidden for bots.BreadcrumbListmatching the visible breadcrumb.SoftwareApplicationonly if you’re actually describing software.
Skip fantasy reviews and fake aggregate ratings. Short-term rich result greed becomes long-term trust debt.
Build the JSON without ceremony
- Draft with Schema Generator or write a minimal object by hand.
- Pretty-print and sanity-check braces in JSON Formatter.
- Run JSON Validator so you’re not debugging commas in production.
- Embed in a
<script type="application/ld+json">block in the HTML head or end of body. - Validate with Google’s rich results test (or equivalent) against the staging URL.
Keep markup in sync with the page
When the headline changes, update headline. When you remove an FAQ, remove the node. Generated-at-build-time from the same source as the page content is ideal. Duplicated manual fields drift.
This fits the broader hygiene in technical SEO checklists and the answer-ready mindset from SEO vs GEO vs AEO.
The plugin trap
Plugins help when non-developers must edit fields safely. They hurt when they inject every possible type “just in case.” If you keep a plugin, disable modules you don’t use and export the JSON once to see what it actually emits.
Patterns worth copying (then adapting)
Article pages: include headline, datePublished, dateModified, author, image, and mainEntityOfPage. FAQ pages: mirror visible questions exactly - paraphrasing in JSON-LD while showing different text on the page is how you earn manual actions.
Software tool pages: if you use SoftwareApplication, be honest about pricing and platforms. Empty or misleading offers are worse than no offers.
Add a CI check
Even a simple JSON parse of extracted ld+json blocks in CI catches broken deploys. Pair with periodic rich-result crawls on staging. Schema that’s invalid silently doesn’t help your technical SEO goals.
International pages
Translated pages need translated schema where text fields appear. Don’t ship English JSON-LD on a Spanish article. Align inLanguage with the page. Hreflang remains separate - schema doesn’t replace it.
Field notes from teams who shipped this
The pattern that keeps showing up: write the constraint first, then the steps, then the failure modes. Teams that only publish happy-path screenshots create tickets. Teams that document the ugly path create trust.
Schedule a short review ninety days after publishing. Check whether product UI names still match, whether linked tools still exist, and whether support still hears the same questions. Update the page or merge it. Standing still is how useful posts become interchangeable again.
If you adapt this article for internal wikis, keep the examples tied to your stack names. The moment you generalize back to “best practices for organizations,” you’ve started erasing the specificity that made the piece worth saving.
How much schema is enough
One accurate Organization block and clean Article markup beat a kitchen-sink graph of twenty types. Each type you add is a promise to maintain. Start from the page’s primary purpose.
For tool sites, FAQ schema on genuine FAQs can help, but only when the questions appear as visible text. Stuffing FAQs into JSON-LD alone is the old spam pattern - don’t revive it.
Revisit schema when you redesign templates. Broken selectors in a plugin are one failure mode; hand-rolled JSON-LD that still mentions retired authors is another. Ownership fixes both.
If legal changes brand naming, update Organization schema the same week you update the footer. Entities like consistent names.
Monitor rich results
Search Console rich result reports lag, but they catch template bugs after deploys. Assign someone to glance weekly after launches. A sudden FAQ drop often means the visible FAQ component vanished while JSON-LD remained - or the reverse.
Fix within the sprint when possible; schema debt compounds like everything else.
Author and organization consistency
Use the same Organization @id across pages so entities connect. Authors should match bylines. If you publish under a team name, say so consistently rather than mixing fictional personal authors.
For blog clusters, Article markup plus breadcrumbs that match visible navigation reinforces the topical structure you already built for humans. Schema should describe the page you shipped - not the page you wish you had.
When you retire a post, remove or update its schema in the same change as the redirect. Orphan structured data is a small mess that confuses crawlers and your future self.
Validate one URL from each template type after every redesign: home, article, tool, docs. Template-level bugs affect hundreds of URLs at once.
FAQ
Multiple JSON-LD blocks or one graph?
Either works. One @graph is tidy; multiple scripts are fine if they don’t contradict each other.
Does schema guarantee rankings?
No. It can enable richer display and clearer entity understanding. Substance still has to be there.