给数据加上语义——JSON-LD 入门

Wed, 04 Aug 2021 15:30:00 +0800

一段看似差不多的代码

JSON 这种数据：

1
2
3
4
5


{
 "name": "鲁迅",
 "birthDate": "1881-09-25",
 "occupation": "Writer"
}

JSON-LD 这种数据：

1
2
3
4
5
6
7


{
 "@context": "https://schema.org",
 "@type": "Person",
 "name": "鲁迅",
 "birthDate": "1881-09-25",
 "occupation": "Writer"
}

肉眼看几乎一样——多了 @context 和 @type 两行。但它们做的事在量级上完全不同：

JSON 让机器能读这段数据
JSON-LD 让机器能理解这段数据是关于一个 Person 的

理解这个差别，是看懂"语义网"、“结构化数据 SEO”、“知识图谱"为什么需要 JSON-LD 的关键。本文把 JSON 和 JSON-LD 的差异、JSON-LD 的本质、它的真实落地场景讲清楚。

一、JSON 缺了什么

JSON 是非常成功的数据交换格式——简单、轻量、跨语言。但它有一个根本缺陷：

JSON 描述了数据的结构，不描述数据的语义。

举个具体例子：

1

{ "name": "李华", "age": 30 }

这段 JSON 里——

“name” 是什么意思？人的名字？产品的名字？文件名？
“age” 是数字"30 岁"还是 30 天 / 30 个月？
“李华” 是个人，还是品牌名，还是化名？

机器只看到字符串和数字，没法做任何"理解"层面的事。

如果两个系统要交换数据，他们必须事先约定每个字段的含义——这正是为什么数据集成、API 对接永远那么痛苦：每对接一个新系统都要写文档、对齐字段。

二、JSON-LD 怎么解决这个问题

JSON-LD（JSON for Linked Data）由 W3C 标准化，给 JSON 加了"语义层”：每个字段都引用一个公开 URI 定义的"概念"。

1
2
3
4
5
6


{
 "@context": "https://schema.org",
 "@type": "Person",
 "name": "鲁迅",
 "birthDate": "1881-09-25"
}

@context: https://schema.org —— 告诉机器：“本文档使用 Schema.org 词汇表”
@type: Person —— 告诉机器：“本对象是一个 Schema.org 定义的 Person”
name、birthDate —— 这些字段在 Schema.org 中有明确定义

任何机器（搜索引擎、抓取器、知识图谱）拿到这段数据后，只要它支持 Schema.org，就立刻知道这是一个人，name 是人的姓名，birthDate 是人的出生日期。

不需要事先约定。不需要写文档。语义来自 URI。

三、JSON-LD 的核心机制

JSON-LD 主要靠四个 @ 关键字：

1. `@context`：上下文

声明数据使用的词汇体系。最重要的关键字：

1

"@context": "https://schema.org"

也可以自定义：

1
2
3
4


"@context": {
 "name": "http://example.com/vocab#fullName",
 "age": "http://example.com/vocab#yearsOld"
}

每个 key 都映射到一个 URI——这就是"语义"的来源。

2. `@type`：类型

告诉机器这个对象是"什么"：

1
2
3


"@type": "Person"
"@type": "Product"
"@type": "Organization"

3. `@id`：标识符

为对象提供一个唯一标识（通常是 URI）：

1
2
3
4
5


{
 "@id": "https://example.com/person/lingcoder",
 "@type": "Person",
 "name": "lingcoder"
}

@id 让两条 JSON-LD 数据可以引用同一个实体——这是构建知识图谱的基础。

4. `@graph`：多对象集合

一个文档里描述多个对象：

1
2
3
4
5
6
7


{
 "@context": "https://schema.org",
 "@graph": [
 { "@type": "Person", "@id": "#zhang", "name": "张三" },
 { "@type": "Organization", "@id": "#abc", "name": "ABC 公司" }
 ]
}

四、关联数据（Linked Data）：JSON-LD 的真正价值

JSON-LD 的"LD"是 Linked Data——让数据之间能相互引用、形成图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
 "@context": "https://schema.org",
 "@type": "Article",
 "headline": "Spring Cloud 微服务实战",
 "author": {
 "@type": "Person",
 "@id": "https://example.com/person/lingcoder",
 "name": "lingcoder"
 },
 "publisher": {
 "@type": "Organization",
 "@id": "https://example.com/org/abc",
 "name": "ABC 出版社"
 }
}

文章 → 作者（Person）→ 出版社（Organization）——这些都是独立的实体，通过 @id 相互引用。

任何爬虫拿到这段数据后，自动知道：

有一个文章对象
它有一个 Person 作者
它有一个 Organization 出版社
这些实体可能也存在于其他网页上（通过 @id 关联）

这是"知识图谱"的本质——图就是节点 + 边，JSON-LD 把节点（@id）和边（关系）都标准化了。

五、JSON-LD 的真实落地场景

1. SEO 结构化数据（最普及）

