Skip to content
Derar Sattouf

Structured Data for SEO in 2026: JSON-LD for Developers

Updated SEO & analytics

Structured Data for SEO in 2026: JSON-LD for Developers

Structured data is one of the few SEO tasks that lives entirely in code. You describe a page in a machine-readable vocabulary, usually schema.org written as JSON-LD, and search engines use that description to understand what the page is. In 2026 the practical payoff is narrower than it was a few years ago, because Google has retired or restricted many rich result types. The value that remains is clarity: an accurate, consistent description of who wrote a page, what the page is, when it was published, and how it fits into your site. The examples here assume Next.js and the App Router.

JSON-LD is a <script type="application/ld+json"> block containing a schema.org object. Render it from a Server Component so it ships in the initial HTML. For a blog or portfolio, the useful types are WebSite, WebPage, Person, Organization, BlogPosting (or Article), and BreadcrumbList when you actually render breadcrumbs.

Google's Article documentation says there are no required properties, so add the recommended ones (headline, image, datePublished, dateModified, author) with correct values. Markup must describe content a visitor can see: every JSON-LD field should be backed by visible text or UI on the same page.

Some features are gone. FAQ rich results stopped appearing in Google Search on May 7, 2026. FAQPage is still valid schema.org, but do not expect a Google FAQ box from it. The sitelinks search box markup was retired in late 2024, so keep WebSite for its other uses, not for a search box. Validate with the Rich Results Test for Google eligibility and the Schema Markup Validator for schema.org correctness, and use both.

What JSON-LD is

JSON-LD (JavaScript Object Notation for Linked Data) is a way to attach structured information to a page as a JSON object. The object uses the @context key to point at a vocabulary, almost always https://schema.org, and the @type key to name the kind of thing being described. Everything else is a property of that thing.

A minimal example looks like this:

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Structured Data for SEO in 2026",
  "datePublished": "2026-10-30T00:00:00+00:00",
  "author": {
    "@type": "Person",
    "name": "Derar Sattouf"
  }
}

Where it goes in a Next.js page

The browser does not execute JSON-LD. Search engines read it from the HTML, so the script tag must be present in the server response. In the App Router, that means rendering it from a Server Component or from a component that the server renders. You do not need client JavaScript for it.

How this repo renders it

This portfolio renders JSON-LD with a tiny server component, JsonLd, that serializes an object into a script tag and escapes < so content can never close the tag. The blog route builds a BlogPosting object from the post's frontmatter and renders it:

// app/(site)/blog/[slug]/page.tsx (excerpt)
const articleJsonLd = {
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  headline: title,
  description: summary,
  url: absoluteUrl(`/blog/${post.slug}`),
  mainEntityOfPage: absoluteUrl(`/blog/${post.slug}`),
  image: absoluteUrl(postImage(post)),
  datePublished: publishedAt,
  dateModified: updatedAt || publishedAt,
  wordCount: wordCount(post.content),
  inLanguage: "en",
  author: { "@type": "Person", "@id": authorId, name: person.name, url: absoluteUrl("/about") },
  publisher: { "@id": authorId },
};

return <article><JsonLd data={articleJsonLd} />{/* ... */}</article>;

Three details matter for correctness:

  • dateModified comes from a real field. It uses the post's updatedAt when present and falls back to publishedAt. That is honest for never-edited posts and correct after a real revision. Keep updatedAt tied to substantive edits, and keep it identical to the date shown to readers.
  • The author is a shared entity. The @id (authorId, a URL ending in #person) lets the article, the site-level WebSite object and the about page refer to the same Person node instead of repeating slightly different copies.
  • Dates are bare dates in some frontmatter. Google recommends ISO 8601 with a timezone. This site's updatedAt values include a time, but older publishedAt values may be date-only. Normalize if you want strict consistency (see the helper below).

Rendering your own JSON-LD (illustrative)

When you need a type the component does not support, write a small server-rendered helper. The following is illustrative; adapt it to your project's conventions.

// Illustrative: a server-rendered JSON-LD script tag.
import type { ReactElement } from "react";
import { safeJsonLd } from "@/utils/safeJsonLd";

type JsonLdProps = {
  data: Record<string, unknown>;
};

export function JsonLd({ data }: JsonLdProps): ReactElement {
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: safeJsonLd(data) }}
    />
  );
}

