You open a page's source code and spot a block like <script type="application/ld+json">
sitting in the head, full of curly braces and an @context field you've never
seen before. It looks like something only a developer could have written, so you close the
tab and move on.
That reaction skips past something simpler than it looks. JSON-LD isn't a programming language and it doesn't run any logic. It's a plain, structured way of writing facts about a page — its title, its author, its price — so a search engine can read them without guessing.
JSON-LD (JavaScript Object Notation for Linked Data) is a format for writing structured data as a self-contained block of key-value pairs, placed inside a script tag on a page. It describes what the page is about — its type, title, author, price, or FAQs — in a way search engines can parse directly, without needing to touch the visible HTML at all.
What is JSON-LD?
JSON-LD stands for JavaScript Object Notation for Linked Data. It borrows JSON's simple syntax of curly braces and key-value pairs, and adds a few special properties that let it describe entities from a shared vocabulary, most commonly schema.org.
- It lives inside a script tag. A JSON-LD block sits in
<script type="application/ld+json">, which browsers don't render, so it never appears visually on the page. - @context sets the vocabulary. Almost every block starts with
"@context": "https://schema.org", which tells the parser which dictionary of types and properties to use. - @type names the entity. A value like
"Article","Product", or"FAQPage"tells the search engine what kind of thing is being described. - The rest is plain properties. Everything after that is ordinary fields —
"name","author","price"— filled in the same way you'd fill in a form.
Strip away the unfamiliar punctuation and a JSON-LD block reads like a short, structured fact sheet about the page it sits on — nothing more exotic than that.
Why JSON-LD matters
Search engines can often infer what a page is about from its visible text, but inference is guesswork. JSON-LD replaces the guessing with a direct statement:
- It's the format Google recommends. Google has stated a preference for JSON-LD over the older microdata and RDFa formats for structured data.
- It's decoupled from the visible page. Because the block sits separately from the content it describes, a redesign or a copy change is far less likely to accidentally break it.
- It unlocks rich results. Correctly written JSON-LD is what makes a page eligible for star ratings, FAQ dropdowns, and other enhanced search listings.
- It's easy to generate and validate. Because the format is so structured, tools can build it from a form and check it automatically, with little room for ambiguity.
Step-by-step: reading a JSON-LD block
-
Find the script tag. Look for
<script type="application/ld+json">in a page's source code, usually in the head. - Check the @context. This first field confirms which vocabulary the rest of the block is written against, almost always schema.org.
- Identify the @type. This is the single most important field — it names the kind of thing being described, like Article, Product, or Organization.
- Read the properties as plain facts. Each remaining key is a property of that type — a headline, an author, a price — matched to a value.
- Look for nested objects. A property's value can itself be a small JSON-LD object, like an author with its own @type and name, describing a related entity.
- Confirm it matches the visible page. Every fact in the block should correspond to something a visitor can actually see or verify on the page.
- Validate it. Run the page through Google's Rich Results Test to confirm the block parses correctly and check which rich result it qualifies for.
Common mistakes with JSON-LD
1. Mismatched or conflicting @type values
Using more than one @type in the same block without understanding how they combine, or picking a type that doesn't match the page's actual content, produces markup that's technically valid but semantically wrong.
2. Missing required properties
Each schema.org type has properties Google treats as required for a given rich result. A block missing one of these, like an image on a Recipe type, may fail validation or simply not qualify for the enhanced listing.
3. Data that isn't visible on the page
Filling in a rating, price, or availability value that a visitor can't actually see or verify on the page violates structured data guidelines, regardless of whether the JSON-LD syntax itself is correct.
4. Multiple conflicting blocks on one page
Adding several JSON-LD scripts that describe the same entity differently, often from a plugin and a manual addition stacking on top of each other, can confuse parsers about which version to trust.
Real-world examples
How the same JSON-LD structure adapts to describe very different kinds of pages:
In every case, the shape of the block stays the same — @context, @type, then a set of properties — only the values and the type name change.
JSON-LD vs. other structured data formats
JSON-LD isn't the only way to write structured data. Here's how it compares to the two older formats schema.org also supports.
| Format | Where it lives | Ease of maintenance | Best for |
|---|---|---|---|
| JSON-LD | Separate script block | High, decoupled from HTML | Nearly all modern sites, Google's preferred format |
| Microdata | Inline within visible tags | Low, breaks with layout changes | Legacy sites already using it extensively |
| RDFa | Inline via HTML attributes | Low, verbose to maintain | Sites with existing RDFa-based content pipelines |
| Plain meta tags | Head section | High but limited scope | Basic social sharing, not full schema coverage |
Generate valid JSON-LD right now — free
Now that the format makes sense, you don't need to write it by hand. The Rebrixe Schema Generator builds clean, validated JSON-LD for the most common types — Article, Product, FAQPage, Recipe, and more. No account, no watermark, just a ready-to-paste snippet.