Writing JSON-LD structured data by hand, and when to stop

CleverUtils — Fri, 26 Jun 2026 08:51:02 +0000

I maintain a handful of small marketing sites, and for years my structured-data workflow was embarrassing: copy a JSON-LD block from an old project, find-and-replace the values, paste it into the <head>, and hope. It worked until it didn't — a trailing comma here, a wrong @type there, and the rich result silently disappears for a month before anyone notices.

Structured data is one of those things that's easy to add and genuinely hard to add correctly. These are the notes I wish someone had handed me earlier.

What JSON-LD actually is

JSON-LD is just a <script type="application/ld+json"> block that describes your page in a vocabulary search engines understand (schema.org). It doesn't change what a human sees; it changes what a machine is allowed to say about your page — the star ratings, the FAQ accordions, the breadcrumb trails that show up in results.

A minimal Article block is unintimidating:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Writing JSON-LD by hand",
  "datePublished": "2026-06-26",
  "author": { "@type": "Person", "name": "Jane Dev" }
}

The trouble starts when you have five page types, each needing a slightly different shape, and you're maintaining all of them by hand across a dozen templates.

The three mistakes I kept making

1. Invalid JSON. A trailing comma after the last property, a smart-quote that snuck in from a CMS, an unescaped quote inside a string. The block looks fine to a human and is invisible garbage to a parser. Worst of all, nothing errors — the page just renders without the markup.

2. Schema that disagrees with the page. If your markup claims a Product has a 4.8 rating but there's no visible review anywhere on the page, you're not getting a rich result — you're risking a manual action. Markup has to describe what's actually on the page, not what you wish were on it.

3. Invented properties. @type: "Article" does not have a readingTime field no matter how much you want it to. Made-up properties are silently ignored, which means you think you shipped something you didn't.

How I work now

Two changes fixed most of it.

First, I stopped writing the JSON by hand for new page types. I reach for a JSON-LD generator that knows the required-versus-recommended fields per type when I need a clean block for a type I don't add often, because it won't let me forget a required property or typo an @type.

Second, I validate in two passes, because "valid JSON" and "valid schema" are different questions. For the first, any browser-based JSON formatter flags a stray comma or bad nesting in a second. For the second, Google's Rich Results Test tells you whether the block is actually eligible for a rich result, which is the only thing that matters in the end.

A workflow that survives contact with reality

Here's the checklist I actually follow now, in order:

Generate or hand-write the block for the page type.
Paste it through a JSON validator — catch the syntax errors first, they're the cheap ones.
Run it through the Rich Results Test against the live (or staged) URL.
Eyeball that every claim in the markup is visibly true on the page.
Only then ship it.

It sounds like a lot. It takes about ninety seconds once it's a habit, and it has saved me from shipping broken markup more times than I'd like to admit.

When NOT to bother

Structured data isn't free — it's another thing you have to keep in sync with the page. If your content changes often and your markup doesn't, you'll drift into the second mistake above, and wrong schema is worse than no schema. For a brochure page that never changes, mark it up once and forget it. For a fast-moving page nobody will maintain, sometimes the honest call is to skip it.