JSON-LD Structured Data

Your product page shows a name, a price, five stars, and twelve reviews to humans. To a search engine's parser it is an undifferentiated soup of divs — the price is just text that happens to sit near the name. JSON-LD fixes the ambiguity by shipping a machine-readable description of the page's entities alongside the markup, in a script block that any HTML-only crawler can read:

// app/product/[slug]/page.tsx
import type { Metadata } from "next";
import { getProduct } from "@/lib/products";

export default async function ProductPage(props: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await props.params;
  const product = await getProduct(slug);

  const jsonLd = {
    "@context": "https://schema.org",
    "@type": "Product",
    name: product.name,
    image: product.images,
    description: product.blurb,
    sku: product.sku,
    brand: { "@type": "Brand", name: product.brand },
    aggregateRating: {
      "@type": "AggregateRating",
      ratingValue: product.rating,
      reviewCount: product.reviewCount,
    },
    offers: {
      "@type": "Offer",
      price: product.price,
      priceCurrency: "USD",
      availability: "https://schema.org/InStock",
    },
  };

  return (
    <main>
      <ProductView product={product} />
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c'),
        }}
      />
    </main>
  );
}

Three details in that file are load-bearing. @context: "https://schema.org" declares the vocabulary; @type names the entity type, and every property you set must be one schema.org defines for that type — invent ratingStars and the parser ignores it. The payload is emitted by a Server Component, so it is in the initial HTML: crawlers and validators that fetch raw HTML see it with no JavaScript, the same guarantee that carries the Metadata API's tags. And the .replace(/</g, "\u003c") is not decoration — a </script> sequence inside the JSON (plausible once descriptions accept user input) closes the tag early and breaks the document; escaping every < as the JSON-compatible \u003c neutralizes it while staying valid JSON.

Why a separate script block instead of microdata attributes scattered through the DOM? JSON-LD is decoupled from presentation: the same data object can be built from the page's fetched record and rendered once, while the visible UI uses the same record independently. The two representations share a source of truth without sharing markup — which is exactly the property that keeps you out of the mismatch trap in the second chapter. It is also the format Google documents as preferred, and the one every validator accepts.

Where the object comes from is a design decision with a right answer: derive it from the same query the page renders from, like the cache()-shared accessor of Dynamic generateMetadata — one read, two consumers, no drift. A hand-built JSON object maintained next to a component that renders different fields is how price: 29.99 in the payload survives a UI change to $34.99, and every downstream consumer (rich results, internal tools parsing your structured data, future features) inherits the lie.

A structural note for app architecture: JSON-LD belongs at the page level, once per entity type — the same way you would not ship two <title> tags. A page describing a product and a review and a breadcrumb trail emits an array of nodes ([product, breadcrumbs]) or nested hasPart references rather than three competing top-level scripts. Breadcrumbs earn their own treatment: a BreadcrumbList mirroring the visible trail is the structured-data twin of the URL hierarchy crawlers already infer from your paths.

The reason to bother: valid structured data can earn a page a rich result — the enhanced search listing with star ratings, price ranges, faq accordions, breadcrumbs, recipe times — and those listings measurably change click-through. Structured data is not a ranking factor; it is a rendering factor that decides how an eligible result displays. The type set that pays off for most product/content sites:

The enforcement model is the part to understand coldly. Google does not reject invalid markup with an error you can see — it ignores what it cannot parse and penalizes what it considers spammy: markup for content that is not visible on the page, ratings you did not collect, prices that differ from the visible product. The ladder is silent degradation first (markup ignored, rich result never appears), then manual actions for organized abuse (markup-for-rewards programs, faq spam at scale). That is why the third chapter's single-source-of-truth rule is an integrity rule, not a style preference: the parser cross-checks the payload against the rendered page, and divergence is the failure mode with teeth.

Validation is a two-tool ritual. Google's Rich Results Test checks eligibility for enhanced display for a given URL or snippet; the Schema.org validator checks semantic validity against the vocabulary. Run both on a staging URL before shipping — the first names missing required properties for specific rich result types ("offers.price or offers.highPrice is required"), the second catches type errors the eligibility test tolerates. Neither is optional ceremony: the cheapest debugging for structured data happens before deploy, because post-deploy there is no error log — just absent rich results you will notice weeks later in traffic analytics.

