> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Structured Data (Schema.org)

> Help search engines understand your content with schema.org JSON-LD markup

Structured data is how you tell Google exactly what's on a page — this is an article, this is a product, this is an event starting at 7pm. When you add it, Google can show rich results (star ratings, event times, recipe thumbnails, FAQ accordions) in search, which meaningfully lifts click-through rate.

<Info>
  Structured data doesn't guarantee rich results — Google decides based on content quality, relevance, and trust. It's a prerequisite, not a magic toggle.
</Info>

## Three Paths

<Tabs>
  <Tab title="AI Chat (easiest)">
    Describe what you want:

    ```
    Add Article schema to my blog posts, Product schema to 
    /shop/* pages, and Organization schema site-wide.
    ```

    The AI will detect your page types, generate the appropriate JSON-LD, and inject it into your page templates.
  </Tab>

  <Tab title="Site Enhancements">
    Enable [SEO Enhancements](/how-tos/site-enhancements) in your project. It auto-generates basic schema — Organization, WebSite, WebPage — without any custom work. For richer types (Article, Product, Event, Recipe), add them manually on top.
  </Tab>

  <Tab title="Manual JSON-LD">
    Add `<script type="application/ld+json">` tags directly in your page templates. Good if you want fine control over every field.
  </Tab>
</Tabs>

## Common Schema Types by Page Type

| Page type      | Schema type              |
| -------------- | ------------------------ |
| Home / About   | Organization             |
| Blog post      | Article / BlogPosting    |
| Product        | Product + Offer          |
| Event          | Event                    |
| Recipe         | Recipe                   |
| Review         | Review / AggregateRating |
| FAQ            | FAQPage                  |
| Local business | LocalBusiness            |

Most pages use 1-2 schema types. Don't stack unrelated schema hoping for more rich results — Google treats that as spam.

## Example: Article Schema

For a blog post:

```html theme={null}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "5 Tips for Better Website Performance",
  "author": { "@type": "Person", "name": "Jane Doe" },
  "datePublished": "2026-04-19T09:00:00Z",
  "image": "https://yoursite.com/images/hero.jpg",
  "publisher": {
    "@type": "Organization",
    "name": "Acme Inc",
    "logo": {
      "@type": "ImageObject",
      "url": "https://yoursite.com/logo.png"
    }
  }
}
</script>
```

Eligible rich result: article with thumbnail, date, and author in the search snippet.

## Example: Product Schema

For a product detail page:

```html theme={null}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Blue Widget",
  "image": "https://yoursite.com/widget.jpg",
  "description": "High-quality blue widget",
  "offers": {
    "@type": "Offer",
    "price": "29.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}
</script>
```

Eligible rich result: price, availability, and (with AggregateRating added) star ratings.

## Example: FAQ Schema

Stick this on any page with genuine Q\&A content:

```html theme={null}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Do you offer refunds?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes, within 30 days of purchase."
      }
    },
    {
      "@type": "Question",
      "name": "How long does shipping take?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Standard shipping is 3-5 business days."
      }
    }
  ]
}
</script>
```

## Dynamic Schema for Blog and Product Pages

Hardcoded JSON-LD only works for static content. For blogs and products, generate it from your data:

<Steps>
  <Step title="Fetch the page data">
    Load the blog post or product from your database.
  </Step>

  <Step title="Build the schema object">
    ```tsx theme={null}
    function articleSchema(post) {
      return {
        "@context": "https://schema.org",
        "@type": "Article",
        headline: post.title,
        author: { "@type": "Person", name: post.author_name },
        datePublished: post.published_at,
        dateModified: post.updated_at,
        image: post.hero_image_url,
        publisher: {
          "@type": "Organization",
          name: "Acme Inc",
          logo: { "@type": "ImageObject", url: "https://yoursite.com/logo.png" }
        }
      };
    }
    ```
  </Step>

  <Step title="Inject into the page head">
    In Next.js, use the built-in Script component or render the JSON inside a script tag via children:

    ```tsx theme={null}
    import Script from 'next/script';

    <Script
      id="article-schema"
      type="application/ld+json"
    >
      {JSON.stringify(articleSchema(post))}
    </Script>
    ```

    JSON.stringify produces safe JSON — no user-generated HTML is inserted, so there's no XSS risk as long as you're only serializing your own structured data object.
  </Step>