The types that matter for a blog or portfolio

You do not need every schema.org type. For a personal site, a small set covers the ground. Each type below should describe something that is actually on the page.

Person

Person describes you as an entity. Use it as the author of articles and, on your about page, as the main subject. Useful properties include name, url (pointing at your about page or a canonical profile), image, and sameAs (an array of URLs for profiles that clearly belong to the same person, such as your GitHub or LinkedIn). Person does not produce a rich result of its own. Its job is disambiguation: it tells search engines which name on a byline refers to which identity.

Organization

Organization describes a brand, studio, or company behind the site. A single-person portfolio can skip it, but if you present work under a studio name, give it its own name, url, and logo, and keep the name identical to the one used elsewhere. Do not describe the same identity as a Person with one name and as an Organization with another.

WebSite

WebSite describes the site as a whole. It typically carries name, url, and description. Google has used WebSite markup to help display a site name in some results, and the sitelinks search box that once used SearchAction has been retired (more on that below). Keep one WebSite entity for the whole site, and emit it on the home page.

WebPage

WebPage describes an individual page. It is the right type for the about page, the blog index, the work index, and other non-article pages. Include name, url, description, and where relevant author. For a blog post, you can keep WebPage as the page-level context and use BlogPosting for the article, linked through mainEntityOfPage.

BlogPosting and Article

For blog posts, BlogPosting is the most specific schema.org type. Article is the parent type, and Google's documentation covers Article, NewsArticle, and BlogPosting together. Google states that these markups have no required properties. It recommends these properties where they apply:

  • headline: keep it short, because long headlines can be truncated on some devices.
  • image: images that represent the article, not logos. Google recommends high-resolution images with several aspect ratios when you can supply them.
  • datePublished and dateModified: ISO 8601 with a timezone. Google notes that without a timezone it defaults to Googlebot's timezone, which can shift the date by a day.
  • author: every author shown on the page, each with a name and a url or sameAs.

Your frontmatter stores publishedAt as a bare date such as 2026-10-30. That is not a full ISO 8601 timestamp with a timezone, so the helper in the next section normalizes it. A small detail like this is exactly the kind of thing that makes markup inconsistent over time.

BreadcrumbList describes the path a user took to reach a page. It is an ordered list of ListItem entries. Google's documentation says the list needs at least two items, that each item needs an item URL (the last item may omit it and fall back to the current page), and that name is needed unless the item refers to a Thing that has its own name. position is an integer starting at 1.

FAQPage

FAQPage describes a list of questions and answers on the page. It remains valid schema.org. Google's own FAQ rich results, however, stopped appearing in Search on May 7, 2026, as covered in the next section. Use FAQPage only if your visible page has a real FAQ section, because it still describes content for other consumers. Do not expect it to create an FAQ box in Google.

Which rich results Google supports in 2026

This section changes faster than any other part of structured data. Verify it against Google's Search Central documentation before you rely on it. The state below is accurate as of November 2026.

Still shown as rich result features

Google's Search Gallery lists the structured data types it currently displays as rich result features. The list includes Article, Breadcrumb, Organization, Profile page, Software app, Video, and several others. The gallery does not label any of them as deprecated. Two items on that list are worth a closer look for a portfolio:

  • Article covers blog posts. Its documentation is the reference for BlogPosting and Article shown above.
  • Breadcrumb is worth shipping when you render a real breadcrumb trail. Google makes no guarantee that breadcrumbs will appear, but following the guidelines is required for eligibility.

The gallery also lists Profile page. Read its documentation before you add that markup to your about page.

Person and WebSite are not listed as standalone rich result features in the gallery. They still matter for entity understanding and for site name display, but do not expect a visible card from them.

Deprecated or restricted

  • FAQ rich results. Google's documentation changelog says that "This feature will no longer appear in Google Search starting May 7, 2026." Coverage from several industry outlets reports that the FAQ report and the related Search Console filter are being retired in June 2026, with API support removed in August 2026. Earlier, in August 2023, Google had already restricted FAQ rich results to well-known government and health sites.
  • The sitelinks search box. Secondary reports say Google retired it in November 2024. Google said that unsupported structured data does not cause errors in Search or Search Console, so existing SearchAction markup can stay, but there is no reason to add it now.
  • Some types removed in June 2025. Industry coverage reports that Google dropped seven structured data types at that time, including Course Info, Learning Video, Book Actions, Claim Review, Estimated Salary, Special Announcement, and Vehicle Listing. None of these are typical for a blog or portfolio. Check Google's current documentation before you assume a type is still active.

