structured-data

结构化数据

修复 IsAgentReady.com 的 AI 搜索信号类别。这些检查点用于测试网站是否提供机器可读的上下文，供 AI 搜索产品使用和引用。

• 方法论版本：2026-10-22。方法论：https://isagentready.com/en/methodology
• 评分（权重和分值）：https://isagentready.com/api/v2/methodology/2026-10-22/scoring
• 完整检查点数据（阶段、证据类型、验证命令、重新扫描命令）：references/checkpoints.md

扫描器会读取第一个 HTML 响应，不会运行 JavaScript。仅由 JavaScript 添加的 JSON-LD 不计入检查。

适用场景

• 扫描显示 AI 搜索信号类别存在未通过项（旧版 ID 2.x）。
• 用户要求添加或修复 JSON-LD、结构化数据或 schema 标记。
• 网站需要 Organization、WebSite、Product、Article、FAQPage 或作者标记。
• 网站没有关于、联系或隐私页面。

不适用场景

• Microdata 或 RDFa：此技能仅涵盖 JSON-LD。
• Open Graph 或 Twitter Card 标签：这些标签用于社交媒体预览。
• robots.txt、站点地图或 AI 爬虫访问：请使用 ai-content-discovery。
• 语义 HTML 或标题：请使用 content-semantics。
• 安全标头：请使用 security-trust。

说明

1. 获取扫描中未通过的检查点。每个结果都有一个旧版 ID（2.2）和一个稳定 ID（ia.organization-schema）。
2. 前往修复工作流，并使用与稳定 ID 相同的锚点。
3. 根据网站调整示例。将 example.com 替换为网站域名。
4. 使用 Schema.org 验证器 验证，并运行验证命令。
5. 使用 isagentready results <domain> --checkpoint <stable-id> 重新扫描，或前往 isagentready.com 重新扫描。

如果提供了 $ARGUMENTS，请将其作为要修复的网址或要修复的检查点。

检查点

Strength 表示 agentready.org 规范级别（MUST、SHOULD、MAY）。Strength 不会改变分数。

Legacy	Stable ID	Name	AR IDs	Strength
2.1	ia.json-ld	存在 JSON-LD	AR-READ-08	SHOULD
2.2	ia.organization-schema	Organization / WebSite schema	AR-READ-08	SHOULD
2.3	ia.high-value-schema	高价值 schema 类型	AR-READ-08	SHOULD
2.4	ia.entity-linking	通过 @id 关联实体	AR-READ-08	SHOULD
2.6	ia.schema-validation	Schema 验证	AR-READ-08	SHOULD
2.7	ia.faq-schema	FAQPage schema	AR-READ-08	SHOULD
2.8	ia.author-attribution	作者署名	AR-READ-08	SHOULD
2.9	ia.trust-pages	信任锚点页面	none	SHOULD

快速路径

对于没有结构化数据的网站，添加一个包含 Organization、WebSite 和主要内容类型的 @graph 块。为每个实体指定一个 @id 和作者。这个块可以同时修复 2.1、2.2、2.3、2.4 和 2.8。完整模板见 references/json-ld-patterns.md。

修复工作流

2.1 存在 JSON-LD

当 HTML 中有一个或多个 <script type="application/ld+json"> 块，且其中包含有效 JSON 和值为 https://schema.org 的 @context 时，即通过检查。

1. 在服务器返回的 HTML 的 <head> 中添加一个 JSON-LD 块：

   <script type="application/ld+json">
   { "@context": "https://schema.org", "@type": "Organization",
     "name": "Example Inc", "url": "https://example.com" }
   </script>
   

2. 确保 JSON 有效。尾随逗号会导致代码块无效。

验证：curl -sf https://example.com/ | grep -q 'application/ld+json'

2.2 Organization / WebSite 架构

当 JSON-LD 中包含带有 name 和 url 的 Organization 或 WebSite 时通过。logo、sameAs 和 contactPoint 可提供更多背景信息。

1. 添加 Organization 实体：

   {
     "@context": "https://schema.org",
     "@type": "Organization",
     "name": "Example Inc",
     "url": "https://example.com",
     "logo": "https://example.com/logo.png",
     "sameAs": ["https://www.linkedin.com/company/example", "https://github.com/example"],
     "contactPoint": { "@type": "ContactPoint", "email": "[email protected]", "contactType": "customer service" }
   }
   

2. 如果网站有搜索功能，添加带有 SearchAction 的 WebSite 实体。参见 references/json-ld-patterns.md。

验证：curl -sf https://example.com/ | grep -qE '"@type": *"(Organization|WebSite)"'

2.3 高价值架构类型

