JSON-LD 关键字参考

JSON-LD 关键字以 @ 开头，具有规范定义的含义。普通业务字段不应使用 @ 前缀，除非它确实是 JSON-LD 关键字。

常用关键字速查

关键字	用途	常见场景
`@context`	定义字段、类型和前缀如何解释	每个 JSON-LD 文档
`@type`	声明对象或值的类型	`Article`、`Product`、`Person`
`@id`	声明实体 IRI 或引用实体	实体复用、知识图谱
`@value`	声明字面量值	语言、类型化值
`@language`	声明语言标签	多语言文本
`@graph`	在一个文档中放多个节点	组织、网站、页面组合
`@list`	表示有序列表	顺序必须保留的数据
`@set`	表示集合	强制值作为数组处理
`@container`	定义容器映射方式	语言映射、索引映射
`@vocab`	定义默认词汇表	自定义上下文
`@base`	定义相对 IRI 的基准	文档级 IRI 解析
`@reverse`	表示反向属性	反向关系建模

@context

{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Ada Chen"
}

@context 可以是字符串、对象或数组。面向 Schema.org 的网页结构化数据，通常使用字符串即可。

@type

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Acme K1"
}

@type 用来说明对象类型。对于搜索结构化数据，类型要和页面主体一致，并符合目标平台支持范围。

@id

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "Example Docs"
}

@id 是实体身份，不只是页面链接。引用已有实体时，可以只写 @id：

{
  "publisher": {
    "@id": "https://example.com/#organization"
  }
}

@value、@language、@type

值对象用于表达普通字符串无法表达的细节：

{
  "@value": "Bonjour",
  "@language": "fr"
}

类型化值示例：

{
  "@value": "2026-09-22",
  "@type": "http://www.w3.org/2001/XMLSchema#date"
}

在 Schema.org SEO 场景中，大多数日期和数字字段直接使用平台文档要求的字符串格式即可。

@graph

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Example Docs"
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/json-ld",
      "publisher": { "@id": "https://example.com/#organization" }
    }
  ]
}

@graph 可以减少重复并清晰表达多实体关系。

@list 与 @set

@list 表示顺序有语义：

{
  "@context": {
    "steps": {
      "@id": "https://schema.org/step",
      "@container": "@list"
    }
  },
  "steps": ["准备数据", "生成 JSON-LD", "验证上线"]
}

@set 常用于确保某个字段即使只有一个值，也按集合处理。网页结构化数据里通常直接使用数组更直观。

@container

@container 定义容器如何解释。语言映射示例：

{
  "@context": {
    "name": {
      "@id": "https://schema.org/name",
      "@container": "@language"
    }
  },
  "name": {
    "zh-CN": "结构化数据指南",
    "en": "Structured Data Guide"
  }
}

@vocab 和 @base

@vocab 为短字段提供默认词汇表：

{
  "@context": {
    "@vocab": "https://schema.org/"
  }
}

@base 用于解析相对 IRI：

{
  "@context": {
    "@base": "https://example.com/docs/"
  },
  "@id": "json-ld"
}

在公开网页中，直接写绝对 URL 往往更清楚。

不建议随意使用的关键字

关键字	原因
`@reverse`	语义更复杂，普通 Schema.org 标记很少需要
`@nest`	可改善 JSON 结构，但增加消费方理解成本
`@included`	适合特定图数据场景，网页结构化数据通常不需要
`@version`	只有需要明确 JSON-LD 1.1 处理模式时才使用
`@direction`	用于文本方向，需确认处理器支持

编写建议

新手先掌握 @context、@type、@id、@graph。
面向 SEO 时优先照目标平台文档写，少用高级关键字。
面向知识图谱时重点设计稳定 @id 和上下文。
任何关键字的引入都应让数据更清晰，而不是更炫技。