Keeping deprecated markup in place is generally harmless. Google says it does not hurt the page, although it may not display. The risk is maintenance cost and the false impression that a type is doing something it no longer does.

A reusable helper: building BlogPosting from MDX frontmatter

The most useful piece of structured data for this site is the BlogPosting object, because every post has the same fields. The helper below is illustrative. It takes the frontmatter shape used by this repo's posts and returns a plain object. You can render it through the JsonLd component above, or merge several objects into one graph, as shown in the next section.

// Illustrative: build a BlogPosting object from MDX frontmatter.
type PostFrontmatter = {
  title: string;
  summary?: string;
  description?: string;
  publishedAt: string;
  dateModified?: string;
  image?: string;
};

type PostAuthor = {
  name: string;
  url: string;
};

type BuildBlogPostingOptions = {
  post: PostFrontmatter;
  slug: string;
  baseURL: string;
  author: PostAuthor;
};

// Google recommends ISO 8601 with a timezone. Frontmatter often stores a bare date.
const toIsoWithTimezone = (value: string): string =>
  /^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T00:00:00+00:00` : value;

export const buildBlogPostingJsonLd = ({
  post,
  slug,
  baseURL,
  author,
}: BuildBlogPostingOptions): Record<string, unknown> => {
  const pageUrl = `${baseURL}/blog/${slug}`;
  const imagePath =
    post.image ?? `/api/og/generate?title=${encodeURIComponent(post.title)}`;

  return {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    "@id": `${pageUrl}#blogposting`,
    mainEntityOfPage: {
      "@type": "WebPage",
      "@id": pageUrl,
    },
    url: pageUrl,
    headline: post.title,
    description: post.summary ?? post.description,
    image: new URL(imagePath, baseURL).toString(),
    datePublished: toIsoWithTimezone(post.publishedAt),
    ...(post.dateModified
      ? { dateModified: toIsoWithTimezone(post.dateModified) }
      : {}),
    author: {
      "@type": "Person",
      name: author.name,
      url: author.url,
    },
  };
};

Some decisions in this helper are deliberate. dateModified is only emitted when the frontmatter provides it, so the helper never claims a post was not edited when you do not know that. The date normalization handles the bare YYYY-MM-DD format used in the frontmatter. The @id and mainEntityOfPage pair ties the article to its page, which is useful if you later add a WebPage entity for the same URL. The url and the @id should both resolve to the canonical URL that your metadata helper writes into the page's alternates.canonical, so the two sources of truth agree.

A BreadcrumbList example

The following shows a breadcrumb for a page nested two levels deep. It is illustrative. In this portfolio, you would only emit it on a page that renders a visible breadcrumb trail of the same items.

// Illustrative: build a BreadcrumbList from an ordered trail.
type Crumb = {
  name: string;
  path: string;
};

export const buildBreadcrumbJsonLd = (
  baseURL: string,
  trail: Crumb[],
): Record<string, unknown> => ({
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  itemListElement: trail.map((crumb, index) => ({
    "@type": "ListItem",
    position: index + 1,
    name: crumb.name,
    item: `${baseURL}${crumb.path}`,
  })),
});

// Example: a trail for a work case study, nested under the work index.
export const workCaseStudyBreadcrumbs = (baseURL: string, title: string, slug: string) =>
  buildBreadcrumbJsonLd(baseURL, [
    { name: "Work", path: "/work" },
    { name: title, path: `/work/${slug}` },
  ]);

Two points matter here. First, position is a one-based index that matches the visual order of the breadcrumb on screen. Second, name values should match the labels a user sees. If your visible breadcrumb says "Work" and your markup says "Portfolio", the markup no longer describes the page accurately.

A breadcrumb with a single ancestor and no current item does not meet Google's two-item minimum. Either render a trail that has a real parent and child, or skip the markup.

Escaping JSON-LD safely

