如何正确使用 JSON-LD 的 @graph 实现多类型结构化数据标记-html教程-PHP中文网

如何正确使用 JSON-LD 的 @graph 实现多类型结构化数据标记

@graph 是 JSON-LD 中用于批量声明多个独立实体的标准机制，支持在同一脚本中混合定义不同 Schema.org 类型（如 MedicalCondition、Person、Review、VideoObject），无需类型一致或嵌套依赖，是现代语义标记的最佳实践。

`@graph` 是 json-ld 中用于批量声明多个独立实体的标准机制，支持在同一脚本中混合定义不同 schema.org 类型（如 `medicalcondition`、`person`、`review`、`videoobject`），无需类型一致或嵌套依赖，是现代语义标记的最佳实践。

在构建医疗健康类网页的结构化数据时，常需同时描述疾病、医生、患者评价及多媒体内容——这些实体语义独立、逻辑并列，天然适合用 @graph 统一组织。你提出的疑问“是否只能用 @graph 标记同类型 Schema？”是一个常见误解。答案明确否定：@graph 的设计初衷正是支持异构实体共存。

根据 JSON-LD 1.1 规范及 Schema.org 官方文档，@graph 表示一个命名图（named graph），其数组元素可为任意数量、任意类型的 JSON-LD 对象（即不同 @type 的 Schema 实体），每个对象都是图中的独立节点，彼此通过 @id（若显式声明）或隐式上下文关联，而非强制继承或聚合关系。

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

Json Schema Toolkit

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

下载

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "MedicalCondition",
      "@id": "#condition",
      "name": "2型糖尿病",
      "signOrSymptom": [
        { "@type": "MedicalSignOrSymptom", "name": "多饮" },
        { "@type": "MedicalSignOrSymptom", "name": "体重下降" }
      ],
      "possibleTreatment": [
        { "@type": "MedicalTherapy", "name": "二甲双胍治疗" }
      ]
    },
    {
      "@type": "Person",
      "@id": "#doctor",
      "name": "张明医生",
      "jobTitle": "内分泌科主任医师",
      "affiliation": {
        "@type": "Organization",
        "name": "北京协和医院"
      }
    },
    {
      "@type": "Review",
      "author": { "@id": "#doctor" },
      "itemReviewed": { "@id": "#condition" },
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": "4.9",
        "bestRating": "5"
      },
      "reviewBody": "该病管理需长期生活方式干预与药物协同。"
    },
    {
      "@type": "VideoObject",
      "name": "糖尿病饮食指南",
      "description": "营养师讲解碳水化合物控制要点",
      "uploadDate": "2026-07-15",
      "duration": "PT8M32S",
      "thumbnailUrl": ["https://example.com/thumbs/diabetes-diet.jpg"],
      "contentUrl": "https://example.com/videos/diabetes-diet.mp4"
    }
  ]
}
</script>

? 关键注意事项：

@id 是关联枢纽：当多个实体存在逻辑关系（如医生撰写评价、评价针对疾病），应为实体分配唯一 @id（如 "@id": "#doctor"），并在引用处直接使用该 ID（如 "author": { "@id": "#doctor" }），避免冗余嵌套，提升数据可解析性与机器推理能力。
类型拼写必须准确：原文中 "Perosn" 是典型拼写错误，应为 "Person"；"worstRating" 等字段值不可为空，需填入数字（如 1）；缺失值建议省略字段，而非留空字符串或 null。
验证优先于语法：部署前务必使用 Google Rich Results Test 或 Schema Markup Validator 检查语法有效性与搜索引擎兼容性。工具会明确提示 @type 是否被识别、必需字段是否缺失。
避免过度堆砌：@graph 支持最多约 10–15 个高质量实体。若页面含数十条评论或视频，建议分页标记或仅标记精选内容，兼顾加载性能与 SEO 效果。