Hand-coded JSON-LD in WordPress: Build a Schema Graph

Date: November 5, 2026Reading time: 6 min readShare:

An SEO plugin outputs a connected entity graph: a WebPage that is part of a WebSite, published by an Organization. Most users see the plugin do its job but never inspect the JSON-LD it writes behind the scenes. Writing manual schema markup by hand is a plugin-free path to creating that exact block without relying on Rank Math or Yoast. This approach does not boost rankings directly; it makes pages eligible for rich results, which can improve click-through rates.

Hand-coded JSON-LD in WordPress: Build a Schema Graph

The JSON-LD block and why schema without plugins makes sense

JSON-LD is a block of JavaScript-style data placed in the page head or body, separate from the visible HTML. This is the format Google explicitly recommends over Microdata or RDFa for adding structured data to web pages. When you look under the hood of a typical SEO plugin, the output is essentially a connected entity graph: a WebPage that is part of a WebSite published by an Organization. The gap for many site owners is that they see the plugin do its job but never see the actual JSON-LD it writes to the code.

Understanding the function of this markup is critical. Schema does not act as a direct ranking boost; instead, it makes pages eligible for enhanced displays in search results, such as star ratings or product prices. These rich results can improve click-through rates, but content quality, relevance, and backlinks remain the primary drivers of rankings. A plugin like Rank Math or Yoast SEO auto-generates this JSON-LD for basic needs, often including a schema builder for specific types like Service or FAQ on individual pages.

Choosing the hand-coded path allows you to replicate exactly what those plugins generate, but with full control over what ships. By writing the manual schema markup yourself, you eliminate dependency on third-party software. This approach ensures that the structured data is precise, tailored to your specific entity structure, and free from the potential conflicts that arise when multiple tools attempt to manage the same codebase.

Building the connected graph with manual schema markup

The core structure an SEO plugin outputs is a connected entity graph: a WebPage that is part of a WebSite, which is published by an Organization. When you write this by hand, you are not creating a new format—you are replicating the exact same linked structure, just with full control over the values.

Core entity types and placement

For a standard business site, the graph relies on a few specific types, each tied to a distinct location:

  • Organization or LocalBusiness: Place this on the homepage. If you have a physical location, LocalBusiness is more precise and supports fields like address, phone, and opening hours.
  • Article or BlogPosting: Use these on individual blog posts to define the author, date, and headline.
  • Product: Apply this to product pages to surface pricing and availability in search.
  • BreadcrumbList: Implement this site-wide to clearly define the navigation path for every page.

A worked example for a single page

To connect a specific page to your site’s main entity, you need a snippet that links the page to the organization. Here is a concise structure for a service page:

{
  "@context": "https://schema.org",
  "@type": "Service",
  "@id": "https://example.com/services/cleaning",
  "name": "Commercial Cleaning",
  "provider": {
    "@type": "Organization",
    "@id": "https://example.com#organization"
  },
  "url": "https://example.com/services/cleaning"
}

The @id in the provider object references the main organization block on your homepage. This single link tells search engines that this specific service is offered by the entity defined at the root of your site, creating a verifiable relationship rather than a disconnected data point. This approach allows you to hand code schema with precision, ensuring every entity in your WordPress structured data graph is explicitly linked.

Embedding add JSON-LD WordPress blocks by hand

When you choose to hand code schema, the implementation location determines how effectively the structured data works. To add JSON-LD WordPress blocks that load per template rather than once site-wide, place the code directly into your theme’s specific template files. For instance, inject the Organization block into the header.php file, or better yet, create a custom child-theme file like single.php to output Article data only on post pages. This approach ensures the markup is context-aware and prevents a single, static block from applying incorrectly to every page on your domain.

The matching-content rule

The most critical risk in this manual schema markup process is a mismatch between your code and the visible page content. Search engines expect the structured data to accurately describe what is present on the page. If your JSON-LD block claims a specific product is in stock or lists an author who isn’t actually on the page, you are violating the matching-content rule. This discrepancy is not a minor error; it can trigger a manual action that harms your site’s visibility. Because you are bypassing the safety checks of an automated tool, you must personally verify that every data point in your block reflects the visible reality of the template it is embedded in.

Avoiding conflicting blocks

A common pitfall when implementing WordPress structured data without a plugin is accidental duplication. Many themes, page builders, and other plugins already output their own schema blocks. If your hand-coded block conflicts with existing data—such as two different Organization blocks with varying names or addresses—it confuses search engines. Rather than layering multiple disconnected snippets, aim for one clean, connected graph. Before you add your custom code, inspect the page source to see if your theme is already emitting data. If it is, you should either override that existing output or adjust your manual implementation to complement it, ensuring a single, consistent source of truth for your structured data.

Validate your hand code schema before you ship

Before publishing, run your hand-coded JSON-LD through Google’s Rich Results Test to confirm which features your page qualifies for and to catch syntax errors. For broader schema.org validity, the Schema Markup Validator is a useful secondary check. Since template-level errors propagate to every matching page, test each distinct layout—homepage, post, product, and location page—rather than assuming a single URL covers all cases. One note on reality: Google restricted FAQ and HowTo rich results in 2023, so while that markup remains technically valid, it will not add visual enhancements for most business sites.

Questions about hand coding schema in WordPress

Does schema boost rankings?

No, it does not. Schema is not a direct ranking factor. Instead, it makes pages eligible for enhanced displays, which can improve click-through rates by making your listing more informative in the search results.

Is a plugin necessary?

Usually, no. The hand-coded path covers the core connected graph needed for most business sites. Specialist tools become useful only in complex cases where you need to manage dynamic data at scale.

Can markup cause penalties?

Yes, if it is misleading. Misleading or spammy markup that describes content not present on the page can trigger a manual action. Keep your structured data accurate and consistent with visible content to avoid this risk.

The plugin-free path trades a bit of upfront setup for full control over what markup ships. The real cost of skipping a tool is often duplicate or conflicting blocks when other themes or plugins also emit schema. Before you start writing hand-coded JSON-LD, take a quick look at your current theme’s source. Is it already outputting hidden structured data?

AEO/GEO

Win visibility in AI-generated answers

Create, optimize, host and distribute AI-ready content at scale with AEO/GEO.

Explore the platform

Show up in AI answers

Explore our service

See how it works