当页面包含一种具有必需属性的高价值类型时通过。类型包括 Article、NewsArticle、BlogPosting、Product、SoftwareApplication、WebApplication、MobileApplication、LocalBusiness、Service、FAQPage、QAPage、HowTo、Course、JobPosting、VideoObject、Event 和 Recipe。

1. 选择与页面内容匹配的类型。例如，产品页面：

   {
     "@context": "https://schema.org",
     "@type": "Product",
     "name": "Planner Pro",
     "description": "Project planning software for small teams",
     "offers": { "@type": "Offer", "price": "12.00", "priceCurrency": "USD" }
   }
   

2. 填写所有必需属性。每种类型的模板见 references/schema-types.md。

验证：curl -sf https://example.com/ | grep -oE '"@type": *"[A-Za-z]+"' | sort -u

2.4 通过 @id 关联实体

当实体包含 @id，并且彼此通过 @id 引用时通过。只有 @id 而没有引用可获得部分分数。

1. 按照 <url>#<type> 格式为每个实体设置 @id，并从其他实体引用它：

   {
     "@context": "https://schema.org",
     "@graph": [
       { "@type": "Organization", "@id": "https://example.com/#organization", "name": "Example Inc", "url": "https://example.com" },
       { "@type": "WebSite", "@id": "https://example.com/#website", "url": "https://example.com",
         "publisher": { "@id": "https://example.com/#organization" } }
     ]
   }
   

验证：curl -sf https://example.com/ | grep -c '"@id"'（预期为 2 个或更多）

2.6 架构验证

当 JSON-LD 在同一个块中没有重复的 @type、没有缺少必需属性，也没有空的必需值时通过。

1. 从一个 @graph 中移除第二个相同类型的实体，或合并这两个实体。
2. 将 "name": "" 等空值替换为实际值。
3. 使用 PascalCase 类型名称：Organization，而不是 organization。
4. 使用 Schema.org Validator 检查页面。

验证：没有可供只读 shell 检查的命令。请使用验证器和重新扫描命令。

2.7 FAQPage 架构

适用于展示 FAQ 内容或包含 FAQPage JSON-LD 的页面。当每个 Question 都有一个 acceptedAnswer，且问题也显示在页面上时通过。

1. 为页面上显示的问题和答案添加标记：

   {
     "@context": "https://schema.org",
     "@type": "FAQPage",
     "mainEntity": [{
       "@type": "Question",
       "name": "Can I cancel at any time?",
       "acceptedAnswer": { "@type": "Answer", "text": "Yes. You can cancel in the billing settings." }
     }]
   }
   

2. 不要为页面上未显示的问题添加标记。

验证：curl -sf https://example.com/ | grep -q '"FAQPage"'（在包含可见 FAQ 的页面上运行）

2.8 作者署名

当 JSON-LD 包含带有 @type（Person 或 Organization）和 name 的 author 时通过。<meta name="author"> 或 rel="author" 可获得部分分数。

1. 将作者添加到内容实体中：

   { "@context": "https://schema.org", "@type": "Article", "headline": "Plan a sprint",
     "author": { "@type": "Person", "name": "Jane Smith", "url": "https://example.com/authors/jane" } }
   

2. 对于公司内容，使用 "@type": "Organization"。不要将纯字符串用作作者。

验证：curl -sf https://example.com/ | grep -qE '"author"|name="author"|rel="author"'

2.9 信任页面

当关于、联系和隐私页面均返回 2xx，且可见文本不少于 500 个字符时通过。扫描器会跟踪首页上的同源链接，也会跟踪 /over-ons 等本地路径。随后会尝试访问 /about、/contact 和 /privacy。

1. 以服务器 HTML 形式发布包含实际内容的这三个页面。
2. 从首页链接到这些页面，例如放在页脚中：

   <footer>
     <nav aria-label="Company">
       <a href="/about">About Example Inc</a>
       <a href="/contact">Contact</a>
       <a href="/privacy">Privacy policy</a>
     </nav>
   </footer>
   

验证：curl -sI https://example.com/about https://example.com/contact https://example.com/privacy | grep -i '^HTTP/'

常见陷阱

1. 不含 "@context": "https://schema.org" 的 JSON 不计入。
2. 尾随逗号会导致整个块无效。
3. 在一个 @graph 中包含两个 Organization 实体会导致验证问题。
4. "author": "Jane Smith"（字符串）无法通过。请使用包含 @type 和 name 的对象。
5. 为页面上不可见的问题添加 FAQPage 标记只能获得部分分数。

正确和错误示例见 references/gotchas.md。

参考资料

• references/checkpoints.md：各检查点的生成数据
• references/schema-types.md：各 Schema.org 类型的 JSON-LD 模板
• references/json-ld-patterns.md：@graph、实体链接、SearchAction 和组合类型
• references/gotchas.md：常见错误及正确和错误示例