# JSON-LD 关键字参考

URL: https://caijiao.org/json-ld/reference/keywords
Source: docs/json-ld/reference/keywords.md
Description: 整理 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

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

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

## @type

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

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

## @id

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

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

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

## @value、@language、@type

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

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

类型化值示例：

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

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

## @graph

```json
{
  "@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` 表示顺序有语义：

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

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

## @container

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

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

## @vocab 和 @base

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

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

`@base` 用于解析相对 IRI：

```json
{
  "@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` 和上下文。
- 任何关键字的引入都应让数据更清晰，而不是更炫技。