# JSON-LD 上下文与词汇表

URL: https://caijiao.org/json-ld/guide/context
Source: docs/json-ld/guide/context.md
Description: 深入理解 @context 的作用、远程上下文、本地上下文、@vocab、前缀映射和字段别名，掌握 JSON-LD 语义映射方式。

`@context` 是 JSON-LD 的核心。它告诉处理器：文档中的短字段名、类型名和属性名应该如何展开成稳定的 IRI。

## 远程上下文

最常见写法是引用远程上下文：

```json
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "机械键盘",
  "brand": "Acme"
}
```

这里的 `name`、`brand`、`Product` 都会按照 Schema.org 的词汇表解释。远程上下文让文档简洁，也便于多个发布者使用同一套词汇。

## 本地上下文

也可以在文档中直接定义映射：

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

`homepage` 的 `@type: "@id"` 表示它的值不是普通文本，而是一个 IRI 引用。

## 默认词汇表

`@vocab` 可以为未显式映射的字段提供默认前缀：

```json
{
  "@context": {
    "@vocab": "https://schema.org/"
  },
  "@type": "Person",
  "name": "Ada Chen",
  "knowsAbout": "JSON-LD"
}
```

在可控的应用或文档中，`@vocab` 可以减少重复配置。但如果数据会被很多第三方消费，显式使用成熟词汇表通常更稳妥。

## 前缀映射

当前缀重复出现时，可以定义短前缀：

```json
{
  "@context": {
    "schema": "https://schema.org/",
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@type": "schema:Person",
  "schema:name": "Ada Chen",
  "foaf:homepage": { "@id": "https://example.com/authors/ada" }
}
```

这类写法在语义 Web 和知识图谱场景中更常见；面向 SEO 的 Schema.org 标记一般不需要这么复杂。

## 字段别名

上下文可以把业务字段映射到标准字段：

```json
{
  "@context": {
    "@vocab": "https://schema.org/",
    "title": "headline",
    "publishedAt": "datePublished"
  },
  "@type": "Article",
  "title": "上下文入门",
  "publishedAt": "2026-09-22"
}
```

这对内部 API 很有用：业务代码仍然使用熟悉字段，发布出去时具备标准语义。

## 多个上下文

`@context` 可以是数组，后面的上下文会在必要时覆盖前面的定义：

```json
{
  "@context": [
    "https://schema.org",
    {
      "docs": "https://example.com/vocab#",
      "difficulty": "docs:difficulty"
    }
  ],
  "@type": "TechArticle",
  "headline": "JSON-LD 上下文",
  "difficulty": "beginner"
}
```

多个上下文适合“标准词汇 + 自定义扩展”的场景。扩展字段要有清晰命名空间，避免和公共词汇冲突。

## 上下文设计建议

| 场景 | 建议 |
| --- | --- |
| 搜索结构化数据 | 直接使用 `https://schema.org` |
| 内部 API | 用本地上下文映射业务字段 |
| 开放数据 | 为自定义字段提供稳定、可解析的命名空间 |
| 大规模发布 | 固定上下文版本，避免语义突然变化 |
| 高可靠消费 | 缓存远程上下文，并设置失败降级策略 |

## 常见误区

- 把 `@context` 当作普通元数据字段，而不是语义映射规则。
- 自定义字段没有命名空间，导致不同系统难以判断含义。
- 远程上下文不可访问，导致处理器无法完整展开。
- 同一个短字段在不同文档里含义不同，增加消费方维护成本。