An honest framing for interviews and for planning: rich results are granted, revoked, and reshaped by platforms on their own schedule — FAQPage visibility was sharply narrowed, HowTo is deprecated in most contexts, and product markup requirements tightened around merchant integration. Treat structured data as a rendering layer you keep truthful, not a growth hack you extract once. The durable core is the discipline: every entity the page shows gets an accurate machine-readable description, derived from the same data the human sees. When a rich result type is deprecated, that discipline costs you nothing; when a new one ships (as AI surfaces increasingly consume the same schema.org vocabulary), it makes you early.

One deployment note ties back to the rendering phase: because the payload ships with the server-rendered HTML, its freshness follows the page's regime — a prerendered product page carries build-time prices in both the visible markup and the JSON-LD, so Incremental Static Regeneration or dynamic rendering is what keeps them current together. A stale price in the payload is doubly bad: wrong for the rich result and a mismatch signal against the (correctly updated) visible page.

The implementation that survives contact with real teams puts the JSON-LD builder beside the data it describes, fed by the same read. A complete product page:

// lib/product-jsonld.ts — pure function, unit-testable
export function buildProductJsonLd(product: Product) {
  return {
    "@context": "https://schema.org",
    "@type": "Product",
    name: product.name,
    image: product.images.map((i) => i.url),
    description: product.blurb.slice(0, 500),
    sku: product.sku,
    gtin13: product.gtin,
    brand: { "@type": "Brand", name: product.brand.name },
    aggregateRating: product.reviewCount > 0 && {
      "@type": "AggregateRating",
      ratingValue: product.rating,
      reviewCount: product.reviewCount,
    },
    offers: {
      "@type": "Offer",
      url: `/product/${product.slug}`,
      price: product.price.toFixed(2),          // string, as schema.org expects
      priceCurrency: "USD",                     // ISO 4217 — "USD", not "$"
      availability: product.inStock
        ? "https://schema.org/InStock"
        : "https://schema.org/OutOfStock",
      itemCondition: "https://schema.org/NewCondition",
    },
  };
}

// app/product/[slug]/page.tsx
export default async function ProductPage(props: { params: Promise<{ slug: string }> }) {
  const { slug } = await props.params;
  const product = await getProduct(slug);        // one read: UI and JSON-LD share it
  if (!product) notFound();
  return (
    <main>
      <ProductView product={product} />
      <ProductJsonLd product={product} />         {/* the script component */}
    </main>
  );
}

Field-level details that validators actually flag, learned the expensive way: price is a string (schema.org's Number type accepts it, and it sidesteps float formatting); priceCurrency is ISO 4217 with no symbols; availability and itemCondition are not free text but full schema.org URLs (https://schema.org/InStock) — the single most common typo class. An Offer without a price is ineligible; a price without priceCurrency is ineligible; both errors appear as absent rich results, never as exceptions.

The pattern extends without new machinery when a page carries more than one entity. A product page that renders a review list and a breadcrumb trail emits an array of nodes, each built by its own pure function and joined at render — const jsonLd = [buildProductJsonLd(product), buildBreadcrumbJsonLd(trail)]; — and validators accept multiple top-level nodes without complaint. The failure to avoid is emitting the same entity twice at top level (the product script from the page and another product script from a review component); parsers pick one and your rating markup becomes a coin flip. One owner per entity type, assembled in one place — the same composition rule as layouts, applied to data a machine reads.

The integrity guarantees come from structure, not vigilance. Because buildProductJsonLd is a pure function of the fetched record — the same record the visible component renders — the two cannot diverge on price or stock: one query, one truth, two projections. Unit-test the builder with a fixture product (cheap, and it catches a renamed field long before search console does), and reject the alternative architecture — a static JSON blob edited by hand — in code review on drift risk alone. The final consistency check runs at render: if the visible price and the payload price are computed from different fields, you have reintroduced the bug this design exists to prevent.

Completing the SEO stack: the title and social card come from generateMetadata, the crawl surface from Sitemaps and robots.txt, and the entity description from this payload — three layers, all server-rendered, all derived from the same data, none requiring client JavaScript. That closure is the practical answer to "how does a Next.js app get found": not one feature, but a coherent set of server-rendered signals that agree with each other. Beyond this phase, the roadmap turns to keeping the users those signals attract: sessions and identity are where Authentication Providers begins.