seo-schema

用途

该技能用于检测、校验或生成 Schema.org JSON-LD 结构化数据，针对给定的页面或实体。仅在需要结构化数据或富媒体结果标记时使用。

主要能力

检测

通过命令提取 JSON-LD：${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo run parse_html.py --url <url> --json，或扫描页面源代码中的 <script type="application/ld+json">。
标记任何缺少 @context 或 @type 的块：Google 无法将其附加到实体（此类块中的评分不会到达 Product）。
检查 Microdata（itemscope、itemprop）。
检查 RDFa（typeof、property）。
始终推荐 JSON-LD 作为主要格式（Google 明确偏好）。

校验

按 schema 类型检查必填属性。
对照 Google 支持的富媒体结果类型进行校验。
测试常见错误：
- 缺少 @context
- 无效 @type
- 错误数据类型
- 占位文本
- 相对 URL（应为绝对 URL）
- 无效日期格式
标记已弃用类型。

Schema 类型状态（截至 2026 年 6 月）

完整列表见 ../seo/references/schema-types.md。关键规则：

活跃（可自由推荐）：Organization、LocalBusiness、SoftwareApplication、WebApplication、Product（自 2025 年 4 月起含 Certification 标记）、ProductGroup、Offer、Service、Article、BlogPosting、NewsArticle、Review、AggregateRating、BreadcrumbList、WebSite、WebPage、Person、ProfilePage、ContactPage、VideoObject、ImageObject、Event、JobPosting、Course、DiscussionForumPosting。
视频与专用（可自由推荐）：BroadcastEvent、Clip、SeekToAction、SoftwareSourceCode。可用模板见 schema/templates.json。
JSON-LD 与 JavaScript 渲染：Google 支持用 JavaScript 生成的结构化数据，但其“Generate structured data with JavaScript”指南（最后更新于 2025-12-10）警告，动态生成的 Product 标记可能导致 Shopping 爬取频率降低，对快速变动的价格和库存不够可靠。对于时间敏感的标记（尤其是 Product、Offer），应在初始服务器渲染的 HTML 中包含 JSON-LD。
无富媒体结果，若有用则保留：FAQPage——Google 于 2026 年 5 月 7 日对所有网站停用 FAQ 富媒体结果（取代 2023 年 8 月的政府/健康限制）。无 Google SERP 富媒体结果收益；将现有 FAQPage 标记为 Info（而非 Critical），而非建议移除。对于真正的用户问答页面，使用 QAPage。
已弃用（绝不推荐）：
- HowTo：富媒体结果于 2023 年 9 月移除
- SpecialAnnouncement：2025 年 7 月 31 日弃用
- CourseInfo、EstimatedSalary、LearningVideo：2025 年 6 月停用
- ClaimReview：自 2025 年 6 月起无 Search 富媒体结果。Google 的 Fact Check Explorer 仍使用该标记，因此事实核查发布者可以保留；绝不为 SERP 特性推荐它
- VehicleListing：2025 年 6 月从富媒体结果中停用
- Practice Problem：2025-11-05 弃用通知；工具支持自 2026 年 1 月起移除；文档于 2026-01-06 移除
- CourseInfo、ClaimReview、EstimatedSalary、LearningVideo、SpecialAnnouncement、VehicleListing 的 Search Console / Rich Results Test / 外观过滤器支持于 2025-09-09 移除（Search Console API 至 2025 年 12 月）。
仍受支持（尽管此前有淘汰通知）：Book Actions——未弃用。2025 年 6 月的淘汰横幅于 2025-11-05 移除，因为仍有 Search 特性使用该标记。
仅支持 Dataset Search：Dataset——未停用；由 Google Dataset Search 消费，无 Google Search 富媒体结果界面。不要建议移除，好像它已被废弃。
仍受支持（不要标记）：QAPage（2026-03-24 扩展评论线程属性）、DiscussionForumPosting、Education Q&A（Quiz / eduQuestionType=Flashcard）。对于电子商务，成人产品必须使用 hasAdultConsideration（2026-05-20 新增；值 https://schema.org/SexualContentConsideration）。Product.category 接受 Text、CategoryCode 或混合两者的数组。

生成

为页面生成 schema 时：

通过内容分析识别页面类型
选择合适的 schema 类型
生成包含所有必填 + 推荐属性的有效 JSON-LD
仅包含真实、可验证的数据。使用清晰标记的占位符供用户填写
在呈现前校验输出

对于评论标记，拒绝虚假评论和未披露的激励评论。激励必须在页面上清晰显著地披露。

常用 Schema 模板

Organization

{
  "@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

{
  "@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

{
  "@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]"
    }
  }
}

输出

SCHEMA-REPORT.md：检测与校验结果
generated-schema.json：可直接使用的 JSON-LD 代码片段

校验结果

Schema	类型	状态	问题
...	...	✅/⚠️/❌	...

建议

缺失的 schema 机会
需要修复的校验问题
生成的实现代码

错误处理

场景	操作
URL 不可达	报告连接错误及状态码。建议核实 URL 并检查页面是否需要身份验证。
未找到 schema 标记	报告未检测到 JSON-LD、Microdata 或 RDFa。根据页面内容分析推荐合适的 schema 类型。
无效 JSON-LD 语法	解析并报告具体语法错误（缺失括号、尾随逗号、未加引号的键）。提供修正后的 JSON-LD 输出。
检测到已弃用 schema 类型	标记该弃用类型及其停用日期。推荐当前替代类型，若无替代则建议移除。

适用场景

适用于需要对网页或实体进行结构化数据（JSON-LD、Microdata、RDFa）检测、校验和生成的 SEO 场景，尤其关注 Google 富媒体结果支持情况。

限制

该技能专用于结构化数据与富媒体结果标记，不适用于其他 SEO 领域。
生成时要求数据真实可验证，占位符需明确标记，拒绝虚假评论和未披露的激励评论。