Google / Bing / 百度都支持 JSON-LD 作为结构化数据格式。在 HTML 里加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<script type="application/ld+json">
{
 "@context": "https://schema.org",
 "@type": "Article",
 "headline": "JSON 与 JSON-LD",
 "author": {
 "@type": "Person",
 "name": "lingcoder"
 },
 "datePublished": "2021-08-04",
 "image": "https://example.com/cover.svg"
}
</script>

搜索引擎抓到这段后，能在搜索结果里展示富片段（rich snippet）——评分、价格、作者、发布时间——大大提升点击率。

flowchart LR
 Page[网页] --> SE[搜索引擎]
 SE --> Plain[普通搜索结果
纯文本摘要]
 Page -.JSON-LD.-> SE2[搜索引擎]
 SE2 --> Rich[富片段
评分/价格/作者]

这是 JSON-LD 在 Web 上最广泛、最实用的应用。

2. 知识图谱

学术领域的论文数据库、医疗领域的病例数据、电商的商品图谱——用 JSON-LD 把不同来源的数据串起来。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "@context": "https://schema.org",
 "@type": "MedicalCondition",
 "name": "糖尿病",
 "associatedAnatomy": { "@type": "AnatomicalStructure", "name": "胰腺" },
 "possibleTreatment": [
 { "@type": "Drug", "name": "胰岛素" },
 { "@type": "MedicalTherapy", "name": "饮食控制" }
 ]
}

3. Web3 / 去中心化身份

DID（Decentralized Identifier）和 Verifiable Credentials（VC）规范用 JSON-LD 描述身份和凭证：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "@context": [
 "https://www.w3.org/2018/credentials/v1",
 "https://www.w3.org/2018/credentials/examples/v1"
 ],
 "type": ["VerifiableCredential", "UniversityDegreeCredential"],
 "issuer": "did:example:university",
 "credentialSubject": {
 "id": "did:example:alice",
 "degree": { "type": "BachelorDegree", "name": "Bachelor of Science" }
 }
}

4. RDF 兼容

JSON-LD 直接可以转成 RDF 三元组——和学术界、政府开放数据互通。

六、JSON-LD vs Microdata vs RDFa

HTML 结构化数据三种主流格式：

	JSON-LD	Microdata	RDFa
写法	`<script>` 块	HTML 标签里加属性	HTML 标签里加属性
内嵌位置	任意	紧贴对应内容	紧贴对应内容
与内容耦合	解耦	强耦合	强耦合
谷歌推荐	首选	支持	支持
易维护	✓	△	△

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<!-- Microdata（侵入式） -->
<div itemscope itemtype="https://schema.org/Person">
 <span itemprop="name">鲁迅</span>
 <span itemprop="birthDate">1881-09-25</span>
</div>

<!-- JSON-LD（独立块） -->
<script type="application/ld+json">
{ "@context": "https://schema.org", "@type": "Person", ... }
</script>

Google 官方推荐 JSON-LD——和 HTML 结构解耦，易于运维，模板化生成方便。

七、几个工程实践

1. 不要手工写

JSON-LD 字段嵌套深、重复多——代码生成，别手写。Java 用 org.schema.javasdk，Node 用 schema-dts，能避免拼字段错。

2. 验证工具

写完用 Google Rich Results Test 验证——**不验证就上线，搜索引擎抓不到富片段 **。

3. context 缓存

https://schema.org 是个真实的 URL，机器抓数据时会去访问。生产场景把 context 缓存在本地，避免延迟。

4. 不要塞业务字段

JSON-LD 是对外用——只放标准 Schema.org 字段。内部业务字段（数据库 ID、内部状态）不要塞进 JSON-LD，会污染语义。

5. SEO 价值的真实预期

加了 JSON-LD 不一定立刻有富片段——Google 决定是否展示，并不保证。但没加一定没有——成本极低，回报概率高，工程上是无脑加的事。

八、什么场景该用 JSON-LD

✅ 适合：

公开网页的结构化标注（最普及场景，做 SEO）
跨系统数据交换（标准化语义）
知识图谱构建
Web3 / DID / VC

❌ 不适合：

普通的 API 数据交换——用 JSON 就够了
内部系统通信——加 @context 是开销
性能敏感场景——JSON-LD 文档体积比 JSON 大

普通 API 用普通 JSON，只有"数据需要被外部理解"时上 JSON-LD。

小结

把全文压一句：

JSON 让机器读得到数据，JSON-LD 让机器读懂数据。前者解决传输，后者解决语义。

工程上的实践：

公开网页加 JSON-LD——SEO 富片段几乎无成本
用 Schema.org 词汇表，不要造私有词汇
用工具生成，用 Google Rich Results Test 验证
内部系统不必折腾——纯 JSON 就够

理解 JSON-LD 不是为了在每个项目里都用它，而是理解"语义网"为什么重要——当你下次要让机器"看懂"数据而不只是"读懂" 时，知道有这件武器可用。

知识图谱 on 牛哥聊技术