---
name: "SEO schema"
repo: https://github.com/agricidaniel/claude-seo
source: https://github.com/agricidaniel/claude-seo/blob/HEAD/skills/seo-schema/SKILL.md
license: "MIT"
install: "npx skills add agricidaniel/claude-seo --skill seo-schema"
page: https://100xlab.com/resources/agent-skills/agricidaniel-claude-seo--seo-schema--s5f7a9
---

# Schema Markup Analysis & Generation

## Detection

1. Scan page source for JSON-LD `<script type="application/ld+json">`
2. Check for Microdata (`itemscope`, `itemprop`)
3. Check for RDFa (`typeof`, `property`)
4. Always recommend JSON-LD as primary format (Google's stated preference)

## Validation

- Check required properties per schema type
- Validate against Google's supported rich result types
- Test for common errors:
  - Missing @context
  - Invalid @type
  - Wrong data types
  - Placeholder text
  - Relative URLs (should be absolute)
  - Invalid date formats
- Flag deprecated types (see below)

## Schema Type Status (as of May 2026)

Read `references/schema-types.md` for the full list. Key rules:

### ACTIVE (recommend freely):
Organization, LocalBusiness, SoftwareApplication, WebApplication, Product (with Certification markup as of April 2025), ProductGroup, Offer, Service, Article, BlogPosting, NewsArticle, Review, AggregateRating, BreadcrumbList, WebSite, WebPage, Person, ProfilePage, ContactPage, VideoObject, ImageObject, Event, JobPosting, Course, DiscussionForumPosting

### VIDEO & SPECIALIZED (recommend freely):
BroadcastEvent, Clip, SeekToAction, SoftwareSourceCode

See `schema/templates.json` for ready-to-use JSON-LD templates for these types.

> **JSON-LD and JavaScript rendering:** Per Google's December 2025 JS SEO guidance, structured data injected via JavaScript may face delayed processing. For time-sensitive markup (especially Product, Offer), include JSON-LD in the initial server-rendered HTML.

### NO RICH RESULTS — KEEP FOR AI:
- **FAQPage**: Google retired FAQ rich results for ALL sites on May 7, 2026 (supersedes the Aug 2023 gov/health restriction). No SERP feature anymore — but flag existing FAQPage at Info (not Critical), since the markup still aids AI Mode / AI Overviews entity resolution. For genuine user Q&A pages, use **QAPage**.

### DEPRECATED (never recommend):
- **HowTo**: Rich results removed September 2023
- **SpecialAnnouncement**: Deprecated July 31, 2025
- **CourseInfo, EstimatedSalary, LearningVideo**: Retired June 2025
- **ClaimReview**: Retired from rich results June 2025
- **VehicleListing**: Retired from rich results June 2025
- **Practice Problem**: Retired from rich results late 2025
- **Dataset**: Retired from rich results late 2025
- **Book Actions**: Deprecated then reversed, still functional as of Feb 2026 (historical note)

## Generation

When generating schema for a page:
1. Identify page type from content analysis
2. Select appropriate schema type(s)
3. Generate valid JSON-LD with all required + recommended properties
4. Include only truthful, verifiable data. Use placeholders clearly marked for user to fill
5. Validate output before presenting

## Common Schema Templates

### Organization
```json
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "[Company Name]",
  "url": "[Website URL]",
  "logo": "[Logo URL]",
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "[Phone]",
    "contactType": "customer service"
  },
  "sameAs": [
    "[Facebook URL]",
    "[LinkedIn URL]",
    "[Twitter URL]"
  ]
}
```

### LocalBusiness
```json
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "[Business Name]",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "[Street]",
    "addressLocality": "[City]",
    "addressRegion": "[State]",
    "postalCode": "[ZIP]",
    "addressCountry": "US"
  },
  "telephone": "[Phone]",
  "openingHours": "Mo-Fr 09:00-17:00",
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": "[Lat]",
    "longitude": "[Long]"
  }
}
```

### Article/BlogPosting
```json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "[Title]",
  "author": {
    "@type": "Person",
    "name": "[Author Name]"
  },
  "datePublished": "[YYYY-MM-DD]",
  "dateModified": "[YYYY-MM-DD]",
  "image": "[Image URL]",
  "publisher": {
    "@type": "Organization",
    "name": "[Publisher]",
    "logo": {
      "@type": "ImageObject",
      "url": "[Logo URL]"
    }
  }
}
```

## Output

- `SCHEMA-REPORT.md`: detection and validation results
- `generated-schema.json`: ready-to-use JSON-LD snippets

### Validation Results
| Schema | Type | Status | Issues |
|--------|------|--------|--------|
| ... | ... | ✅/⚠️/❌ | ... |

### Recommendations
- Missing schema opportunities
- Validation fixes needed
- Generated code for implementation

## Error Handling

| Scenario | Action |
|----------|--------|
| URL unreachable | Report connection error with status code. Suggest verifying URL and checking if the page requires authentication. |
| No schema markup found | Report that no JSON-LD, Microdata, or RDFa was detected. Recommend appropriate schema types based on page content analysis. |
| Invalid JSON-LD syntax | Parse and report specific syntax errors (missing brackets, trailing commas, unquoted keys). Provide corrected JSON-LD output. |
| Deprecated schema type detected | Flag the deprecated type with its retirement date. Recommend the current replacement type or advise removal if no replacement exists. |

---

## Supporting file: LICENSE.txt

```text
MIT License - see repository root LICENSE file for complete terms.

Copyright (c) 2026 AgriciDaniel
https://github.com/AgriciDaniel/claude-seo
```

---

## Supporting file: references/deprecated-types-2024-2026.md

# Deprecated Schema.org rich result types (2024–2026)

Authoritative reference for every rich result Google retired during the
2024–2025 cleanup. Whenever a user asks for one of these, the
`seo-schema` skill must explain that the type is deprecated and either
redirect to an active alternative or note that no replacement exists.

## Retired June 19, 2025

Announced at
[Simplifying our Search rich results](https://developers.google.com/search/blog/2025/06/simplifying-search-results)
(developers.google.com/search/blog).

| Type | Retired | Notes |
|---|---|---|
| **Vehicle Listing** (`@type: VehicleListing` / `Vehicle`) | June 2025 | No replacement. Google no longer renders dealer inventory rich cards. Use regular `Product` schema if the listing is sold online. |
| **Claim Review** (`@type: ClaimReview`) | June 2025 | No replacement. The fact-check rich result was the main consumer of ClaimReview; without it, the markup has no SERP effect. ClaimReview *the vocabulary* is still in schema.org, but Google ignores it. |
| **Estimated Salary** (`@type: EstimatedSalary` / `OccupationalAggregateRating`) | June 2025 | No replacement. `JobPosting` remains live for individual jobs. |
| **Learning Video** | June 2025 | No replacement. The generic `VideoObject` rich result still renders. |
| **Course Info carousel** | June 2025 | The carousel variant retired. The single-result `Course` rich card is still live. When asked for "Course Info", verify whether the user wants the carousel (dead) or the live single-result variant. |

## Retired July 31, 2025

| Type | Retired | Notes |
|---|---|---|
| **Special Announcement** (`@type: SpecialAnnouncement`) | July 2025 | The COVID-era emergency-info card was deprecated. No replacement. |

## Earlier (pre-v2 baseline) retirements

These are listed for completeness so the LLM doesn't suggest them.

| Type | Retired | Notes |
|---|---|---|
| **HowTo** (`@type: HowTo`) | September 2023 | Rich result removed from desktop and mobile. The vocabulary remains but produces no SERP feature. Some sites still use HowTo for AI citation legibility — that's a defensible reason to keep it, but flag it as "no SERP effect". |
| **FAQ** (`@type: FAQPage`) | Aug 2023 (restricted); **May 7, 2026 (fully retired)** | Rich results fully retired for **all** sites on May 7, 2026 — this supersedes the 2023 gov/health restriction. Rich Results Test/report support drops Jun 2026; Search Console API Aug 2026. Flag existing FAQPage as Info (not Critical) because it still helps AI/LLM citation as an entity signal; do **not** recommend removal or new FAQPage for SERP benefit. For genuine single-question pages, use `QAPage`. |

## Replacement decision table

When generating schema, prefer these alternatives:

| Asked for | Replacement |
|---|---|
| `ClaimReview` | None — explain rich result is dead; suggest `Article` with `dateline` if news context. |
| `EstimatedSalary` | `JobPosting` with `baseSalary` for specific roles. |
| `LearningVideo` | `VideoObject` (still live). |
| `Course Info` carousel | Single `Course` rich card (still live). |
| `SpecialAnnouncement` | `Event` if time-bounded; otherwise `Article` or `WebPage`. |
| `VehicleListing` | `Product` with vehicle-specific properties. |
| `HowTo` (for SERP) | None — explain the rich result is dead. Suggest article structure with clear `<h2>` step headings if the goal is comprehension; ranking benefit is no longer schema-driven. |
| `FAQPage` (for SERP) | None — rich results retired May 2026. Keep the markup for AI citation; use `QAPage` for genuine user-submitted Q&A pages. |

## Primary sources

- Google retirement announcement (June 2025): https://developers.google.com/search/blog/2025/06/simplifying-search-results
- Special Announcement deprecation (July 2025): https://developers.google.com/search/blog
- HowTo retirement (September 2023): https://developers.google.com/search/blog/2023/09/structured-data-changes
- FAQ restriction (August 2023): https://developers.google.com/search/blog/2023/08/howto-faq-changes
- FAQ rich result retirement (May 7, 2026): https://developers.google.com/search/docs/appearance/structured-data/faqpage

Last verified against developers.google.com: 2026-05-25.

---

## Supporting file: schema/templates.json

```json
{
  "templates": [
    {
      "type": "VideoObject",
      "description": "Video content pages with thumbnails, duration, and playback URLs. Enables video rich results in Google Search.",
      "template": {
        "@context": "https://schema.org",
        "@type": "VideoObject",
        "name": "[Video Title]",
        "description": "[Video Description]",
        "thumbnailUrl": "[Thumbnail Image URL]",
        "uploadDate": "[YYYY-MM-DD]",
        "duration": "[ISO 8601 Duration, e.g. PT1H30M]",
        "contentUrl": "[Direct Video File URL]",
        "embedUrl": "[Embed Player URL]",
        "publisher": {
          "@type": "Organization",
          "name": "[Publisher Name]",
          "logo": {
            "@type": "ImageObject",
            "url": "[Logo URL]"
          }
        }
      }
    },
    {
      "type": "BroadcastEvent",
      "description": "Live streaming content for LIVE badge in Google Search results. Requires VideoObject and isLiveBroadcast flag.",
      "template": {
        "@context": "https://schema.org",
        "@type": "VideoObject",
        "name": "[Live Stream Title]",
        "description": "[Live Stream Description]",
        "thumbnailUrl": "[Thumbnail Image URL]",
        "uploadDate": "[YYYY-MM-DD]",
        "contentUrl": "[Stream URL]",
        "embedUrl": "[Embed Player URL]",
        "publication": {
          "@type": "BroadcastEvent",
          "isLiveBroadcast": true,
          "startDate": "[YYYY-MM-DDTHH:MM:SSZ]",
          "endDate": "[YYYY-MM-DDTHH:MM:SSZ]"
        }
      }
    },
    {
      "type": "Clip",
      "description": "Key moments or chapters within a video. Enables key moments rich results with timestamp links.",
      "template": {
        "@context": "https://schema.org",
        "@type": "VideoObject",
        "name": "[Video Title]",
        "description": "[Video Description]",
        "thumbnailUrl": "[Thumbnail Image URL]",
        "uploadDate": "[YYYY-MM-DD]",
        "contentUrl": "[Direct Video File URL]",
        "hasPart": [
          {
            "@type": "Clip",
            "name": "[Clip Title]",
            "startOffset": 0,
            "endOffset": 120,
            "url": "[Video URL with timestamp, e.g. ?t=0]"
          },
          {
            "@type": "Clip",
            "name": "[Next Clip Title]",
            "startOffset": 120,
            "endOffset": 300,
            "url": "[Video URL with timestamp, e.g. ?t=120]"
          }
        ]
      }
    },
    {
      "type": "SeekToAction",
      "description": "Enable seek functionality in video rich results. Allows users to jump to specific timestamps from search.",
      "template": {
        "@context": "https://schema.org",
        "@type": "VideoObject",
        "name": "[Video Title]",
        "description": "[Video Description]",
        "thumbnailUrl": "[Thumbnail Image URL]",
        "uploadDate": "[YYYY-MM-DD]",
        "contentUrl": "[Direct Video File URL]",
        "potentialAction": {
          "@type": "SeekToAction",
          "target": "[Video URL]?t={seek_to_second_number}",
          "startOffset-input": "required name=seek_to_second_number"
        }
      }
    },
    {
      "type": "SoftwareSourceCode",
      "description": "Open source and code repository pages. Describes programming language, platform, and repository location.",
      "template": {
        "@context": "https://schema.org",
        "@type": "SoftwareSourceCode",
        "name": "[Repository Name]",
        "description": "[Repository Description]",
        "codeRepository": "[Repository URL, e.g. https://github.com/org/repo]",
        "programmingLanguage": "[Language, e.g. Python]",
        "runtimePlatform": "[Platform, e.g. Node.js]",
        "author": {
          "@type": "Person",
          "name": "[Author Name]"
        },
        "license": "[License URL, e.g. https://opensource.org/licenses/MIT]",
        "dateCreated": "[YYYY-MM-DD]",
        "dateModified": "[YYYY-MM-DD]"
      }
    },
    {
      "type": "ProductGroup",
      "description": "E-commerce product variants grouped by attributes like size, color. Enables variant-aware rich results with variesBy and hasVariant properties.",
      "template": {
        "@context": "https://schema.org",
        "@type": "ProductGroup",
        "name": "[Product Name]",
        "description": "[Product group description]",
        "productGroupID": "[product-group-id]",
        "variesBy": ["https://schema.org/size", "https://schema.org/color"],
        "hasVariant": [
          {
            "@type": "Product",
            "name": "[Variant - Red, Large]",
            "sku": "[SKU-001]",
            "color": "[Red]",
            "size": "[Large]",
            "offers": {
              "@type": "Offer",
              "price": "[29.99]",
              "priceCurrency": "USD",
              "availability": "https://schema.org/InStock"
            }
          }
        ]
      }
    },
    {
      "type": "ProfilePage",
      "description": "Author, creator, or team member profile pages. Enhances E-E-A-T signals with mainEntity Person markup and sameAs links.",
      "template": {
        "@context": "https://schema.org",
        "@type": "ProfilePage",
        "mainEntity": {
          "@type": "Person",
          "name": "[Author Name]",
          "url": "[Profile URL]",
          "description": "[Author bio and expertise summary]",
          "sameAs": [
            "[Twitter URL]",
            "[LinkedIn URL]"
          ]
        }
      }
    },
    {
      "type": "Certification",
      "description": "Product certifications (Energy Star, safety, organic, etc.). Replaced EnergyConsumptionDetails in April 2025.",
      "template": {
        "@context": "https://schema.org",
        "@type": "Product",
        "name": "[Product Name]",
        "hasCertification": {
          "@type": "Certification",
          "certificationIdentification": "[Certification Name, e.g. Energy Star]",
          "issuedBy": {
            "@type": "Organization",
            "name": "[Issuing Organization, e.g. EPA]"
          }
        }
      }
    },
    {
      "type": "OfferShippingDetails",
      "description": "Shipping and delivery information for e-commerce products. Includes shipping rate, handling time, and transit time.",
      "template": {
        "@context": "https://schema.org",
        "@type": "Product",
        "name": "[Product Name]",
        "offers": {
          "@type": "Offer",
          "price": "[Price]",
          "priceCurrency": "USD",
          "shippingDetails": {
            "@type": "OfferShippingDetails",
            "shippingRate": {
              "@type": "MonetaryAmount",
              "value": "[0]",
              "currency": "USD"
            },
            "deliveryTime": {
              "@type": "ShippingDeliveryTime",
              "handlingTime": {
                "@type": "QuantitativeValue",
                "minValue": 0,
                "maxValue": 1,
                "unitCode": "DAY"
              },
              "transitTime": {
                "@type": "QuantitativeValue",
                "minValue": 1,
                "maxValue": 5,
                "unitCode": "DAY"
              }
            }
          }
        }
      }
    },
    {
      "type": "Product (Full E-commerce)",
      "description": "Complete e-commerce product page with pricing, availability, reviews, brand, and offers. Enables product rich results in Google Search. Added in v1.9.0 for seo-ecommerce.",
      "template": {
        "@context": "https://schema.org",
        "@type": "Product",
        "name": "[Product Name]",
        "description": "[Product Description]",
        "image": "[Product Image URL]",
        "sku": "[SKU]",
        "brand": {
          "@type": "Brand",
          "name": "[Brand Name]"
        },
        "offers": {
          "@type": "Offer",
          "price": "[Price]",
          "priceCurrency": "[Currency Code, e.g. USD]",
          "availability": "https://schema.org/InStock",
          "url": "[Product Page URL]",
          "priceValidUntil": "[YYYY-MM-DD]",
          "hasMerchantReturnPolicy": {
            "@type": "MerchantReturnPolicy",
            "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
            "merchantReturnDays": 30
          },
          "shippingDetails": {
            "@type": "OfferShippingDetails",
            "shippingRate": {
              "@type": "MonetaryAmount",
              "value": "[Shipping Cost]",
              "currency": "[Currency Code]"
            }
          }
        },
        "aggregateRating": {
          "@type": "AggregateRating",
          "ratingValue": "[Average Rating]",
          "reviewCount": "[Number of Reviews]"
        }
      }
    },
    {
      "type": "ItemList",
      "description": "Hub/pillar pages listing related content items. Used for content cluster landing pages, resource directories, and top-N lists. Added in v1.9.0 for seo-cluster.",
      "template": {
        "@context": "https://schema.org",
        "@type": "ItemList",
        "name": "[Hub Page Title]",
        "description": "[Hub Page Description]",
        "numberOfItems": "[Count]",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "url": "[Spoke Page URL]",
            "name": "[Spoke Page Title]"
          }
        ]
      }
    }
  ]
}
```