The reason most content sites have incomplete schema isn’t that nobody knows schema exists. It’s that when someone finally sits down to look at the format Google recommends — JSON-LD — they see something that resembles a developer’s to-do list and decide they’ll come back to it later.
Thank you for reading this post, don’t forget to subscribe!Later never comes.
I want to fix that. Not by pretending JSON-LD is simpler than it is, but by explaining what it actually does, why it looks the way it does, and how to read it so that the fear of it stops being a reason to skip the thing entirely.
What JSON-LD is, before we go any further
JSON-LD stands for JavaScript Object Notation for Linked Data. The “linked data” part is what matters: it’s a format for expressing relationships between things. This entity is a Person. This Person is the author of this Article. This Article was published by this Organization. The format connects things that belong together so a machine can understand them without inferring anything from surrounding text.
The “JavaScript Object Notation” part just describes how the information is formatted — using curly braces, quotes, colons, and commas. You’ve been reading JSON-LD every time you’ve seen a Google Knowledge Panel populate with accurate information. You’ve been producing it every time a plugin adds structured data to your site without telling you. The only new thing here is reading it with intention.
Why JSON-LD specifically
Google supports three formats for structured data: JSON-LD, Microdata, and RDFa. All three work. Google recommends JSON-LD. The recommendation is correct, and here’s the architectural reason why.
Microdata and RDFa require you to weave structured data directly into your HTML — wrapping individual elements with attributes, tagging specific visible words and phrases. If your page layout changes, your schema breaks. If a content manager updates copy, they can accidentally break structured data they didn’t know was there. Every change to the page touches the schema.
JSON-LD lives in a separate <script> block, typically in the <head> of your page. It doesn’t touch your visible HTML. It sits beside your content, describes it, and does its job without getting tangled up in how the page looks or what’s in it visually. You can update your content without touching the schema. You can update the schema without touching the content.
This is the cleaner architecture. Cleaner architecture produces fewer mistakes. And in schema, mistakes don’t just fail silently — they produce invalid markup that earns you nothing.
What JSON-LD looks like
Here is Article schema written in JSON-LD. Read this top to bottom:
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "You've Been Avoiding JSON-LD. Here's Why That Needs to Stop.",
"author": {
"@type": "Person",
"name": "Jacob Clifton",
"url": "https://cliftoncreative.agency"
},
"datePublished": "2026-04-01",
"dateModified": "2026-04-01",
"publisher": {
"@type": "Organization",
"name": "Clifton Creative",
"url": "https://cliftoncreative.agency"
}
}
From top to bottom:
@context tells the machine which vocabulary we’re using. It’s always https://schema.org. You don’t need to think about this line — it’s always the same.
@type tells it what kind of thing this page describes. In this case, an Article.
Everything else is a property of that type. The headline, who wrote it, when it was published, who published it.
The author block is where JSON-LD starts showing its value. The author isn’t just a name — it’s itself an object, a Person entity, with its own properties. This is linked data: the Article is authored by a Person who has a URL and a name. That’s a relationship, not just a label.
Three things that trip people up
Confusing what’s required with what’s possible.
Schema.org lists dozens of properties for most types. You don’t need most of them. For Article schema, Google publishes which properties are required for rich results and which are recommended. Start with required. Add recommended. Ignore the rest until you have a specific use case for them. Completism is not the goal. Coverage is.
Describing content that isn’t actually on the page.
The JSON-LD must match your visible content. If you include a 4.8-star rating in your structured data and there’s no visible rating on the page, Google will ignore it at best and flag it at worst. The machine-readable layer describes the human-readable layer — it doesn’t supplement it with information that isn’t there for people to see. This is the rule that trips up most implementation errors.
Not knowing where the script block lands.
JSON-LD goes in a <script type="application/ld+json"> block, typically in the <head>. In WordPress, your SEO plugin handles this automatically when properly configured. If you’re adding it manually — through a theme function, a custom code plugin, or a header injection tool — confirm it’s actually landing in the markup by using your browser’s View Source function or a browser inspector. A schema block that doesn’t render is the same as no schema block.
Validating what you write
Before any post with new or updated schema goes live, run it through Google’s Rich Results Test. Paste in a URL or paste in the raw JSON-LD. It will tell you whether Google can parse the markup, whether you qualify for any rich result types, and what errors are present.
This is not optional. It takes thirty seconds. If you are writing about schema for a living and publishing posts that haven’t passed the Rich Results Test, you have a credibility problem. The whole point of the practice-what-you-preach standard is that the schema on this post should be validated before it goes live.
Do not skip this step.
Where WordPress fits in
If you’re running Yoast SEO, Article schema is added to posts automatically once the Organization settings are filled in. What Yoast generates for Article is a floor, not a ceiling — it covers the required properties but may not include recommended ones like image, articleSection, or mainEntityOfPage, depending on your configuration.
Rank Math gives you more granular control and lets you customize schema type per post. Schema Pro is built specifically for structured data management and is worth considering if schema is a deliberate part of your content strategy rather than a background task.
Regardless of which plugin you use: open the settings and fill in everything completely. The Organization name, logo, URL, social profiles. The author name and URL. Default to nothing blank. A plugin that outputs incomplete schema because nobody configured the organization fields is producing markup that validates but doesn’t contribute to your entity graph in any meaningful way.
What to do next
Configure your SEO plugin’s organization and author settings completely. Validate your homepage and at least one post using the Rich Results Test. Fix any errors before publishing anything new.
Then, once Article schema is solid and validated: move into the types that actually earn visible rich results — FAQPage for posts with Q&A content, HowTo for genuinely instructional content, BreadcrumbList for site-wide navigation. Those are where the SERP differentiation comes from. JSON-LD is the format that implements all of them.
Now you know how to read it. JSON-LD is the format; getting to scheming is the move.
I write about content strategy, fractional editorial leadership, and the professional reality of this kind of work.
For inquiries: jacob@cliftoncreative.agency · cal.com/cliftoncreative