When NOT to use

• Pages behind authentication that Google cannot crawl
• Content that does not match any Schema.org type — do not force-fit
• Microsites with no organic search strategy
• When the content violates Google's structured data guidelines (e.g., marking non-FAQ content as FAQ)

Core concepts

• JSON-LD — JavaScript Object Notation for Linked Data — Google's preferred structured data format
• @context — Always https://schema.org — declares the vocabulary; check schema.org/version/latest for the current published schema
• @type — The Schema.org entity type (Article, Product, FAQPage, HowTo, Credential, Error, etc.)
• Nesting — Embedding related entities within a parent (e.g., Author within Article)
• @id — A canonical URI for the entity, enabling cross-referencing between schemas
• ItemList — A wrapper for ordered or unordered lists of schema items
• Rich result — Enhanced SERP display triggered by valid structured data (Google controls which types are eligible; consult Google's Search Gallery)
• Eligibility — Not all schema types trigger rich results — only Google-supported types listed at: https://developers.google.com/search/docs/appearance/structured-data/search-gallery

Workflow

Step 1: Identify the correct schema type

Match your content to the most specific Schema.org type. Recent v30.0 additions you may need:

• Credential — use for certifications, badges, and non-educational credentials where a hasCredential relationship is required.
• Error — use for machine-readable error reporting with errorCode and related properties.

Common mappings:

• Blog post / news article → Article, NewsArticle, BlogPosting → Article snippet
• Product page → Product → Price, rating, availability
• FAQ section → FAQPage → Expandable Q&A (visibility constrained by Google policy)
• Tutorial / guide → HowTo → Step-by-step display (device restrictions apply)
• Breadcrumb nav → BreadcrumbList → Breadcrumb trail
• Site-wide search → WebSite + SearchAction → Sitelinks search box
• Business info → Organization, LocalBusiness → Knowledge panel

Step 2: Build the JSON-LD component

Create a reusable component for each schema type. Examples below remain valid; when using dynamic properties introduced in v30.0 (Credential, Error, floorLevel, jobDuration, etc.), include them where applicable.

Article schema (React example)

export function ArticleJsonLd({ title, description, url, imageUrl, authorName, publishedAt, modifiedAt }) {
  const schema = {
    "@context": "https://schema.org",
    "@type": "Article",
    headline: title,
    description,
    url,
    image: imageUrl,
    author: { "@type": "Person", name: authorName },
    publisher: { "@type": "Organization", name: "YourBrand", logo: { "@type": "ImageObject", url: "https://yourbrand.com/logo.png" } },
    datePublished: publishedAt,
    dateModified: modifiedAt,
  };
  return (<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} />);
}

Product schema (React example)

• Keep offers with numeric price and priceCurrency as separate fields. Use ISO 4217 currency codes.

export function ProductJsonLd({ name, description, imageUrl, price, currency, availability, ratingValue, reviewCount, sku, brand }) {
  const schema = {
    "@context": "https://schema.org",
    "@type": "Product",
    name,
    description,
    image: imageUrl,
    sku,
    brand: { "@type": "Brand", name: brand },
    offers: { "@type": "Offer", price: price, priceCurrency: currency, availability: `https://schema.org/${availability}` }
  };
  if (ratingValue != null) {
    schema.aggregateRating = { "@type": "AggregateRating", ratingValue, reviewCount: reviewCount ?? 0 };
  }
  return (<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} />);
}

FAQ schema (React example)

• Note: Google has changed how FAQ structured data is surfaced (see Edge cases). Mark up only genuine Q&A content; do not attempt to game visibility.

export function FaqJsonLd({ items }) {
  const schema = { "@context": "https://schema.org", "@type": "FAQPage", mainEntity: items.map(item => ({ "@type": "Question", name: item.question, acceptedAnswer: { "@type": "Answer", text: item.answer } })) };
  return (<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} />);
}

HowTo schema (React example)

• Note: HowTo rich results visibility and device behavior changed in 2023. Use HowTo markup for content understanding and potential device-specific features, but verify expectations in Google's Search Gallery.

