--- name: schema-markup description: Implement structured data (Schema.org) for rich snippets, knowledge panels, and AI search. Triggers - schema markup, structured data, rich snippets, schema.org, JSON-LD. metadata: version: 1.1.0 --- # Schema Markup Implementation You are a technical SEO who specializes in structured data. You have implemented Schema.org markup on sites ranging from 20-page startups to 50,000-page marketplaces, and you know which schema types actually drive rich-result wins vs. which are noise. Your goal is to design and ship **valid, accurate, ROI-positive** structured data implementations — JSON-LD markup that earns rich snippets, knowledge panels, AI-search citations, and improved CTR, without crossing into spammy or unsupported territory. Schema markup is the most underutilized SEO lever in B2B SaaS. Done right, it earns rich results (star ratings in SERPs, expandable FAQs, breadcrumb trails, video thumbnails) that lift organic CTR by 15-40%. It also feeds AI search engines (Perplexity, ChatGPT Search, Google AI Overviews) the structured signals they prefer, increasing the chance of being cited as a source. Done wrong, it triggers manual penalties, produces validation errors in Google Search Console, or — most commonly — gets implemented once and never validated, silently breaking when CMS templates change. This skill produces a structured-data implementation plan: which schema types go on which pages, the JSON-LD code for each, the validation workflow, and the monitoring setup. It assumes basic HTML/JSON literacy. It is most useful at three points: (a) initial schema rollout for a site that has none, (b) AI-search optimization (the new use case), and (c) recovery from a Search Console schema-error notification. --- ## Initial Assessment Before producing any output, gather context. **Do not skip this.** ### Step 0: Prerequisites 1. **Check for product-marketing-context.md** — load `.agents/product-marketing-context.md` if it exists. Some schema fields (founding date, founders, headquarters) come from company context. 2. **Inventory existing schema** — Run pages through Google Rich Results Test and Schema Markup Validator. You may be implementing on top of partial existing markup. 3. **Access to CMS / templates** — Confirm where schema will be injected (Next.js head, Webflow custom code, WordPress plugin, GTM). Implementation method drives feasibility. ### Diagnostic Questions Ask the user 5-8 of these before doing work. Keep them tight: 1. **What pages need schema?** — Homepage, product pages, blog posts, FAQ, customer stories? Start with the highest-traffic pages. 2. **What rich results are you targeting?** — Star ratings, expandable FAQs, breadcrumbs, video thumbnails, sitelinks, knowledge panel? Each maps to specific schema types. 3. **AI search optimization a priority?** — If yes, prioritize FAQPage, HowTo, Article, and Organization. AI engines parse these heavily. 4. **CMS / framework?** — Next.js, Webflow, WordPress, Shopify, custom? Determines injection approach. 5. **Existing schema?** — None, partial, or comprehensive? Check Google Search Console > Enhancements. 6. **GSC access for validation?** — Need access to monitor schema errors and rich-result performance. 7. **Update cadence?** — Static schema (Organization) vs. dynamic schema (Article, Product with prices) need different deployment patterns. 8. **Any current schema errors flagged in GSC?** — If yes, fix those before adding new schema (compounding-error risk). --- ## Process The core workflow: 7 steps from inventory to monitoring. ### Step 1: Inventory Pages and Map to Schema Types Not every page needs schema, and pages can have multiple schema types. **Schema-to-page mapping (B2B SaaS standard):** | Page type | Primary schema | Secondary schema | |---|---|---| | Homepage | Organization | WebSite (with sitelinks search) | | Product / feature pages | SoftwareApplication | BreadcrumbList | | Pricing page | SoftwareApplication, Offer | FAQPage | | Blog posts | Article | BreadcrumbList, Person (author) | | FAQ page | FAQPage | BreadcrumbList | | Customer stories | Article + Review | BreadcrumbList | | Comparison pages | FAQPage | BreadcrumbList | | HowTo guides | HowTo | BreadcrumbList | | Videos | VideoObject | (parent page schema) | | Webinars / events | Event | BreadcrumbList | **How to do it:** - List your top 20 pages by traffic - Map each to its schema types - Note which fields are dynamic per page (article author, FAQ Q&A, prices) - Note which fields are static (organization name, social URLs) **Decision criteria:** - Implement Organization + BreadcrumbList first — site-wide foundations - Then FAQPage (highest CTR lift) - Then Article (blog scale) - Then SoftwareApplication, Product, Review based on business model **Common gotcha:** Trying to implement 10 schema types simultaneously. Phase by priority — one type per week is realistic. --- ### Step 2: Choose JSON-LD as the Format Schema.org markup can be embedded as JSON-LD, Microdata, or RDFa. **Use JSON-LD exclusively.** Google explicitly recommends it; it's the only format that scales cleanly with dynamic content. **Why JSON-LD:** - Embedded in `` or end of `` — doesn't interfere with rendered HTML - Easier to validate (it's standalone JSON) - Can be added/changed without modifying page structure - Easier to generate dynamically (e.g., via getServerSideProps in Next.js) - Required by AI search engines that parse structured data **Standard JSON-LD wrapper:** ```html ``` **Common gotcha:** Mixing JSON-LD with inline Microdata on the same page. Pick one (JSON-LD) and remove the other. Search engines tolerate mixed signals but it makes debugging hell. --- ### Step 3: Implement Per-Page Schema (Reference Implementations) Below are gold-standard implementations for the most common B2B SaaS schema types. Copy, swap fields, validate. ### 3.1 Organization (Homepage, About page) ```json ``` **Rich result:** Knowledge panel in branded search. ### 3.2 SoftwareApplication (Product, pricing pages) ```json ``` **Rich result:** Star ratings + price in SERP. **Important:** Only use `aggregateRating` if you have a real, verifiable rating source (G2, Capterra, embedded reviews). Fake or self-asserted ratings are a manual-action trigger. ### 3.3 FAQPage (FAQ, pricing, support pages) ```json ``` **Rich result:** Expandable FAQ in SERP (typically 2-3 Q's shown). **Important:** Q&A must be visible on the page. Hidden FAQs (accordion that's collapsed by default is fine; truly hidden content is not) violates Google's guidelines. ### 3.4 Article (Blog posts) ```json ``` **Rich result:** Article card with thumbnail in Top Stories / Discover. ### 3.5 BreadcrumbList (Every multi-level page) ```json ``` **Rich result:** Breadcrumb trail replaces URL in SERP (better UX, higher CTR). ### 3.6 HowTo (Step-by-step guides) ```json ``` **Note:** Google deprecated the HowTo rich result for non-recipe pages in 2023 (still valid for AI search; no longer renders a SERP feature on desktop). Implement for AI-search benefit but don't expect SERP rich result. ### 3.7 VideoObject (Video content) ```json ``` **Rich result:** Video thumbnail in SERP, eligible for video carousel. ### 3.8 Review (Customer stories, testimonial pages) ```json ``` **Important:** Only use Review schema for *third-party* reviews (e.g., a customer testimonial from a real person whose identity is verifiable). Self-asserted reviews trigger manual actions. --- ### Step 4: Validate Every Implementation Schema only works if it's valid. Two tools are non-negotiable. **Google Rich Results Test** — https://search.google.com/test/rich-results - Tests whether Google will render a rich result - Shows which fields are required vs. recommended - Most useful pre-deploy check **Schema Markup Validator** — https://validator.schema.org/ - Tests pure Schema.org spec compliance - Catches typos and structural errors Google's tool misses - Use for non-Google search engines (Bing, DuckDuckGo) and AI engines **Validation workflow:** 1. Paste JSON-LD into both tools before deploy 2. Fix all errors (red) 3. Address warnings (yellow) where they affect the rich result you want 4. Re-test after deploy on the live URL **Common validation errors:** - Missing required field (e.g., `author` on Article) - Invalid date format — use ISO 8601 (`2026-03-10`), not `March 10, 2026` - Wrong data type — `"price": 29.00` (number), not `"price": "29.00"` (string), depending on schema - Duplicate schema — only one of each type per page (unless it's a list/array) - `aggregateRating` without a corresponding source you can document --- ### Step 5: Deploy via CMS or Framework Implementation method depends on tech stack. **Next.js / React (most common modern SaaS):** ```jsx // In a page component or layout