Marketing · 8 min read · Updated September 28, 2026

Schema.org Structured Data: A Practical Guide to JSON-LD

Structured data has a reputation as an SEO lever you pull to rank higher. It is not one. Schema.org markup does a narrower, more mechanical job: it tells a search engine what kind of thing is on a page, in a format it can parse without guessing, so the engine can decide whether to render something richer than a blue link. Skip it and your page can still rank; you just stay ineligible for the rich result, which is a click-through problem, not a ranking one.

This guide covers what JSON-LD actually is, which schema types are worth adding and which quietly fail validation, a worked example of what a real site marks up and why, and where structured data does and does not belong on a site built around short links and redirects.

What JSON-LD actually is

Schema.org is a shared vocabulary: a set of agreed-upon types (Article, Product, FAQPage) and properties (author, price, datePublished) that describe common kinds of content. JSON-LD is one way of writing that vocabulary into a page: a single <script type="application/ld+json"> block containing a plain JSON object, placed anywhere in the head or body. Google explicitly recommends it over the older alternatives, microdata and RDFa, which require annotating individual HTML elements with itemprop attributes and are far easier to get wrong or leave half-updated after a redesign.

The practical advantage of a script block is that it is separate from your visible markup. You can generate it, template it, or swap it out without touching the HTML a visitor actually sees, and a crawler reads it independently of how the page renders.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Acme Co",
  "url": "https://acme.com",
  "logo": "https://acme.com/logo.png"
}
</script>

What it earns you, and what it does not

Structured data is not a ranking factor Google has ever confirmed using directly. What it does is make a page eligible for a rich result: star ratings under a product listing, an expandable FAQ dropdown, breadcrumb links instead of a raw URL, an event card with a date and venue. Eligible is the operative word. Adding the markup does not guarantee the enhancement appears; Google still decides whether to show it, and can revoke it later if quality guidelines are not met. What it reliably changes is how much space and information your result gets in the search page, which is a click-through-rate lever, not a position lever.

The trap: a type that requires data you do not have

Some rich results have a hard prerequisite baked into Google’s validator, and shipping the type without it does not degrade gracefully, it fails. The clearest example is SoftwareApplication (and its siblings WebApplication, MobileApplication): Google’s Software App result requires either an aggregateRating or a review property, plus offers.price if you are also claiming a price. A tool or app landing page that adds SoftwareApplication markup without real rating data is not "partially" eligible; it fails Rich Results Test validation outright, on every page that emits it.

This is worth checking before you adopt a type, not after: read the required-properties list for the specific type you want, not just the type name. A generator or template that lets you produce the JSON does not check whether you are structurally eligible for the result it targets.

A worked example: what ReSlug marks up, and what it deliberately skips

ReSlug’s own marketing site is a reasonable case study because it hit the SoftwareApplication trap directly. Every free tool page (the QR code generator, the UTM builder, and the rest) is exactly the kind of page people reach for WebApplication markup on, since each one is a small piece of software with its own URL. ReSlug does not add it, on purpose: none of the tool pages carry a genuine rating or review, so aggregateRating would have to be fabricated to pass validation, and a fabricated rating is worse than no markup, both because it is dishonest and because Google’s guidelines treat it as a manual-action risk. An Ahrefs crawl in July 2026 flagged exactly this failure site-wide before the block was removed for good, which is the kind of mistake that is easy to ship quietly and expensive to notice.

What every tool page emits instead is a BreadcrumbList, built from the page’s actual position under /tools/, and an FAQPage block generated from the same question-and-answer content already rendered visibly on the page, never text that only exists in the JSON-LD. Google requires the FAQ content to be visible to the user, not markup-only, and building the JSON-LD from the same data structure the page renders from is the simplest way to guarantee that stays true after an edit.

Guide pages, this one included, follow a template: an Article block with the headline, description and the datePublished/dateModified pair, a BreadcrumbList from Home through Guides to the article, and an FAQPage block whenever the guide has an FAQ section, again generated from the same array that renders the visible questions below. None of the three requires data the page does not already have, which is exactly the property to look for before adding a type: does emitting this markup require fabricating anything, or does it just restate content and metadata that already exists on the page?

Where structured data does not belong

A redirect has nothing of its own to describe. A short link under /r/ returns a 302 and a Location header; there is no rendered page for a crawler to read markup from, and adding a script block to a redirect response is not something a crawler would ever see, since it never gets past the redirect (see 301 vs 302 redirects for what that status code changes). The same logic applies to the robots.txt file rules that block /r/ and /app/ from crawling in the first place: a URL a crawler is not allowed to fetch cannot have its structured data read either, so markup on a disallowed page is inert regardless of how correct it is.

Structured data and Open Graph tags solve different problems and are easy to conflate because both live in <head> as machine-readable metadata. Open Graph controls the card a chat app or social platform builds when someone pastes your link, read by a scraper like Slackbot or facebookexternalhit at share time; see link previews and short links for how that works and why it breaks. Schema.org JSON-LD is read by search engine crawlers at index time and only ever affects how a search result looks, never a shared-link card. A page can have excellent Open Graph tags and no structured data, or the reverse; neither substitutes for the other.

Building JSON-LD without hand-writing it

The markup itself is unforgiving JSON syntax nested several levels deep, and a missing comma or an @type typo produces no visible error on the page, just silent validation failure weeks later. A Schema.org JSON-LD generator that supports the common types (Organization, Article, Product, FAQPage, BreadcrumbList, LocalBusiness, Event) removes the syntax risk: you fill in a form for the type you need, and the generator only lets you produce output that parses, though it cannot know whether you have the prerequisite data a given type actually requires.

• Pick the narrowest type that fits. A blog post is Article, not WebPage; a physical shop is LocalBusiness, not Organization. The generic type validates fine but is not eligible for the specific rich result you actually want.
• Fill every required field before optional ones. BreadcrumbList needs position on every item in order; a Product claiming offers needs price and priceCurrency together, not one without the other.
• Keep the JSON-LD in sync with the visible page. For FAQPage in particular, the questions and answers in the script block must match what a visitor can actually read, not a superset written only for crawlers.

Validating what you shipped

1. Run the live URL through Google’s Rich Results Test. It parses the page the way Googlebot does and reports, per block, whether it is valid, has warnings, or fails outright, and for which specific rich result it qualifies.
2. Check for the exact failure covered above: a type like SoftwareApplication reporting a missing required field (aggregateRating or review) rather than a syntax error. That is a data problem, not a markup problem, and the fix is to drop the type, not to fix the JSON.
3. In Google Search Console, the Enhancements section (or the specific report for FAQ, Breadcrumbs, or Products) shows which pages Google has actually indexed with valid markup, separate from whether the test tool passes on a single URL you checked by hand.
4. Re-check after any redesign that changes the head template or the data feeding it. Structured data has no visual footprint, so a template change that silently drops the script block produces no rendering bug for anyone to notice.