如何正确使用 JSON-LD 中的 @graph 关键字组织多类型结构化数据-html教程-PHP中文网

如何正确使用 JSON-LD 中的 @graph 关键字组织多类型结构化数据

@graph 是 JSON-LD 的核心特性，允许在单个块中并列声明多个不同类型的 Schema.org 实体（如 MedicalCondition、Person、Review、VideoObject），无需嵌套或强制同构，完全符合规范且被所有主流搜索引擎（Google、Bing、Yandex）及 AI Agent 工具链（如 MCP、GraphRAG）所支持。

`@graph` 是 json-ld 的核心特性，允许在单个 `<script type="application/ld+<a style=" color: text-decoration:underline title="json" href="https://m.php.cn/zt/15848.html" target="_blank">json">` 块中并列声明多个不同类型的 schema.org 实体（如 `medicalcondition`、`person`、`review`、`videoobject`），无需嵌套或强制同构，完全符合规范且被所有主流搜索引擎（google、bing、yandex）及 ai agent 工具链（如 mcp、graphrag）所支持。</script>

在结构化数据实践中，@graph 并非限制性容器，而是一个语义图（Semantic Graph）的顶层声明机制——它明确告诉解析器：接下来的数组是一组相互关联（或独立）的 RDF 资源节点（resources），每个节点可拥有任意 @type，彼此通过属性（如 author、itemReviewed、video）建立显式或隐式链接。这正契合 Schema.org “实用主义本体”的设计哲学：不强求类型统一，而强调语义可连接性。

✅ 正确用法示例（精简可运行版）：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "MedicalCondition",
      "@id": "https://example.com/condition/hypertension",
      "name": "高血压",
      "signOrSymptom": [
        { "@type": "MedicalSign", "name": "头痛" },
        { "@type": "MedicalSign", "name": "头晕" }
      ],
      "possibleTreatment": [
        { "@type": "MedicalTherapy", "name": "ACE抑制剂" }
      ]
    },
    {
      "@type": "Person",
      "@id": "https://example.com/doctors/dr-zhang",
      "name": "张医生",
      "jobTitle": "心血管内科主任医师",
      "affiliation": {
        "@type": "Organization",
        "name": "仁济医院"
      }
    },
    {
      "@type": "Review",
      "author": { "@id": "https://example.com/doctors/dr-zhang" },
      "itemReviewed": { "@id": "https://example.com/condition/hypertension" },
      "reviewRating": {
        "@type": "AggregateRating",
        "ratingValue": "4.9",
        "reviewCount": 127
      }
    },
    {
      "@type": "VideoObject",
      "name": "高血压日常管理指南",
      "uploadDate": "2026-07-15",
      "duration": "PT8M32S",
      "thumbnailUrl": ["https://example.com/thumbs/hypertension-guide.jpg"],
      "embedUrl": "https://example.com/embed/hypertension-video"
    }
  ]
}
</script>

? 关键要点说明：

Json Schema Toolkit

使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。

下载

类型无限制：@graph 数组内可自由混合 MedicalCondition、Person、Review、VideoObject 等任意 Schema.org 类型，无需“相同类型”前提——Stack Overflow 上的误解源于混淆了 @graph 与 RDF 图的底层模型约束（RDF 允许异构三元组），而 JSON-LD 的 @graph 正是为表达此类异构图而设计。
ID 链接是关键：为实现跨实体语义关联（如“张医生撰写了关于高血压的视频评论”），应为各实体设置唯一 @id，并在引用属性（如 author、itemReviewed）中直接使用该 ID。这比嵌套对象更清晰、更利于知识图谱抽取和 Agent 工具调用。
避免常见错误：
- ❌ 不要省略 @context 或拼错（如 "https://schema.org" 缺少末尾 /）；
- ❌ @type 值必须是合法 Schema.org 类型名（如 "Person"，而非 "Perosn" ——原文中存在拼写错误）；
- ❌ Review 和 VideoObject 中的数值字段（如 ratingValue、userInteractionCount）必须为数字，不可留空或写为逗号；
- ❌ 多个 Review 实体无需重复定义相同结构，应确保每个 @id 唯一且 itemReviewed 指向有效目标。

? 进阶提示：面向 AI Agent 的现代 GEO（生成式引擎优化）已将 @graph 视为标准实践。Agent 通过 MCP 协议读取结构化数据时，依赖 @graph 提供的完整实体拓扑来构建上下文图谱。因此，一个精心组织的 @graph 不仅提升搜索富摘要（Rich Results）展示率，更是打通 LLM 工具调用与知识推理的关键基础设施。

综上，你原始代码中使用 @graph 包裹多种类型实体的思路完全正确——只需修正拼写、补全必填字段、添加 @id 并验证语法，即可成为符合 Google Rich Results Test、Microsoft GraphRAG 及各类 Agent 解析器要求的高质量结构化数据标记。