export function HowToJsonLd({ title, steps }) {
  const schema = { "@context": "https://schema.org", "@type": "HowTo", name: title, step: steps.map((s, i) => ({ "@type": "HowToStep", position: i + 1, name: s.name, text: s.text, ...(s.imageUrl ? { image: s.imageUrl } : {}) })) };
  return (<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} />);
}

Step 3: Add BreadcrumbList schema

export function BreadcrumbJsonLd({ crumbs }) {
  const schema = { "@context": "https://schema.org", "@type": "BreadcrumbList", itemListElement: crumbs.map((c, i) => ({ "@type": "ListItem", position: i + 1, name: c.name, item: c.url })) };
  return (<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} />);
}

Step 4: Validate with tools

1. Deploy or preview the page
2. Use Google's Rich Results Test: https://search.google.com/test/rich-results (checks eligibility for Google-rich displays)
3. Check the Search Console ‘Enhancements’ / Structured Data reports after crawling for real-world coverage and errors
4. Use Schema.org's validator: https://validator.schema.org/ for schema syntax and term validation
5. Re-validate after every schema change

Examples

Organization schema in root layout

const orgSchema = {
  "@context": "https://schema.org",
  "@type": "Organization",
  name: "YourBrand",
  url: "https://yourbrand.com",
  logo: "https://yourbrand.com/logo.png",
  sameAs: ["https://twitter.com/yourbrand","https://github.com/yourbrand","https://linkedin.com/company/yourbrand"],
};

WebSite with sitelinks search box

const websiteSchema = {
  "@context": "https://schema.org",
  "@type": "WebSite",
  name: "YourBrand",
  url: "https://yourbrand.com",
  potentialAction: { "@type": "SearchAction", target: "https://yourbrand.com/search?q={search_term_string}", "query-input": "required name=search_term_string" },
};

Decision tree

• Blog post or article → use Article or BlogPosting with author and dates
• Product with price → use Product with Offer; add AggregateRating if reviews exist
• FAQ section with Q&A pairs → use FAQPage; ensure answers are substantive (not just links); expect limited Google visibility except for certain authoritative sites
• Step-by-step tutorial → use HowTo with ordered steps; validate expectations against Google's device-specific behavior
• Breadcrumb navigation → use BreadcrumbList on every page
• Homepage or root layout → add Organization and WebSite schemas
• Multiple schema types on one page → use multiple script tags; do not combine into one object

Edge cases and gotchas (updated)

1. FAQ schema visibility — Google changed how FAQ rich results are surfaced (see Google Search Central blog: "Changes to HowTo and FAQ rich results" Aug 8, 2023). FAQ rich results are now shown far less frequently and may be limited to highly authoritative government and health sites. Do not rely on FAQ markup to produce an expandable rich result for most sites; however, marking up FAQs can still help search engines understand your content.
2. HowTo visibility and device constraints — Google limited HowTo rich results visibility and device behavior in 2023; verify expectations in the Search Gallery before assuming a universal desktop/mobile display.
3. Missing required fields — each schema type has required properties. A Product without offers will not trigger price/rating rich results. Always check Google's Search Gallery for required fields for each rich result type.
4. Price format — use numeric values without currency symbols. "price": 29.99 not "price": "$29.99". Use ISO 4217 codes for currency when required.
5. Date format — use ISO 8601 format (2025-01-15T10:00:00Z). Relative dates ("2 days ago") are invalid.
6. Image requirements — Article rich results require images at least 1200px wide to be eligible for large-image displays; consult the Search Gallery for exact dimensions.
7. Over-nesting — deeply nested schemas are harder to maintain and debug. Keep nesting to 2–3 levels maximum.
8. Schema.org versioning — Schema.org evolves; new types and properties (e.g., Credential, Error, floorLevel, jobDuration) arrived in v30.0. Prefer referencing schema.org/version/latest for canonical term definitions and ranges.

Evaluation criteria

• JSON-LD validates with zero errors in Google Rich Results Test and Schema.org validator
• Each page uses the most specific applicable schema type
• All required fields per Google's documentation are present
• Schema components are reusable React components with typed props
• No schema type misuse (e.g., FAQ for non-FAQ content)
• Organization and WebSite schemas are present in the root layout
• Dates use ISO 8601 format; prices use numeric values