</Steps>

## Test Your Schema

Google provides a free validator:

<Steps>
  <Step title="Visit the Rich Results Test">
    Open [search.google.com/test/rich-results](https://search.google.com/test/rich-results).
  </Step>

  <Step title="Paste your page URL">
    Or paste raw HTML if the page isn't deployed yet.
  </Step>

  <Step title="Review results">
    The test shows:

    * Which schema types were detected
    * Whether the page is eligible for rich results
    * Any errors or warnings (missing required fields)
  </Step>

  <Step title="Fix errors, leave warnings">
    Errors block rich results. Warnings mention optional fields and are safe to ignore unless you want the richest possible snippet.
  </Step>
</Steps>

<Tip>
  Don't stuff schema for entities that aren't actually visible on the page. Google detects this as manipulation and may issue a manual penalty that's painful to recover from. Schema should describe what's on the page — not what you wish were on the page.
</Tip>

## Monitor Rich-Result Coverage

Google Search Console shows you what's working:

<Steps>
  <Step title="Open Search Console">
    [search.google.com/search-console](https://search.google.com/search-console)
  </Step>

  <Step title="Go to Enhancements">
    Left sidebar > **Enhancements**. You'll see a report per schema type (Articles, Products, FAQ, etc.).
  </Step>

  <Step title="Watch for errors">
    Google crawls new pages and flags schema issues here. Check weekly after launching new schema; fixed errors usually clear within a week of a re-crawl.
  </Step>
</Steps>

## Verify It Worked

<Steps>
  <Step title="Validate via the Rich Results Test">
    Paste the URL of a page with schema. Confirm zero errors.
  </Step>

  <Step title="View the raw JSON-LD in the browser">
    Open the page, view source, search for `application/ld+json`. The script tag should contain your generated schema.
  </Step>

  <Step title="Wait for Google to index">
    Rich results take weeks to show up. Watch Search Console > Enhancements for indexing activity, and run occasional searches for your content.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Rich results not showing even though schema is valid">
    Rich results aren't guaranteed. Google considers content quality, site trust, and relevance. Also: it takes weeks to months for new schema to reflect in SERPs — be patient and monitor Search Console.
  </Accordion>

  <Accordion title="Validation errors in the Rich Results Test">
    Fix per the tool's guidance. Common errors: missing required properties (e.g., Article requires `headline`, `image`, `author`, `datePublished`), invalid dates (use ISO 8601), invalid URLs (must be absolute), incorrectly formatted prices (use string like `"29.99"`, not number).
  </Accordion>

  <Accordion title="Warnings about missing optional fields">
    Warnings are safe to ignore, but adding the recommended fields can unlock richer snippets. For Article, adding `publisher.logo` and `dateModified` tends to help.
  </Accordion>

  <Accordion title="Schema conflicts with page content">
    Google penalizes misleading schema. If your page says "In Stock" but the product is actually out of stock in your DB, fix one. Ensure schema is generated from the same data that renders the visible page — don't maintain them separately.
  </Accordion>

  <Accordion title="Multiple competing schemas on one page">
    You have schema from Site Enhancements AND your manual tags, and they disagree. Pick one source of truth — usually your manual tags win because they're more specific. Turn off redundant auto-generated schema or override it.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="SEO Basics" icon="magnifying-glass" href="/how-tos/seo">
    Titles, descriptions, sitemaps, and other on-page SEO
  </Card>

  <Card title="SEO Audit" icon="clipboard-check" href="/how-tos/seo-audit">
    Find gaps in your site's SEO coverage
  </Card>
</CardGroup>