---
name: schema-markup
version: 0.1.0
description: >
Use this skill when implementing structured data markup using JSON-LD and Schema.org
vocabulary for rich search results. Triggers on adding schema markup for FAQ, HowTo,
Product, Article, Breadcrumb, Organization, LocalBusiness, Event, Recipe, or any
Schema.org type. Covers JSON-LD implementation, Google Rich Results eligibility,
validation testing, and framework integration (Next.js, Nuxt, Astro).
category: marketing
tags: [seo, schema-markup, json-ld, structured-data, rich-snippets, schema-org]
recommended_skills: [technical-seo, seo-mastery, on-site-seo, ecommerce-seo]
platforms:
- claude-code
- gemini-cli
- openai-codex
- mcp
license: MIT
maintainers:
- github: maddhruv
---
When this skill is activated, always start your first response with the 🧢 emoji.
# Schema Markup / Structured Data
Schema markup is machine-readable context added to web pages that tells search engines
what your content *means*, not just what it *says*. JSON-LD (JavaScript Object Notation
for Linked Data) is Google's recommended implementation format - injected via a
`
```
Required fields for Product rich results: `name`, `image`, plus at least one of
`aggregateRating`, `offers`, or `review`. Always use `https://schema.org/` URLs
for `itemCondition` and `availability` values.
### Add FAQPage schema
Use `FAQPage` when the page contains a list of question-and-answer pairs where
the user is seeking answers (not a community Q&A page). Each question must appear
on the page - do not include hidden FAQ items.
```html
```
### Implement BreadcrumbList
Breadcrumbs in schema must match the breadcrumb navigation visible on the page.
Position values must start at 1 and increment sequentially.
```html
```
### Add Article schema for blog posts
Use `Article` for news and blog content, `BlogPosting` for blog-specific posts.
Both produce the same rich result treatment; `BlogPosting` is a subtype of `Article`.
```html
```
### Implement Organization / LocalBusiness schema
Place `Organization` on the homepage or about page. Use `LocalBusiness` (or a
more specific subtype like `Restaurant`, `MedicalBusiness`) for businesses with
a physical location.
```html
```
### Add HowTo schema
Use `HowTo` for step-by-step instructional content. Each step should have a
`name` (short step title) and `text` (detailed description). Steps can include
images for richer display.
```html
```
### Framework integration - Next.js App Router
In Next.js App Router, inject JSON-LD using a script tag inside the page component.
Do not use `next/head` for this - it is not needed for JSON-LD.
```tsx
// app/products/[slug]/page.tsx
export default function ProductPage({ product }: { product: Product }) {
const jsonLd = {
"@context": "https://schema.org",
"@type": "Product",
"name": product.name,
"description": product.description,
"offers": {
"@type": "Offer",
"price": product.price,
"priceCurrency": "USD",
"availability": "https://schema.org/InStock"
}
};
return (
<>
{/* page content */}
);
}
```
For Nuxt, use `useHead()` composable with a script entry. For Astro, inject the
script tag directly in the `.astro` component's `` slot. Both follow the
same pattern: serialize the object and inject as `type="application/ld+json"`.
---
## Gotchas
1. **Rich Results Test passes but nothing appears in SERPs** - Passing validation only confirms syntax correctness. Google still decides whether to display rich results based on content quality, query relevance, and site authority. Schema eligibility is not a guarantee of display.
2. **Product schema with dynamic pricing goes stale** - If `price` or `availability` are hardcoded in the template rather than dynamically rendered from live data, they drift out of sync. Google issues manual actions for misleading structured data. Always generate these fields server-side from live inventory.
3. **FAQPage on community Q&A pages triggers spam detection** - `FAQPage` is for single-author authoritative Q&A (e.g., a brand's own FAQ). Marking up a community forum or user-generated Q&A as `FAQPage` violates Google's guidelines and can result in the rich result being suppressed across the entire domain.
4. **Multiple `@type` blocks for the same entity cause conflicts** - Having two separate `` string (possible in user-generated content), it will break the JSON-LD block. Always sanitize dynamic strings or use a JSON serialization library that escapes special characters.
---
## Anti-patterns / common mistakes
| Mistake | Why it's wrong | What to do instead |
|---|---|---|
| Marking up hidden content | Google's guidelines prohibit schema for content not rendered to users. Penalizable as spam. | Only include data that is visible and readable on the page |
| Duplicate `@type` declarations | Multiple conflicting schema blocks for the same entity confuse parsers and waste crawl budget | Use one block per entity; combine supporting types in the same `