JSON-LD 上下文与词汇表

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

远程上下文

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

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

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

本地上下文

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

{
  "@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 可以为未显式映射的字段提供默认前缀：

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

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

前缀映射

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

{
  "@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 标记一般不需要这么复杂。

字段别名

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

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

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

多个上下文

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

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

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

上下文设计建议

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

常见误区

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