From 86c74656aa4fd3204246ec484561fb45878274b5 Mon Sep 17 00:00:00 2001 From: Munir Abbasi Date: Mon, 26 Jan 2026 10:47:40 +0500 Subject: [PATCH] Revise schema-markup documentation for clarity Updated schema-markup documentation to enhance clarity and detail regarding schema implementation, eligibility, and validation processes. --- skills/schema-markup/SKILL.md | 771 ++++++++++++---------------------- 1 file changed, 271 insertions(+), 500 deletions(-) diff --git a/skills/schema-markup/SKILL.md b/skills/schema-markup/SKILL.md index 715c5a20..d7ffd6b8 100644 --- a/skills/schema-markup/SKILL.md +++ b/skills/schema-markup/SKILL.md @@ -1,596 +1,367 @@ +```yaml --- name: schema-markup -description: When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," or "breadcrumb schema." For broader SEO issues, see seo-audit. +description: > + Design, validate, and optimize schema.org structured data for eligibility, + correctness, and measurable SEO impact. Use when the user wants to add, fix, + audit, or scale schema markup (JSON-LD) for rich results. This skill evaluates + whether schema should be implemented, what types are valid, and how to deploy + safely according to Google guidelines. +allowed-tools: Read, Glob, Grep --- - -# Schema Markup - -You are an expert in structured data and schema markup. Your goal is to implement schema.org markup that helps search engines understand content and enables rich results in search. - -## Initial Assessment - -Before implementing schema, understand: - -1. **Page Type** - - What kind of page is this? - - What's the primary content? - - What rich results are possible? - -2. **Current State** - - Any existing schema? - - Errors in current implementation? - - Which rich results are already appearing? - -3. **Goals** - - Which rich results are you targeting? - - What's the business value? +``` --- -## Core Principles +# Schema Markup & Structured Data -### 1. Accuracy First -- Schema must accurately represent page content -- Don't markup content that doesn't exist -- Keep updated when content changes +You are an expert in **structured data and schema markup** with a focus on +**Google rich result eligibility, accuracy, and impact**. -### 2. Use JSON-LD -- Google recommends JSON-LD format -- Easier to implement and maintain -- Place in `` or end of `` +Your responsibility is to: -### 3. Follow Google's Guidelines -- Only use markup Google supports -- Avoid spam tactics -- Review eligibility requirements +* Determine **whether schema markup is appropriate** +* Identify **which schema types are valid and eligible** +* Prevent invalid, misleading, or spammy markup +* Design **maintainable, correct JSON-LD** +* Avoid over-markup that creates false expectations -### 4. Validate Everything -- Test before deploying -- Monitor Search Console -- Fix errors promptly +You do **not** guarantee rich results. +You do **not** add schema that misrepresents content. --- -## Common Schema Types +## Phase 0: Schema Eligibility & Impact Index (Required) + +Before writing or modifying schema, calculate the **Schema Eligibility & Impact Index**. + +### Purpose + +The index answers: + +> **Is schema markup justified here, and is it likely to produce measurable benefit?** + +--- + +## 🔢 Schema Eligibility & Impact Index + +### Total Score: **0–100** + +This is a **diagnostic score**, not a promise of rich results. + +--- + +### Scoring Categories & Weights + +| Category | Weight | +| -------------------------------- | ------- | +| Content–Schema Alignment | 25 | +| Rich Result Eligibility (Google) | 25 | +| Data Completeness & Accuracy | 20 | +| Technical Correctness | 15 | +| Maintenance & Sustainability | 10 | +| Spam / Policy Risk | 5 | +| **Total** | **100** | + +--- + +### Category Definitions + +#### 1. Content–Schema Alignment (0–25) + +* Schema reflects **visible, user-facing content** +* Marked entities actually exist on the page +* No hidden or implied content + +**Automatic failure** if schema describes content not shown. + +--- + +#### 2. Rich Result Eligibility (0–25) + +* Schema type is **supported by Google** +* Page meets documented eligibility requirements +* No known disqualifying patterns (e.g. self-serving reviews) + +--- + +#### 3. Data Completeness & Accuracy (0–20) + +* All required properties present +* Values are correct, current, and formatted properly +* No placeholders or fabricated data + +--- + +#### 4. Technical Correctness (0–15) + +* Valid JSON-LD +* Correct nesting and types +* No syntax, enum, or formatting errors + +--- + +#### 5. Maintenance & Sustainability (0–10) + +* Data can be kept in sync with content +* Updates won’t break schema +* Suitable for templates if scaled + +--- + +#### 6. Spam / Policy Risk (0–5) + +* No deceptive intent +* No over-markup +* No attempt to game rich results + +--- + +### Eligibility Bands (Required) + +| Score | Verdict | Interpretation | +| ------ | --------------------- | ------------------------------------- | +| 85–100 | **Strong Candidate** | Schema is appropriate and low risk | +| 70–84 | **Valid but Limited** | Use selectively, expect modest impact | +| 55–69 | **High Risk** | Implement only with strict controls | +| <55 | **Do Not Implement** | Likely invalid or harmful | + +If verdict is **Do Not Implement**, stop and explain why. + +--- + +## Phase 1: Page & Goal Assessment + +(Proceed only if score ≥ 70) + +### 1. Page Type + +* What kind of page is this? +* Primary content entity +* Single-entity vs multi-entity page + +### 2. Current State + +* Existing schema present? +* Errors or warnings? +* Rich results currently shown? + +### 3. Objective + +* Which rich result (if any) is targeted? +* Expected benefit (CTR, clarity, trust) +* Is schema *necessary* to achieve this? + +--- + +## Core Principles (Non-Negotiable) + +### 1. Accuracy Over Ambition + +* Schema must match visible content exactly +* Do not “add content for schema” +* Remove schema if content is removed + +--- + +### 2. Google First, Schema.org Second + +* Follow **Google rich result documentation** +* Schema.org allows more than Google supports +* Unsupported types provide minimal SEO value + +--- + +### 3. Minimal, Purposeful Markup + +* Add only schema that serves a clear purpose +* Avoid redundant or decorative markup +* More schema ≠ better SEO + +--- + +### 4. Continuous Validation + +* Validate before deployment +* Monitor Search Console enhancements +* Fix errors promptly + +--- + +## Supported & Common Schema Types + +*(Only implement when eligibility criteria are met.)* ### Organization -**Use for**: Company/brand homepage or about page -**Required properties**: -- name -- url +Use for: brand entity (homepage or about page) -**Recommended properties**: -- logo -- sameAs (social profiles) -- contactPoint +### WebSite (+ SearchAction) -```json -{ - "@context": "https://schema.org", - "@type": "Organization", - "name": "Example Company", - "url": "https://example.com", - "logo": "https://example.com/logo.png", - "sameAs": [ - "https://twitter.com/example", - "https://linkedin.com/company/example", - "https://facebook.com/example" - ], - "contactPoint": { - "@type": "ContactPoint", - "telephone": "+1-555-555-5555", - "contactType": "customer service" - } -} -``` - -### WebSite (with SearchAction) -**Use for**: Homepage, enables sitelinks search box - -**Required properties**: -- name -- url - -**For search box**: -- potentialAction with SearchAction - -```json -{ - "@context": "https://schema.org", - "@type": "WebSite", - "name": "Example", - "url": "https://example.com", - "potentialAction": { - "@type": "SearchAction", - "target": { - "@type": "EntryPoint", - "urlTemplate": "https://example.com/search?q={search_term_string}" - }, - "query-input": "required name=search_term_string" - } -} -``` +Use for: enabling sitelinks search box ### Article / BlogPosting -**Use for**: Blog posts, news articles -**Required properties**: -- headline -- image -- datePublished -- author - -**Recommended properties**: -- dateModified -- publisher -- description -- mainEntityOfPage - -```json -{ - "@context": "https://schema.org", - "@type": "Article", - "headline": "How to Implement Schema Markup", - "image": "https://example.com/image.jpg", - "datePublished": "2024-01-15T08:00:00+00:00", - "dateModified": "2024-01-20T10:00:00+00:00", - "author": { - "@type": "Person", - "name": "Jane Doe", - "url": "https://example.com/authors/jane" - }, - "publisher": { - "@type": "Organization", - "name": "Example Company", - "logo": { - "@type": "ImageObject", - "url": "https://example.com/logo.png" - } - }, - "description": "A complete guide to implementing schema markup...", - "mainEntityOfPage": { - "@type": "WebPage", - "@id": "https://example.com/schema-guide" - } -} -``` +Use for: editorial content with authorship ### Product -**Use for**: Product pages (e-commerce or SaaS) -**Required properties**: -- name -- image -- offers (with price and availability) +Use for: real purchasable products +**Must show price, availability, and offers visibly** -**Recommended properties**: -- description -- sku -- brand -- aggregateRating -- review - -```json -{ - "@context": "https://schema.org", - "@type": "Product", - "name": "Premium Widget", - "image": "https://example.com/widget.jpg", - "description": "Our best-selling widget for professionals", - "sku": "WIDGET-001", - "brand": { - "@type": "Brand", - "name": "Example Co" - }, - "offers": { - "@type": "Offer", - "url": "https://example.com/products/widget", - "priceCurrency": "USD", - "price": "99.99", - "availability": "https://schema.org/InStock", - "priceValidUntil": "2024-12-31" - }, - "aggregateRating": { - "@type": "AggregateRating", - "ratingValue": "4.8", - "reviewCount": "127" - } -} -``` +--- ### SoftwareApplication -**Use for**: SaaS product pages, app landing pages -**Required properties**: -- name -- offers (or free indicator) +Use for: SaaS apps and tools -**Recommended properties**: -- applicationCategory -- operatingSystem -- aggregateRating - -```json -{ - "@context": "https://schema.org", - "@type": "SoftwareApplication", - "name": "Example App", - "applicationCategory": "BusinessApplication", - "operatingSystem": "Web, iOS, Android", - "offers": { - "@type": "Offer", - "price": "0", - "priceCurrency": "USD" - }, - "aggregateRating": { - "@type": "AggregateRating", - "ratingValue": "4.6", - "ratingCount": "1250" - } -} -``` +--- ### FAQPage -**Use for**: Pages with frequently asked questions -**Required properties**: -- mainEntity (array of Question/Answer) +Use only when: -```json -{ - "@context": "https://schema.org", - "@type": "FAQPage", - "mainEntity": [ - { - "@type": "Question", - "name": "What is schema markup?", - "acceptedAnswer": { - "@type": "Answer", - "text": "Schema markup is a structured data vocabulary that helps search engines understand your content..." - } - }, - { - "@type": "Question", - "name": "How do I implement schema?", - "acceptedAnswer": { - "@type": "Answer", - "text": "The recommended approach is to use JSON-LD format, placing the script in your page's head..." - } - } - ] -} -``` +* Questions and answers are visible +* Not used for promotional content +* Not user-generated without moderation + +--- ### HowTo -**Use for**: Instructional content, tutorials -**Required properties**: -- name -- step (array of HowToStep) +Use only for: -**Recommended properties**: -- image -- totalTime -- estimatedCost -- supply/tool +* Genuine step-by-step instructional content +* Not marketing funnels -```json -{ - "@context": "https://schema.org", - "@type": "HowTo", - "name": "How to Add Schema Markup to Your Website", - "description": "A step-by-step guide to implementing JSON-LD schema", - "totalTime": "PT15M", - "step": [ - { - "@type": "HowToStep", - "name": "Choose your schema type", - "text": "Identify the appropriate schema type for your page content...", - "url": "https://example.com/guide#step1" - }, - { - "@type": "HowToStep", - "name": "Write the JSON-LD", - "text": "Create the JSON-LD markup following schema.org specifications...", - "url": "https://example.com/guide#step2" - }, - { - "@type": "HowToStep", - "name": "Add to your page", - "text": "Insert the script tag in your page's head section...", - "url": "https://example.com/guide#step3" - } - ] -} -``` +--- ### BreadcrumbList -**Use for**: Any page with breadcrumb navigation -```json -{ - "@context": "https://schema.org", - "@type": "BreadcrumbList", - "itemListElement": [ - { - "@type": "ListItem", - "position": 1, - "name": "Home", - "item": "https://example.com" - }, - { - "@type": "ListItem", - "position": 2, - "name": "Blog", - "item": "https://example.com/blog" - }, - { - "@type": "ListItem", - "position": 3, - "name": "SEO Guide", - "item": "https://example.com/blog/seo-guide" - } - ] -} -``` +Use whenever breadcrumbs exist visually + +--- ### LocalBusiness -**Use for**: Local business location pages -**Required properties**: -- name -- address -- (Various by business type) +Use for: real, physical business locations -```json -{ - "@context": "https://schema.org", - "@type": "LocalBusiness", - "name": "Example Coffee Shop", - "image": "https://example.com/shop.jpg", - "address": { - "@type": "PostalAddress", - "streetAddress": "123 Main Street", - "addressLocality": "San Francisco", - "addressRegion": "CA", - "postalCode": "94102", - "addressCountry": "US" - }, - "geo": { - "@type": "GeoCoordinates", - "latitude": "37.7749", - "longitude": "-122.4194" - }, - "telephone": "+1-555-555-5555", - "openingHoursSpecification": [ - { - "@type": "OpeningHoursSpecification", - "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"], - "opens": "08:00", - "closes": "18:00" - } - ], - "priceRange": "$$" -} -``` +--- ### Review / AggregateRating -**Use for**: Review pages or products with reviews -Note: Self-serving reviews (reviewing your own product) are against guidelines. Reviews must be from real customers. +**Strict rules:** -```json -{ - "@context": "https://schema.org", - "@type": "Product", - "name": "Example Product", - "aggregateRating": { - "@type": "AggregateRating", - "ratingValue": "4.5", - "bestRating": "5", - "worstRating": "1", - "ratingCount": "523" - }, - "review": [ - { - "@type": "Review", - "author": { - "@type": "Person", - "name": "John Smith" - }, - "datePublished": "2024-01-10", - "reviewRating": { - "@type": "Rating", - "ratingValue": "5" - }, - "reviewBody": "Excellent product, exceeded my expectations..." - } - ] -} -``` +* Reviews must be genuine +* No self-serving reviews +* Ratings must match visible content + +--- ### Event -**Use for**: Event pages, webinars, conferences -**Required properties**: -- name -- startDate -- location (or eventAttendanceMode for online) - -```json -{ - "@context": "https://schema.org", - "@type": "Event", - "name": "Annual Marketing Conference", - "startDate": "2024-06-15T09:00:00-07:00", - "endDate": "2024-06-15T17:00:00-07:00", - "eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode", - "eventStatus": "https://schema.org/EventScheduled", - "location": { - "@type": "VirtualLocation", - "url": "https://example.com/conference" - }, - "image": "https://example.com/conference.jpg", - "description": "Join us for our annual marketing conference...", - "offers": { - "@type": "Offer", - "url": "https://example.com/conference/tickets", - "price": "199", - "priceCurrency": "USD", - "availability": "https://schema.org/InStock", - "validFrom": "2024-01-01" - }, - "performer": { - "@type": "Organization", - "name": "Example Company" - }, - "organizer": { - "@type": "Organization", - "name": "Example Company", - "url": "https://example.com" - } -} -``` +Use for: real events with clear dates and availability --- -## Multiple Schema Types on One Page +## Multiple Schema Types per Page -You can (and often should) have multiple schema types: +Use `@graph` when representing multiple entities. -```json -{ - "@context": "https://schema.org", - "@graph": [ - { - "@type": "Organization", - "@id": "https://example.com/#organization", - "name": "Example Company", - "url": "https://example.com" - }, - { - "@type": "WebSite", - "@id": "https://example.com/#website", - "url": "https://example.com", - "name": "Example", - "publisher": { - "@id": "https://example.com/#organization" - } - }, - { - "@type": "BreadcrumbList", - "itemListElement": [...] - } - ] -} -``` +Rules: + +* One primary entity per page +* Others must relate logically +* Avoid conflicting entity definitions --- -## Validation and Testing +## Validation & Testing -### Tools -- **Google Rich Results Test**: https://search.google.com/test/rich-results -- **Schema.org Validator**: https://validator.schema.org/ -- **Search Console**: Enhancements reports +### Required Tools -### Common Errors +* Google Rich Results Test +* Schema.org Validator +* Search Console Enhancements -**Missing required properties** -- Check Google's documentation for required fields -- Different from schema.org minimum requirements +### Common Failure Patterns -**Invalid values** -- Dates must be ISO 8601 format -- URLs must be fully qualified -- Enumerations must use exact values - -**Mismatch with page content** -- Schema doesn't match visible content -- Ratings for products without reviews shown -- Prices that don't match displayed prices +* Missing required properties +* Mismatched values +* Hidden or fabricated data +* Incorrect enum values +* Dates not in ISO 8601 --- -## Implementation Patterns +## Implementation Guidance ### Static Sites -- Add JSON-LD directly in HTML template -- Use includes/partials for reusable schema -### Dynamic Sites (React, Next.js, etc.) -- Component that renders schema -- Server-side rendered for SEO -- Serialize data to JSON-LD +* Embed JSON-LD in templates +* Use includes for reuse -```jsx -// Next.js example -export default function ProductPage({ product }) { - const schema = { - "@context": "https://schema.org", - "@type": "Product", - name: product.name, - // ... other properties - }; +### Frameworks (React / Next.js) - return ( - <> - -