JSON-LD is embedded in HTML, and that creates a specific risk. If any string inside the object contains the sequence </script>, the browser will close the script tag early and treat the rest of the JSON as HTML. A blog post title or a summary written by a user could do this, and so could content pulled from a CMS. The fix is to escape the < character inside the serialized JSON.

// Escapes "<" so that a value cannot close the surrounding script tag.
// "<" is a valid JSON string escape, so parsers still read the same data.
export const safeJsonLd = (data: unknown): string =>
  JSON.stringify(data).replace(/</g, "\\u003c");

JSON.stringify does not escape < on its own, which is why the replacement is needed. The replacement is safe because the escaped form is a standard JSON escape sequence. Any JSON parser decodes it back to <, so the structured data still means exactly what you wrote. The JsonLd component above uses this helper for that reason.

If you use a third-party SEO component, read its source to confirm it escapes the serialized output. If it does not, render the JSON-LD yourself with the helper above. The Next.js JSON-LD guide gives the same advice and mentions serialize-javascript as an alternative.

Validating your markup

Use two tools, because they answer different questions.

  • The Rich Results Test (https://search.google.com/test/rich-results) checks whether a URL or a code snippet is eligible for Google's rich result features. It reports errors that block eligibility and warnings for recommended fields. Use it on the live URL after deployment, because it fetches the rendered page.
  • The Schema Markup Validator (https://validator.schema.org/) checks whether the markup is valid schema.org. It does not know about Google's requirements. Use it to catch typos in property names, wrong value types, and misused types.
  • When a block will not parse at all, paste it into the JSON formatter on this site to find the syntax error before you test again.

Also check Search Console's Enhancements reports and the Manual Actions report. Google documents that a structured data manual action removes eligibility for rich results but does not change ranking in web search. If a page loses rich result eligibility and you have not changed the markup recently, the Manual Actions report is the first place to look.

One connected graph with @id references

Separate script blocks that each describe "the author" invite inconsistent copies. A cleaner pattern is a single graph in which every entity has a stable @id and other entities refer to it. The @id is just an identifier (conventionally a URL with a fragment); it does not need to resolve to a document.

WebSite  (https://www.example.com/#website)
   publisher --> Person (https://www.example.com/#person)
Person   (https://www.example.com/#person)
   url      --> /about
BlogPosting (https://www.example.com/blog/my-post#article)
   author     --> Person (#person)
   publisher  --> Person (#person)
   isPartOf   --> Blog   (/blog)
   mainEntityOfPage --> WebPage (/blog/my-post)

In code, emit the shared nodes once (in the root layout) and reference them elsewhere:

// app/layout.tsx (excerpt)
const SITE = "https://www.example.com";

const siteGraph = {
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Person",
      "@id": `${SITE}/#person`,
      name: "Your Name",
      url: `${SITE}/about`,
      image: `${SITE}/images/avatar.jpg`,
      sameAs: ["https://github.com/your-handle", "https://www.linkedin.com/in/your-handle"],
    },
    {
      "@type": "WebSite",
      "@id": `${SITE}/#website`,
      url: SITE,
      name: "Your Name",
      publisher: { "@id": `${SITE}/#person` },
      inLanguage: "en",
    },
  ],
};

Then a post only needs author: { "@id": ".../#person" }. If the graph grows, validate that every referenced @id is defined somewhere on the same page or is an intentional external reference. This matters because Google and other consumers resolve references within a page's markup.

Use sameAs only for profiles that are really you. Wrong or spammy sameAs links weaken the signal instead of strengthening it.

Marking up an About page with ProfilePage

Google's ProfilePage markup is intended for pages whose primary focus is one person or organization affiliated with the site; the documentation lists blog "About Me" pages, news author pages, forum and social profiles, and employee pages as valid. Required: mainEntity (a Person or Organization) with a name or alternateName. Recommended on the page: dateCreated, dateModified; on the person: description, image, sameAs, alternateName, identifier. Do not use placeholder or icon images, and image URLs must be crawlable.

const profilePage = {
  "@context": "https://schema.org",
  "@type": "ProfilePage",
  "@id": "https://www.example.com/about#profile",
  url: "https://www.example.com/about",
  dateCreated: "2024-01-15T00:00:00+00:00",
  dateModified: "2026-09-01T00:00:00+00:00", // only when a human edits the profile
  mainEntity: {
    "@type": "Person",
    "@id": "https://www.example.com/#person",
    name: "Your Name",
    description: "Full-stack developer working with Next.js, Laravel and Flutter.",
    image: "https://www.example.com/images/avatar.jpg",
    sameAs: ["https://github.com/your-handle"],
  },
};

A store home page or a page with lots of non-profile content is not a valid use. Read the current documentation before shipping, since requirements evolve.

Which types fit which kind of site

Pick types because they describe your pages, not because they are on a list. Google's gallery lists around two dozen features; the ones most relevant to developer sites:

Your pageCandidate markupNotes
Blog postBlogPosting or Article, BreadcrumbListNo required properties for Article, but recommended ones matter
About pageProfilePage with Person, or plain Person and WebPageMust be primarily about one person or organization
Home pageWebSite, Organization or PersonSite name and entity signals
Free tool or web appSoftwareApplication or WebApplicationSee Google's Software app documentation for eligibility, for example review or rating requirements
Product pageProduct with offers and reviewsStrict requirements; markup must match visible price and availability
EventEventNeeds dates, location or online attendance mode
Video tutorialVideoObjectNeeds a thumbnail, upload date and a watch page
DatasetDatasetFor publicly described data
Paywalled contentSubscription and paywalled content markupDeclares which parts are gated, to avoid cloaking concerns
DocumentationTechArticle or ArticleTechArticle is a schema.org subtype; Google documents Article
Job listingJobPostingMust follow Google's job posting rules

If you do not see a match, ship less markup. A correct WebSite, Person, BlogPosting and BreadcrumbList is more valuable than ten speculative types.

Retired or restricted features keep changing. As of Google's documentation in 2026, the FAQ rich result no longer appears, and the Search gallery does not list FAQ or HowTo. Treat any "must-have schema" article older than a year with suspicion, and re-check the gallery.

Lab: test your JSON-LD in CI

Structured data breaks silently: a refactor renames a field, a template stops emitting the script, or a date format drifts. Add an automated check that fetches your built pages, parses every JSON-LD block, and asserts simple invariants.

// scripts/jsonld-audit.mjs
// Usage: node scripts/jsonld-audit.mjs http://localhost:3000 /blog/my-post /about
const [origin, ...paths] = process.argv.slice(2);
if (!origin || paths.length === 0) {
  console.error("Usage: node scripts/jsonld-audit.mjs <origin> <path> [<path> ...]");
  process.exit(2);
}

const failures = [];
const fail = (path, msg) => failures.push(`${path}: ${msg}`);

const extract = (html) =>
  [...html.matchAll(/<script[^>]*type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/gi)].map((m) => m[1]);

const flatten = (doc) => (Array.isArray(doc) ? doc : doc["@graph"] ? doc["@graph"] : [doc]);

const isoWithZone = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2}))?$/;

for (const path of paths) {
  const res = await fetch(origin + path);
  const html = await res.text();
  const blocks = extract(html);
  if (blocks.length === 0) { fail(path, "no JSON-LD found"); continue; }

  const title = html.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i)?.[1]?.replace(/<[^>]+>/g, "").trim();
  const nodes = [];
  for (const raw of blocks) {
    try { nodes.push(...flatten(JSON.parse(raw))); }
    catch (e) { fail(path, `invalid JSON in a JSON-LD block: ${e.message}`); }
  }

  for (const n of nodes) {
    const type = [n["@type"]].flat().join(",");
    if (/BlogPosting|Article/.test(type)) {
      if (!n.headline) fail(path, "article without headline");
      if (title && n.headline && n.headline.trim() !== title) fail(path, `headline differs from visible h1: "${n.headline}" vs "${title}"`);
      if (!n.datePublished || !isoWithZone.test(n.datePublished)) fail(path, `bad datePublished: ${n.datePublished}`);
      if (n.dateModified && new Date(n.dateModified) < new Date(n.datePublished)) fail(path, "dateModified is before datePublished");
      if (!n.author) fail(path, "article without author");
      if (n.image && !/^https?:\/\//.test(Array.isArray(n.image) ? n.image[0] : n.image)) fail(path, "image is not an absolute URL");
    }
    if (/BreadcrumbList/.test(type)) {
      const items = n.itemListElement ?? [];
      if (items.length < 2) fail(path, "breadcrumb has fewer than 2 items");
      items.forEach((it, i) => { if (it.position !== i + 1) fail(path, `breadcrumb position ${it.position} at index ${i}`); });
    }
  }
  console.log(`${path}: ${blocks.length} block(s), ${nodes.length} node(s)`);
}

if (failures.length) { console.error("\n" + failures.join("\n")); process.exit(1); }
console.log("JSON-LD audit passed");

Run it against the production build in CI and add it to pull requests that touch templates. A short unit test for your builder functions is cheaper still:

// seo/jsonld.test.ts
import { describe, expect, it } from "vitest";
import { buildBlogPostingJsonLd } from "./jsonld";

describe("buildBlogPostingJsonLd", () => {
  const base = {
    slug: "my-post",
    baseURL: "https://www.example.com",
    author: { name: "A", url: "https://www.example.com/about" },
  };

  it("omits dateModified when unknown", () => {
    const data = buildBlogPostingJsonLd({ ...base, post: { title: "T", publishedAt: "2026-01-02" } });
    expect(data).not.toHaveProperty("dateModified");
  });

  it("normalizes bare dates to ISO with timezone", () => {
    const data = buildBlogPostingJsonLd({ ...base, post: { title: "T", publishedAt: "2026-01-02" } });
    expect(data.datePublished).toBe("2026-01-02T00:00:00+00:00");
  });

  it("never lets a title close the script tag", () => {
    const html = JSON.stringify({ t: "</script><script>alert(1)</script>" }).replace(/</g, "\\u003c");
    expect(html).not.toContain("</script>");
  });
});

For typed authoring, the community package schema-dts provides TypeScript types for schema.org (the Next.js docs mention it). It catches misspelled property names at compile time.

Visible-content parity: what must match

The rule that causes most manual actions and ignored markup is "markup must reflect visible content". Use this table in code review:

Property in JSON-LDMust match what the user sees
headlineThe page's H1 or visible title
descriptionThe visible summary or intro, not a keyword-stuffed variant
datePublished, dateModifiedThe dates shown on the page
author.nameThe byline
imageAn image that appears in the article, not a generic logo
breadcrumb names and orderThe visible breadcrumb trail
FAQ questions and answersVisible text, word for word
offers.price, availability (Product)The visible price and stock state
aggregateRatingReal, visible, first-party review data. Never invented

The simplest way to stay in parity is to generate both the visible UI and the JSON-LD from the same data object.

Troubleshooting

SymptomLikely causeFix
Rich Results Test shows "no items detected"Script tag missing from server HTML, or invalid JSONcurl the page and search for application/ld+json; parse the block
Validator error: unexpected tokenTrailing comma, unescaped quotes or a template literal bugGenerate with JSON.stringify, never string concatenation
Works in dev, missing in productionMarkup rendered only on the clientRender from a Server Component
Warning: image missingNo image, or a relative URLProvide an absolute, crawlable image URL
Dates off by a dayNo timezone in the dateUse ISO 8601 with an offset
Breadcrumb not eligibleFewer than two items or missing itemRender at least a parent and child, and give each item a URL
Two Person entities with different namesCopy-pasted markup in several templatesShare one entity via @id
Rich result disappearedGoogle stopped showing the feature, or a policy issueCheck the Search Console enhancement and manual actions reports, then the gallery
Markup validates but nothing showsValid is not eligible, and display is at Google's discretionFollow the type's guidelines; do not expect guaranteed display
Special characters break the pageUnescaped < in a valueEscape the < after JSON.stringify
Search Console reports duplicate or conflicting itemsSame entity emitted twice with different dataRemove one, or unify through @id

When not to add structured data

  • When the page does not contain the content. Never mark up reviews, prices, ratings or FAQs that users cannot see.
  • When the type is retired. Do not build new FAQ rich-result work, sitelinks search box markup, or other features Google no longer shows.
  • When you cannot keep it accurate. Stale prices, dates or availability are worse than no markup. If the data changes often, generate it from the source of truth or skip it.
  • When you expect it to boost AI answers. Google's guidance on its AI features says no special structured data is required. Keep markup honest and consistent, but do not treat it as an AI-visibility switch. See SEO for Google AI Mode.
  • For pages you want out of search. Use noindex; markup will not help.

Also see Next.js Technical SEO Checklist for canonicals, sitemaps and robots, Generative Engine Optimization (GEO) for the broader AI-search picture, and Keyword Research and Internal Linking for the content side.

A step-by-step checklist

  1. Decide which entities the site has: one WebSite, one Person (you), an optional Organization, and a WebPage for each major route.
  2. Render each JSON-LD block from a Server Component so it is in the initial HTML.
  3. For each blog post, emit a BlogPosting that uses the frontmatter title, summary, publishedAt, image, and author.
  4. Normalize dates to ISO 8601 with a timezone. Emit dateModified only from a real modified date.
  5. Make sure the url values match the canonical URLs from your metadata helper.
  6. Emit BreadcrumbList only on pages that render a visible breadcrumb with the same labels and order.
  7. Emit FAQPage only on pages with a visible FAQ section whose questions and answers are word for word the same as the markup.
  8. Escape the serialized JSON so < cannot close the script tag.
  9. Run the Rich Results Test on a deployed URL and the Schema Markup Validator on the same output.
  10. Check the Search Console Enhancements and Manual Actions reports after the next crawl.
  11. Re-check the Google documentation for any type you ship, at least once a year, because the supported list changes.

Where this usually goes wrong

Markup that does not match visible content. This is the most serious one. Google's general structured data guidelines say markup should describe only what visitors can see on the page. If your JSON-LD names a reviewer, a rating, or a list of tools that is not on the page, the markup is invalid for Google's purposes even if it validates against schema.org. The same applies to a description that differs in substance from the visible summary. Generate JSON-LD from the same data that renders the visible content, rather than writing it by hand.

Missing required properties. Google's guidelines say that items missing required properties are not eligible for rich results. For Article markup, Google says there are no required properties, so the mistake is usually elsewhere: a BreadcrumbList with one ListItem, a ListItem without name and without an item that resolves to a Thing with a name, or an image URL that is not crawlable. Read the documentation for the type you are shipping and check each required field.

Duplicated or conflicting entities. Two Person objects with different names for the same author, or a WebSite whose name disagrees with the page title, creates conflicting signals. Pick one canonical name for yourself and use it everywhere. Google's guidelines also say that duplicate pages with the same content should carry the same structured data, not just the canonical version.

Hidden content. Google's guidelines say that content referenced in markup but hidden from users can prevent rich results from appearing. A FAQ inside an accordion that is collapsed by default is generally fine as long as the content is in the page and users can open it, but markup that describes text that never renders is not. Test the rendered page, not just your source.

Stale dates. Copying publishedAt into dateModified on every page is a common default. It is accurate for posts you have never edited and wrong for everything else. Use a real modified date from your content source, or leave dateModified out.

Relying on deprecated types. Shipping FAQPage expecting an FAQ box, or adding sitelinks search box markup in 2026, spends effort on features that Google no longer displays. Check the documentation before you build a new type.

Assuming valid means eligible. A validator passing does not guarantee a rich result. Google's guidance is that valid markup is necessary but not sufficient. Eligibility also depends on the page meeting Google's quality and spam guidelines and on Google's own decisions about what to show.

Questions that come up

Does structured data improve my rankings? Not directly. It helps search engines understand your pages and, for some types, qualifies them for rich results. A rich result can improve click-through rate, but that is a separate effect from ranking.

Is FAQPage still worth adding? Only if your page has a real FAQ section and you want the markup to describe it. Google's FAQ rich results stopped appearing in May 2026, so do not add it for the rich result alone.

Where should the script tag go, head or body? Either works. Google reads JSON-LD anywhere in the rendered HTML. In the App Router, rendering it inside the page or layout component is the documented approach.

Should I use @graph or several script tags? Both are valid. A single graph with @id references makes consistency easier; separate tags are simpler for independent components.

How long until a change is picked up? After the next crawl and processing, which can take days. Use URL Inspection to request a recrawl after a meaningful fix.

What about dateModified on every deploy? Do not. Update it only when the content changes in a way a reader would care about.

Sources