Featured image of post 给数据加上语义——JSON-LD 入门
架构设计

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

JSON 让机器能读，JSON-LD 让机器能『理解』。一篇讲清两者差异、JSON-LD 的本质和它在 SEO、知识图谱里的真实价值

一段看似差不多的代码

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）——评分、价格、作者、发布时间——大大提升点击率。

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

© 2016 - 2026 牛哥聊技术
使用 Hugo 构建
主题 Stack 由 Jimmy 设计