Server injection of JSON-LD structured data

Definition

This is the approach used when you want a search engine to unambiguously understand "what your page is about" (whether it is a product, what the price is, who the author and date of this article are), so it appears in Google search results as rich results like star ratings, prices, or breadcrumb paths.

JSON-LD (JavaScript Object Notation for Linked Data) is the data format for embedding that semantic information inside HTML via a <script type="application/ld+json"> tag. If you write types such as WebPage, Product, Offer (sale terms·price), and BreadcrumbList (breadcrumb navigation path) using the vocabulary of schema.org (a standard vocabulary dictionary jointly defined by Google, MS, and others), search engines·crawlers (bots that traverse and index the web) can read the page's meaning accurately by machine rather than by human.

Why it matters

For pricing pages·product details, showing text on screen alone makes it hard for a machine to reliably extract the relationships "this is the plan name, that is the price, the currency is won, and this page sits under this category." JSON-LD states these relationships outright. Even if the visible UI is a client component (a React component that runs in the browser), building this data bundle (graph) with a builder function in the page.tsx that runs on the server cleanly separates the SEO data from the visible UI.

How it works

1. Assemble @context, @graph, @type, @id in a pure builder like *JsonLd.ts.
2. The site-wide Organization/WebSite is only referenced by @id and is not fully redefined on every page.
3. Reflect the per-locale canonical URL·name.
4. In page.tsx (Server Component):

const jsonLd = buildPricingJsonLd({ locale, plans, siteUrl });
const safe = JSON.stringify(jsonLd).replace(/</g, "\\u003c");

return (
  <>
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: safe }}
    />
    <PricingScreen />
  </>
);

5. Offer only for tiers that have an actual sale price; exclude contact-form enterprise tiers.

Practical application

• Feed static price tables·i18n strings as builder inputs — deterministic graph generation without a runtime DB.
• Assert @graph length, Offer count, and required @type with Vitest.
• Guest/logged-in UI branching is client; JSON-LD is generated only on the server based on public information.

Trade-offs

When not to use it

• When you would have to put private·personalized data into the graph (public JSON-LD is unsuitable).
• When the price is determined only on the client and the server cannot know it — the graph becomes stale·inaccurate.

Common mistakes

• Inserting user-controlled strings without JSON.stringify sanitization.
• Redefining Organization/WebSite duplicately on every page, causing graph inconsistency.
• Generating the graph only inside a UI client component — absent from the initial HTML.
• Including a price-less Offer for contact-form plans.

Related concepts

• single-source-of-truth-content-metadata — frontmatter·metadata SSOT
• critical-rendering-path — script parsing and render (generally non-blocking)