Schema Markup
Implement schema.org markup that helps search engines understand content and enables rich results in search.
Installation
OpenClaw / Moltbot / Clawbot
CODEBLOCK0
When to Use
- - Adding structured data to new or existing pages
- Fixing schema validation errors
- Optimizing for specific rich results (FAQ, product, article)
- Implementing JSON-LD in React/Next.js applications
- Auditing existing schema markup
Initial Assessment
Before implementing schema, understand:
- 1. Page Type — What kind of page? What's the primary content? What rich results are possible?
- Current State — Any existing schema? Errors? Which rich results already appearing?
- Goals — Which rich results are you targeting? What's the business value?
Core Principles
1. Accuracy First
- - Schema must accurately represent page content
- Don't markup content that doesn't exist on the page
- Keep updated when content changes
2. Use JSON-LD
- - Google recommends JSON-LD format
- Easier to implement and maintain than microdata or RDFa
- Place in
<head> or before INLINECODE1
3. Follow Google's Guidelines
- - Only use markup Google supports for rich results
- Avoid spam tactics
- Review eligibility requirements for each type
4. Validate Everything
- - Test before deploying
- Monitor Search Console enhancement reports
- Fix errors promptly
Common Schema Types
| Type | Use For | Required Properties |
|---|
| Organization | Company homepage/about | name, url |
| WebSite |
Homepage (search box) | name, url |
| Article | Blog posts, news | headline, image, datePublished, author |
| Product | Product pages | name, image, offers |
| SoftwareApplication | SaaS/app pages | name, offers |
| FAQPage | FAQ content | mainEntity (Q&A array) |
| HowTo | Tutorials | name, step |
| BreadcrumbList | Any page with breadcrumbs | itemListElement |
| LocalBusiness | Local business pages | name, address |
| Event | Events, webinars | name, startDate, location |
For complete JSON-LD examples with required/recommended field annotations: See INLINECODE2
Quick Reference
Organization (Company Page)
Required: name, url
Recommended: logo, sameAs (social profiles), contactPoint
Article/BlogPosting
Required: headline, image, datePublished, author
Recommended: dateModified, publisher, description
Product
Required: name, image, offers (price + availability)
Recommended: sku, brand, aggregateRating, review
FAQPage
Required: mainEntity (array of Question/Answer pairs)
BreadcrumbList
Required: itemListElement (array with position, name, item)
Multiple Schema Types
Combine multiple schema types on one page using @graph:
CODEBLOCK1
Use @id to create referenceable entities — define once, reference elsewhere with { "@id": "..." }.
Validation and Testing
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
| Error | Cause | Fix |
|---|
| Missing required field | Required property not included | Add the missing property |
| Invalid URL |
Relative URL or malformed | Use fully qualified URLs (
https://...) |
| Invalid date format | Not ISO 8601 | Use
YYYY-MM-DDTHH:MM:SS+00:00 |
| Invalid enum value | Wrong enumeration value | Use exact schema.org URLs (e.g.,
https://schema.org/InStock) |
| Content mismatch | Schema doesn't match visible content | Ensure schema reflects actual page content |
| Invalid price | Currency symbol or commas included | Use numeric value only (
"149.99") |
Implementation
Static Sites
- - Add JSON-LD directly in HTML template
- Use includes/partials for reusable schema
Dynamic Sites (React, Next.js)
CODEBLOCK2
CMS / WordPress
- - Plugins: Yoast, Rank Math, Schema Pro
- Theme modifications for custom types
- Custom fields mapped to structured data
Testing Checklist
- - [ ] Validates in Rich Results Test with no errors
- [ ] No warnings for recommended properties
- [ ] Schema content matches visible page content
- [ ] All required properties included for each type
- [ ] URLs are fully qualified
- [ ] Dates are ISO 8601 format
- [ ] Prices are numeric without currency symbols
Task-Specific Questions
Before implementing, gather answers to:
- 1. What type of page is this? (product, article, FAQ, local business)
- What rich results are you targeting? (FAQ dropdown, product stars, breadcrumbs)
- What data is available to populate the schema? (prices, ratings, dates)
- Is there existing schema on the page? (check with Rich Results Test first)
- What's your tech stack? (static HTML, React/Next.js, CMS/WordPress)
Implementation Workflow
- 1. Identify page types — map your site's pages to schema types
- Start with homepage — Organization + WebSite schema
- Add per-page schema — Article for blog, Product for shop, etc.
- Add BreadcrumbList — every page with navigation breadcrumbs
- Validate each page — Rich Results Test before and after
- Monitor Search Console — check enhancement reports weekly after launch
NEVER Do
- 1. NEVER add schema for content that doesn't exist on the page — this violates Google's guidelines and risks penalties
- NEVER use microdata or RDFa when JSON-LD is an option — JSON-LD is easier to maintain and Google's recommended format
- NEVER hardcode schema that should be dynamic — product prices, availability, and ratings must reflect current data
- NEVER skip validation before deploying — invalid schema is worse than no schema; it wastes crawl budget
- NEVER mark up every page identically — each page type needs its own appropriate schema types
- NEVER ignore Search Console errors — schema errors can cause rich results to disappear entirely
Schema Markup
实现 schema.org 标记，帮助搜索引擎理解内容，并在搜索结果中启用丰富结果。
安装
OpenClaw / Moltbot / Clawbot
bash
npx clawhub@latest install schema-markup
使用时机
- - 为新建或现有页面添加结构化数据
- 修复 Schema 验证错误
- 针对特定丰富结果（FAQ、产品、文章）进行优化
- 在 React/Next.js 应用中实现 JSON-LD
- 审计现有 Schema 标记
初始评估
在实施 Schema 之前，需要了解：
- 1. 页面类型 — 这是什么类型的页面？主要内容是什么？可能实现哪些丰富结果？
- 当前状态 — 是否存在现有 Schema？是否有错误？哪些丰富结果已显示？
- 目标 — 你希望实现哪些丰富结果？商业价值是什么？
核心原则
1. 准确性优先
- - Schema 必须准确反映页面内容
- 不要标记页面上不存在的内容
- 内容变更时及时更新
2. 使用 JSON-LD
- - Google 推荐使用 JSON-LD 格式
- 比微数据或 RDFa 更易于实现和维护
- 放置在 或 之前
3. 遵循 Google 指南
- - 仅使用 Google 支持用于丰富结果的标记
- 避免作弊手段
- 检查每种类型的资格要求
4. 全面验证
- - 部署前进行测试
- 监控 Search Console 增强报告
- 及时修复错误
常见 Schema 类型
| 类型 | 用途 | 必需属性 |
|---|
| Organization | 公司主页/关于我们 | name, url |
| WebSite |
首页（搜索框） | name, url |
| Article | 博客文章、新闻 | headline, image, datePublished, author |
| Product | 产品页面 | name, image, offers |
| SoftwareApplication | SaaS/应用页面 | name, offers |
| FAQPage | FAQ 内容 | mainEntity（问答数组） |
| HowTo | 教程 | name, step |
| BreadcrumbList | 任何带面包屑导航的页面 | itemListElement |
| LocalBusiness | 本地商家页面 | name, address |
| Event | 活动、网络研讨会 | name, startDate, location |
如需包含必需/推荐字段注释的完整 JSON-LD 示例：请参阅 references/schema-examples.md
快速参考
Organization（公司页面）
必需：name, url
推荐：logo, sameAs（社交媒体资料）, contactPoint
Article/BlogPosting（文章/博客）
必需：headline, image, datePublished, author
推荐：dateModified, publisher, description
Product（产品）
必需：name, image, offers（价格 + 库存状态）
推荐：sku, brand, aggregateRating, review
FAQPage（常见问题页面）
必需：mainEntity（Question/Answer 对数组）
BreadcrumbList（面包屑导航）
必需：itemListElement（包含 position, name, item 的数组）
多种 Schema 类型
使用 @graph 在一个页面上组合多种 Schema 类型：
json
{
@context: https://schema.org,
@graph: [
{ @type: Organization, ... : ... },
{ @type: WebSite, ... : ... },
{ @type: BreadcrumbList, ... : ... }
]
}
使用 @id 创建可引用的实体 — 定义一次，在其他地方使用 { @id: ... } 引用。
验证与测试
工具
- - Google 丰富结果测试：https://search.google.com/test/rich-results
- Schema.org 验证器：https://validator.schema.org/
- Search Console：增强报告
常见错误
| 错误 | 原因 | 修复方法 |
|---|
| 缺少必需字段 | 未包含必需属性 | 添加缺失的属性 |
| URL 无效 |
相对 URL 或格式错误 | 使用完整 URL（https://...） |
| 日期格式无效 | 非 ISO 8601 格式 | 使用 YYYY-MM-DDTHH:MM:SS+00:00 |
| 枚举值无效 | 错误的枚举值 | 使用精确的 schema.org URL（例如 https://schema.org/InStock） |
| 内容不匹配 | Schema 与可见内容不符 | 确保 Schema 反映实际页面内容 |
| 价格无效 | 包含货币符号或逗号 | 仅使用数值（149.99） |
实施方法
静态网站
- - 直接在 HTML 模板中添加 JSON-LD
- 使用包含/局部模板实现可复用的 Schema
动态网站（React, Next.js）
tsx
export function JsonLd({ data }: { data: Record }) {
return (
type=application/ld+json
dangerouslySetInnerHTML={{ html: JSON.stringify(data) }}
/>
);
}
CMS / WordPress
- - 插件：Yoast、Rank Math、Schema Pro
- 针对自定义类型的主题修改
- 将自定义字段映射到结构化数据
测试清单
- - [ ] 在丰富结果测试中验证通过，无错误
- [ ] 推荐属性无警告
- [ ] Schema 内容与可见页面内容匹配
- [ ] 每种类型都包含所有必需属性
- [ ] URL 为完整格式
- [ ] 日期为 ISO 8601 格式
- [ ] 价格为数值，不含货币符号
任务特定问题
实施前，收集以下问题的答案：
- 1. 这是什么类型的页面？（产品、文章、FAQ、本地商家）
- 你希望实现哪些丰富结果？（FAQ 下拉菜单、产品星级、面包屑导航）
- 有哪些数据可用于填充 Schema？（价格、评分、日期）
- 页面上是否已有现有 Schema？（先用丰富结果测试检查）
- 你的技术栈是什么？（静态 HTML、React/Next.js、CMS/WordPress）
实施工作流程
- 1. 识别页面类型 — 将网站页面映射到 Schema 类型
- 从首页开始 — Organization + WebSite Schema
- 添加每页 Schema — 博客用 Article，商店用 Product 等
- 添加 BreadcrumbList — 每个带导航面包屑的页面
- 验证每个页面 — 实施前后使用丰富结果测试
- 监控 Search Console — 上线后每周检查增强报告
绝对禁止
- 1. 绝对不要为页面上不存在的内容添加 Schema — 这违反 Google 指南，可能导致处罚
- 绝对不要在可以使用 JSON-LD 时使用微数据或 RDFa — JSON-LD 更易于维护，是 Google 推荐的格式
- 绝对不要硬编码本应动态的 Schema — 产品价格、库存状态和评分必须反映当前数据
- 绝对不要在部署前跳过验证 — 无效的 Schema 比没有 Schema 更糟糕；会浪费抓取预算
- 绝对不要对每个页面使用相同的标记 — 每种页面类型需要其适当的 Schema 类型
- 绝对不要忽略 Search Console 错误 — Schema 错误可能导致丰富结果完全消失
