JSON-LD

JSON-LD is the format most structured data is written in. The letters stand for JavaScript Object Notation for Linked Data. In practice it is a block of code that sits in your page, invisible to visitors, telling search engines what the page is: a business, a product, an article, a recipe, an event.

In short

• It is a format for structured data, not a different thing from it.
• It sits in its own block, separate from the visible content.
• Google recommends it over the older Microdata and RDFa.
• It must describe what is actually on the page, or it is a liability.

What separation buys you

The older formats, Microdata and RDFa, work by wrapping attributes around the visible text. The price of a product is marked up by adding code to the element that displays the price. It works, and it breaks constantly, because the markup and the content are the same object. Somebody restyles a page, an editor pastes a paragraph in from a document, a theme update rewrites the template, and the markup goes with it. Nothing looks wrong, so nobody notices for months.

JSON-LD moves the description into its own block. The visible page and the machine readable description are now two separate things that can be generated, tested and changed independently. That is the whole argument, and it is why Google names it as the preferred format.

The cost of the separation is the obvious one. Two things that are supposed to agree can now disagree, and only one of them is on screen.

What it is used to describe

The vocabulary is shared and comes from schema.org, so the same types are understood across search engines. A small business site typically uses a handful.

• Organization or LocalBusiness. Who you are, where you are, how to contact you. This is the one that ties a website to a Google Business Profile.
• Product. What is being sold, and whether it is in stock.
• Article or BlogPosting. What a piece of writing is, who wrote it, when.
• BreadcrumbList. Where the page sits in the structure of the site.
• FAQPage. Questions and answers that appear on the page.
• Service. What you do, for whom, in which area.

Types can be nested and connected, which is where the linked data part of the name comes from. An Article can reference the Organization that published it, and the Organization can reference the profile pages that belong to it, so the pieces describe one entity rather than a collection of unrelated pages.

The rule that breaks most implementations

The markup has to describe what is genuinely on the page.

This sounds obvious and is violated constantly, usually with good intentions. A plugin offers a field for a star rating, somebody fills it in, and the page now claims reviews that do not exist anywhere on it. A template adds price markup to every product regardless of whether a price is shown. An FAQ block is marked up with questions that were never published.

The consequence is not a small correction. Markup that misrepresents a page makes it ineligible for enhanced results, and a site doing it across every page loses the enhancement everywhere at once. The safe test is simple: if a visitor cannot see the thing, do not describe it.

Where it comes from on a real website

Almost nobody writes this by hand for every page. On a typical site it arrives from one of four places.

• The platform. Many systems output basic markup with no configuration at all.
• A plugin or module. The usual source on WordPress, driven by fields filled in inside the editor.
• The page template. Common on custom built sites, where the markup is generated from the same data that renders the page.
• A tag manager. Inserted after the page loads. Workable, and the most fragile of the four.

The failure that follows from having four possible sources is duplication. A theme adds Organization markup, a plugin adds it again, and the page now describes the same business twice with two slightly different sets of details. Search engines cope, but the page is no longer making one clear statement, which was the point of adding markup in the first place.

What it changes in the results

Markup does not move a page up the list. What it does is make a page eligible for a different kind of listing, and eligibility is not a promise.

A product page with valid markup may show a price and a stock status under the link. An article may show a date and an author. A business may appear with review stars, opening hours or a contact number. Search engines decide when to use any of it, and the same page can show an enhanced listing one week and a plain one the next without anything on the page having changed.

The second effect is less visible and more durable. Markup removes ambiguity about what a page is. A page about a service in a city is otherwise a wall of text that has to be interpreted, and interpretation is where a page about plumbing in Cebu gets confused with a page about Cebu. Describing the thing plainly is worth doing for that reason alone, before any question of enhanced listings comes up.

Words you will hear

• schema.org. The shared vocabulary of types and properties. JSON-LD is how you write it; schema.org is what you are allowed to say.
• Type. What the thing is, for example LocalBusiness or Product.
• Property. A detail about it, for example address or price.
• Rich result. The enhanced search listing that valid markup can make a page eligible for.
• Validation. Checking that the markup parses and uses the vocabulary correctly, which is a separate question from whether it is true.

Validation is the distinction worth keeping. A block of JSON-LD can be perfectly formed, pass every test, and still describe a page that does not exist. The tools check the grammar. Whether the description is honest is a question only somebody looking at the page can answer, and it is the question that decides whether the markup helps you or quietly works against you in technical SEO terms.