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 Rich Results Test（丰富结果测试）：https://search.google.com/test/rich-results
- Schema.org Validator（验证器）：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
- 针对自定义类型修改主题
- 将自定义字段映射到结构化数据
测试清单
- - [ ] 在Rich Results Test中验证通过，无错误
- [ ] 推荐属性无警告
- [ ] Schema内容与可见页面内容匹配
- [ ] 每种类型包含所有必需属性
- [ ] URL为完整格式
- [ ] 日期为ISO 8601格式
- [ ] 价格为数值，不含货币符号
任务特定问题
实施前，收集以下问题的答案：
- 1. 这是什么类型的页面？（产品、文章、FAQ、本地商家）
- 你针对哪些丰富结果？（FAQ下拉菜单、产品星级、面包屑导航）
- 有哪些数据可用于填充Schema？（价格、评分、日期）
- 页面上是否有现有Schema？（先用Rich Results Test检查）
- 你的技术栈是什么？（静态HTML、React/Next.js、CMS/WordPress）
实施工作流程
- 1. 识别页面类型 — 将网站页面映射到Schema类型
- 从主页开始 — Organization + WebSite Schema
- 添加每页Schema — 博客用Article，商店用Product等
- 添加BreadcrumbList — 每个有导航面包屑的页面
- 验证每个页面 — 实施前后使用Rich Results Test
- 监控Search Console — 上线后每周检查增强报告
绝对禁止
- 1. 绝对不要为页面上不存在的内容添加Schema — 这违反Google指南，可能导致处罚
- 绝对不要在可以使用JSON-LD时使用微数据或RDFa — JSON-LD更易维护，是Google推荐的格式
- 绝对不要硬编码本应动态的Schema — 产品价格、库存状态和评分必须反映当前数据
- 绝对不要在部署前跳过验证 — 无效的Schema比没有Schema更糟糕；会浪费爬取预算
- 绝对不要对每个页面使用相同的标记 — 每种页面类型需要其适当的Schema类型
- 绝对不要忽略Search Console中的错误 — Schema错误可能导致丰富结果完全消失
