Revise schema-markup documentation for clarity
Updated schema-markup documentation to enhance clarity and detail regarding schema implementation, eligibility, and validation processes.
This commit is contained in:
Munir Abbasi
@@ -1,596 +1,367 @@
|
|||||||
|
```yaml
|
||||||
---
|
---
|
||||||
name: schema-markup
|
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
|
You are an expert in **structured data and schema markup** with a focus on
|
||||||
- Schema must accurately represent page content
|
**Google rich result eligibility, accuracy, and impact**.
|
||||||
- Don't markup content that doesn't exist
|
|
||||||
- Keep updated when content changes
|
|
||||||
|
|
||||||
### 2. Use JSON-LD
|
Your responsibility is to:
|
||||||
- Google recommends JSON-LD format
|
|
||||||
- Easier to implement and maintain
|
|
||||||
- Place in `<head>` or end of `<body>`
|
|
||||||
|
|
||||||
### 3. Follow Google's Guidelines
|
* Determine **whether schema markup is appropriate**
|
||||||
- Only use markup Google supports
|
* Identify **which schema types are valid and eligible**
|
||||||
- Avoid spam tactics
|
* Prevent invalid, misleading, or spammy markup
|
||||||
- Review eligibility requirements
|
* Design **maintainable, correct JSON-LD**
|
||||||
|
* Avoid over-markup that creates false expectations
|
||||||
|
|
||||||
### 4. Validate Everything
|
You do **not** guarantee rich results.
|
||||||
- Test before deploying
|
You do **not** add schema that misrepresents content.
|
||||||
- Monitor Search Console
|
|
||||||
- Fix errors promptly
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 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
|
### Organization
|
||||||
**Use for**: Company/brand homepage or about page
|
|
||||||
|
|
||||||
**Required properties**:
|
Use for: brand entity (homepage or about page)
|
||||||
- name
|
|
||||||
- url
|
|
||||||
|
|
||||||
**Recommended properties**:
|
### WebSite (+ SearchAction)
|
||||||
- logo
|
|
||||||
- sameAs (social profiles)
|
|
||||||
- contactPoint
|
|
||||||
|
|
||||||
```json
|
Use for: enabling sitelinks search box
|
||||||
{
|
|
||||||
"@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"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Article / BlogPosting
|
### Article / BlogPosting
|
||||||
**Use for**: Blog posts, news articles
|
|
||||||
|
|
||||||
**Required properties**:
|
Use for: editorial content with authorship
|
||||||
- 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"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Product
|
### Product
|
||||||
**Use for**: Product pages (e-commerce or SaaS)
|
|
||||||
|
|
||||||
**Required properties**:
|
Use for: real purchasable products
|
||||||
- name
|
**Must show price, availability, and offers visibly**
|
||||||
- image
|
|
||||||
- offers (with price and availability)
|
|
||||||
|
|
||||||
**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
|
### SoftwareApplication
|
||||||
**Use for**: SaaS product pages, app landing pages
|
|
||||||
|
|
||||||
**Required properties**:
|
Use for: SaaS apps and tools
|
||||||
- name
|
|
||||||
- offers (or free indicator)
|
|
||||||
|
|
||||||
**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
|
### FAQPage
|
||||||
**Use for**: Pages with frequently asked questions
|
|
||||||
|
|
||||||
**Required properties**:
|
Use only when:
|
||||||
- mainEntity (array of Question/Answer)
|
|
||||||
|
|
||||||
```json
|
* Questions and answers are visible
|
||||||
{
|
* Not used for promotional content
|
||||||
"@context": "https://schema.org",
|
* Not user-generated without moderation
|
||||||
"@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..."
|
|
||||||
}
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### HowTo
|
### HowTo
|
||||||
**Use for**: Instructional content, tutorials
|
|
||||||
|
|
||||||
**Required properties**:
|
Use only for:
|
||||||
- name
|
|
||||||
- step (array of HowToStep)
|
|
||||||
|
|
||||||
**Recommended properties**:
|
* Genuine step-by-step instructional content
|
||||||
- image
|
* Not marketing funnels
|
||||||
- totalTime
|
|
||||||
- estimatedCost
|
|
||||||
- supply/tool
|
|
||||||
|
|
||||||
```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
|
### BreadcrumbList
|
||||||
**Use for**: Any page with breadcrumb navigation
|
|
||||||
|
|
||||||
```json
|
Use whenever breadcrumbs exist visually
|
||||||
{
|
|
||||||
"@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"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### LocalBusiness
|
### LocalBusiness
|
||||||
**Use for**: Local business location pages
|
|
||||||
|
|
||||||
**Required properties**:
|
Use for: real, physical business locations
|
||||||
- name
|
|
||||||
- address
|
|
||||||
- (Various by business type)
|
|
||||||
|
|
||||||
```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
|
### 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
|
* Reviews must be genuine
|
||||||
{
|
* No self-serving reviews
|
||||||
"@context": "https://schema.org",
|
* Ratings must match visible content
|
||||||
"@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..."
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Event
|
### Event
|
||||||
**Use for**: Event pages, webinars, conferences
|
|
||||||
|
|
||||||
**Required properties**:
|
Use for: real events with clear dates and availability
|
||||||
- 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"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 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
|
Rules:
|
||||||
{
|
|
||||||
"@context": "https://schema.org",
|
* One primary entity per page
|
||||||
"@graph": [
|
* Others must relate logically
|
||||||
{
|
* Avoid conflicting entity definitions
|
||||||
"@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": [...]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Validation and Testing
|
## Validation & Testing
|
||||||
|
|
||||||
### Tools
|
### Required Tools
|
||||||
- **Google Rich Results Test**: https://search.google.com/test/rich-results
|
|
||||||
- **Schema.org Validator**: https://validator.schema.org/
|
|
||||||
- **Search Console**: Enhancements reports
|
|
||||||
|
|
||||||
### Common Errors
|
* Google Rich Results Test
|
||||||
|
* Schema.org Validator
|
||||||
|
* Search Console Enhancements
|
||||||
|
|
||||||
**Missing required properties**
|
### Common Failure Patterns
|
||||||
- Check Google's documentation for required fields
|
|
||||||
- Different from schema.org minimum requirements
|
|
||||||
|
|
||||||
**Invalid values**
|
* Missing required properties
|
||||||
- Dates must be ISO 8601 format
|
* Mismatched values
|
||||||
- URLs must be fully qualified
|
* Hidden or fabricated data
|
||||||
- Enumerations must use exact values
|
* Incorrect enum values
|
||||||
|
* Dates not in ISO 8601
|
||||||
**Mismatch with page content**
|
|
||||||
- Schema doesn't match visible content
|
|
||||||
- Ratings for products without reviews shown
|
|
||||||
- Prices that don't match displayed prices
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Implementation Patterns
|
## Implementation Guidance
|
||||||
|
|
||||||
### Static Sites
|
### Static Sites
|
||||||
- Add JSON-LD directly in HTML template
|
|
||||||
- Use includes/partials for reusable schema
|
|
||||||
|
|
||||||
### Dynamic Sites (React, Next.js, etc.)
|
* Embed JSON-LD in templates
|
||||||
- Component that renders schema
|
* Use includes for reuse
|
||||||
- Server-side rendered for SEO
|
|
||||||
- Serialize data to JSON-LD
|
|
||||||
|
|
||||||
```jsx
|
### Frameworks (React / Next.js)
|
||||||
// Next.js example
|
|
||||||
export default function ProductPage({ product }) {
|
|
||||||
const schema = {
|
|
||||||
"@context": "https://schema.org",
|
|
||||||
"@type": "Product",
|
|
||||||
name: product.name,
|
|
||||||
// ... other properties
|
|
||||||
};
|
|
||||||
|
|
||||||
return (
|
* Server-side rendered JSON-LD
|
||||||
<>
|
* Data serialized directly from source
|
||||||
<Head>
|
|
||||||
<script
|
|
||||||
type="application/ld+json"
|
|
||||||
dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
|
|
||||||
/>
|
|
||||||
</Head>
|
|
||||||
{/* Page content */}
|
|
||||||
</>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### CMS / WordPress
|
### CMS / WordPress
|
||||||
- Plugins (Yoast, Rank Math, Schema Pro)
|
|
||||||
- Theme modifications
|
* Prefer structured plugins
|
||||||
- Custom fields to structured data
|
* Use custom fields for dynamic values
|
||||||
|
* Avoid hardcoded schema in themes
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Output Format
|
## Output Format (Required)
|
||||||
|
|
||||||
|
### Schema Strategy Summary
|
||||||
|
|
||||||
|
* Eligibility Index score + verdict
|
||||||
|
* Supported schema types
|
||||||
|
* Risks and constraints
|
||||||
|
|
||||||
|
### JSON-LD Implementation
|
||||||
|
|
||||||
### Schema Implementation
|
|
||||||
```json
|
```json
|
||||||
// Full JSON-LD code block
|
|
||||||
{
|
{
|
||||||
"@context": "https://schema.org",
|
"@context": "https://schema.org",
|
||||||
"@type": "...",
|
"@type": "...",
|
||||||
// Complete markup
|
...
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Placement Instructions
|
### Placement Instructions
|
||||||
Where to add the code and how
|
|
||||||
|
|
||||||
### Testing Checklist
|
Where and how to add it
|
||||||
- [ ] Validates in Rich Results Test
|
|
||||||
- [ ] No errors or warnings
|
### Validation Checklist
|
||||||
- [ ] Matches page content
|
|
||||||
- [ ] All required properties included
|
* [ ] Valid JSON-LD
|
||||||
|
* [ ] Passes Rich Results Test
|
||||||
|
* [ ] Matches visible content
|
||||||
|
* [ ] Meets Google eligibility rules
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Questions to Ask
|
## Questions to Ask (If Needed)
|
||||||
|
|
||||||
If you need more context:
|
1. What content is visible on the page?
|
||||||
1. What type of page is this?
|
2. Which rich result are you targeting (if any)?
|
||||||
2. What rich results are you hoping to achieve?
|
3. Is this content templated or editorial?
|
||||||
3. What data is available to populate the schema?
|
4. How is this data maintained?
|
||||||
4. Is there existing schema on the page?
|
5. Is schema already present?
|
||||||
5. What's your tech stack for implementation?
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **seo-audit**: For overall SEO including schema review
|
* **seo-audit** – Full SEO review including schema
|
||||||
- **programmatic-seo**: For templated schema at scale
|
* **programmatic-seo** – Templated schema at scale
|
||||||
- **analytics-tracking**: For measuring rich result impact
|
* **analytics-tracking** – Measure rich result impact
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
Just say the word.
|
||||||
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user