# @digitalcredentials/jsonld 中文文档

规范地址：https://npmcn.com/package/%40digitalcredentials/jsonld/

版本：9\.0\.0
npm 元数据更新时间：2026-09-30T17:46:20.486Z
中文译文更新时间：2026-11-12T08:54:10.662Z
软件包许可：BSD-3-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40digitalcredentials/jsonld
原文对照：https://npmcn.com/package/%40digitalcredentials/jsonld/?lang=original
项目主页：https://github.com/digitalcredentials/jsonld.js
源码仓库：https://github.com/digitalcredentials/jsonld.js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.8 MB，35 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=14
- 运行依赖：4 个
- 首次发布：2021-05-19T21:52:02.022Z
- 最新版本发布：2024-08-04T00:44:28.447Z
- 近 30 天下载量：103647（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 0 个）

## 中文简介

一个JSON-LD处理器和JavaScript中的API执行.

## 安装

```sh
npm install @digitalcredentials/jsonld
```

也可以使用：`pnpm add @digitalcredentials/jsonld`、`yarn add @digitalcredentials/jsonld`、`bun add @digitalcredentials/jsonld`

## README

# jsonld.js (英语)

[![NPM Version](https://img.shields.io/npm/v/@digitalcredentials/jsonld.svg)](https://npm.im/@digitalcredentials/jsonld)

## 导言

这个图书馆是执行 [JSON-LD( 日语)](https://json-ld.org/) 规格 Java脚本.

JSON,按 [RFC7159 (法语)](http://tools.ietf.org/html/rfc7159),是代表 对象。 链接数据是描述整个内容的一种方式 不同的文档或网站。 使用 IRIs, 通常为可被贬损的实体, 可用于寻找 创建“知识网”. [JSON-LD( 日语)](https://json-ld.org/) 原计划 以简单的方式发布,不仅表达链接数据 JSON,但用于给现有的JSON添加语义.

JSON-LD被设计为可以用来表达的轻量级语法 已链接数据。 它主要是用来表达链接数据的一种方式 在JavaScript和其他基于Web的编程环境中. 这也是 在构建可互操作的网络服务和存储链接时有用 基于JSON的文档存储引擎中的数据. 这很实际,而且 设计尽可能简单,利用大量JSON 解析器和今天使用的现有代码。 它的设计是 能够表达密钥值对,RDF数据, [卢旺达国防军a](http://www.w3.org/TR/rdfa-core/) 数据, [微格式](http://microformats.org/) 数据,以及 [微数据](http://www.w3.org/TR/microdata/)也就是说,它支持每一个 今天使用的主要基于网络的结构化数据模型.

语法不需要很多应用程序来改变他们的JSON,但是 以带内或带内方式增加上下文,容易增加意义 脱出带. 语法设计为不会干扰已经部署的 在JSON上运行的系统,但提供从JSON平稳的迁移路径 加上语义 最后,格式要快速 用于解析、快速生成、基于流和基于文档的处理 兼容,需要非常小的内存脚印才能操作.

## 遵约

该图书馆旨在符合下列规定:

-   [JSON-LD 1.0号卫星](http://www.w3.org/TR/2014/REC-json-ld-20140116/), (中文(简体) ), W3C建议, 2014-01-16,以及任意 [错误](http://www.w3.org/2014/json-ld-errata)
-   [JSON-LD 1.0 处理算法和 API](http://www.w3.org/TR/2014/REC-json-ld-api-20140116/), (中文(简体) ), W3C建议, 2014-01-16,以及任意 [错误](http://www.w3.org/2014/json-ld-errata)
-   [JSON-LD 1.0 阵容](https://json-ld.org/spec/ED/json-ld-framing/20120830/), (中文(简体) ), 非正式草案, 2012-08-30 (中文(简体) )
-   [JSON-LD 1.1 导弹](https://json-ld.org/spec/FCGS/json-ld/20180607/), (中文(简体) ), 社区小组报告草稿, 2018-06-07或 (中文(简体) ) [更新](https://json-ld.org/spec/latest/json-ld/)
-   [JSON-LD 1.1 处理算法和API](https://json-ld.org/spec/FCGS/json-ld-api/20180607/), (中文(简体) ), 社区小组报告草稿, 2018-06-07或 (中文(简体) ) [更新](https://json-ld.org/spec/latest/json-ld-api/)
-   [JSON-LD 1.1 阵容](https://json-ld.org/spec/FCGS/json-ld-framing/20180607/), (中文(简体) ), 社区小组报告草稿, 2018-06-07或 (中文(简体) ) [更新](https://json-ld.org/spec/latest/json-ld-framing/)
-   社区团体 [测试套件](https://github.com/json-ld/json-ld.org/tree/master/test-suite)

这个 [JSON-LD工作组](https://www.w3.org/2018/json-ld-wg/) 目前正在开发JSON-LD 1.1。 图书馆 随着特性稳定,将进行更新,以符合新的规格 开发时间和资源允许.

-   [JSON-LD 1.1 导弹](https://www.w3.org/TR/json-ld11/), (中文(简体) ), W3C 工作草案, 2018-12-14年或 [更新](https://w3c.github.io/json-ld-syntax/)
-   [JSON-LD 1.1 处理算法和API](https://www.w3.org/TR/json-ld11-api/), (中文(简体) ), W3C 工作草案, 2018-12-14年或 [更新](https://w3c.github.io/json-ld-api/)
-   [JSON-LD 1.1 阵容](https://www.w3.org/TR/json-ld11-framing/), (中文(简体) ), W3C 工作草案, 2018-12-14年或 [更新](https://w3c.github.io/json-ld-framing/)
-   工作组 [测试套件](https://github.com/w3c/json-ld-api/tree/master/tests)

这个 [测试跑道](https://github.com/digitalbazaar/jsonld.js/blob/master/tests/test-common.js) 常被更新以注意或跳过非新测试 但仍得到支持.

## 安装

### 节点.js + npm

```
npm install jsonld
```

```js
const jsonld = require('jsonld');
```

### 浏览器 (bundler) + npm

```
npm install jsonld
```

使用您最喜欢的捆绑技术( E)[网络软件包](https://webpack.js.org/), (中文(简体) ), [滚动](https://rollupjs.org/)(等)改为 直接捆绑装入的代码 `jsonld`。请注意,您需要支持 为ES2017+代码.

### 浏览器 Bundles

已建npm包包括了适合用于浏览器的捆绑代码. 两个 现提供版本:

-   `./dist/jsonld.min.js`: 为与现代兼容而构建的版本 和旧浏览器。 包括许多多填充和代码转换 规模较大,效率较低.
-   `./dist/jsonld.esm.min.js`: 为可用特性构建的版本 支持ES模块的浏览器. 减少多填充和变换 需要使代码更小和更有效率.

这两个捆绑可以同时使用,以允许现代浏览器使用 新的代码。 使用搜索 `script` 标记为 `type="module"` 财务报告和审定财务报表 `nomodule`。 。 。 .

另见 `webpack.config.js` 如果您想做一个自定义捆绑 具体目标.

#### 浏览器( AMD) + npm

```
npm install jsonld
```

使用您最喜欢的技术加载 `node_modules/dist/jsonld.min.js`。 。 。 .

#### CDNJS 光盘

用于 [光盘](https://cdnjs.com/) 包含此脚本标签 :

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/jsonld/1.0.0/jsonld.min.js"></script>
```

检查 [https://cdnjs.com/librarys/jsonld (中文(简体) )](https://cdnjs.com/libraries/jsonld) 用于提供最新版本.

#### js 交付CDN

用于 [js 交付](https://www.jsdelivr.com/) 包含此脚本标签 :

```html
<script src="https://cdn.jsdelivr.net/npm/jsonld@1.0.0/dist/jsonld.min.js"></script>
```

见 [https://www.jsdelivr.com/package/npm/jsonld (中文(简体) )](https://www.jsdelivr.com/package/npm/jsonld) 用于提供最新版本.

#### 破伤风

用于 [(单位:公斤)](https://unpkg.com/) 包含此脚本标签 :

```html

<script src="https://unpkg.com/jsonld@1.0.0/dist/jsonld.min.js"></script>
```

见 [https://unpkg.com/jsonld/ (中文(简体) )](https://unpkg.com/jsonld/) 用于提供最新版本.

### JSPM 联合媒体

```
jspm install npm:jsonld
```

```js
import * as jsonld from 'jsonld';
// or
import {promises} from 'jsonld';
// or
import {JsonLdProcessor} from 'jsonld';
```

### 节点.js 土生土长的束缚

对于特殊用途案件,可选择 [rdf- canonize- 本土化](https://github.com/digitalbazaar/rdf-canonize-native) 软件包 提供本地执行 `canonize()`。它被使用 通过安装软件包和设置 `useNative` 选项 `canonize()` 改为 `true`。在使用该模式之前,它是 **高度建议** 运行基准 因为 JavaScript 执行往往更快, 绑定器会添加 工具链复杂.

```
npm install jsonld
npm install rdf-canonize-native
```

## 实例

以下各例中所使用的示例数据和背景:

```js
const doc = {
  "http://schema.org/name": "Manu Sporny",
  "http://schema.org/url": {"@id": "http://manu.sporny.org/"},
  "http://schema.org/image": {"@id": "http://manu.sporny.org/images/manu.png"}
};
const context = {
  "name": "http://schema.org/name",
  "homepage": {"@id": "http://schema.org/url", "@type": "@id"},
  "image": {"@id": "http://schema.org/image", "@type": "@id"}
};
```

### [紧凑](https://json-ld.org/spec/latest/json-ld/#compacted-document-form)

```js
// compact a document according to a particular context
const compacted = await jsonld.compact(doc, context);
console.log(JSON.stringify(compacted, null, 2));
/* Output:
{
  "@context": {...},
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/",
  "image": "http://manu.sporny.org/images/manu.png"
}
*/

// compact using URLs
const compacted = await jsonld.compact(
  'http://example.org/doc', 'http://example.org/context', ...);
```

### [扩展](https://json-ld.org/spec/latest/json-ld/#expanded-document-form)

```js
// expand a document, removing its context
const expanded = await jsonld.expand(compacted);
/* Output:
{
  "http://schema.org/name": [{"@value": "Manu Sporny"}],
  "http://schema.org/url": [{"@id": "http://manu.sporny.org/"}],
  "http://schema.org/image": [{"@id": "http://manu.sporny.org/images/manu.png"}]
}
*/

// expand using URLs
const expanded = await jsonld.expand('http://example.org/doc', ...);
```

### [平调](https://json-ld.org/spec/latest/json-ld/#flattened-document-form)

```js
// flatten a document
const flattened = await jsonld.flatten(doc);
// output has all deep-level trees flattened to the top-level
```

### [边框](https://json-ld.org/spec/latest/json-ld-framing/#introduction)

```js
// frame a document
const framed = await jsonld.frame(doc, frame);
// output transformed into a particular tree structure per the given frame
```

### [划线](https://w3c.github.io/rdf-canon/spec/) (规范化)

```js
// canonize (normalize) a document using the RDF Dataset Canonicalization Algorithm
// (URDNA2015):
const canonized = await jsonld.canonize(doc, {
  algorithm: 'URDNA2015',
  format: 'application/n-quads'
});
// canonized is a string that is a canonical representation of the document
// that can be used for hashing, comparison, etc.
```

### 东德(N-四方)

```js
// serialize a document to N-Quads (RDF)
const nquads = await jsonld.toRDF(doc, {format: 'application/n-quads'});
// nquads is a string of N-Quads
```

### 来自RDF(N-Quads)

```js
// deserialize N-Quads (RDF) to JSON-LD
const doc = await jsonld.fromRDF(nquads, {format: 'application/n-quads'});
// doc is JSON-LD
```

### 自定义 RDF 解析器

```js
// register a custom synchronous RDF parser
jsonld.registerRDFParser(contentType, input => {
  // parse input to a jsonld.js RDF dataset object... and return it
  return dataset;
});

// register a custom promise-based RDF parser
jsonld.registerRDFParser(contentType, async input => {
  // parse input into a jsonld.js RDF dataset object...
  return new Promise(...);
});
```

### 自定义文档加载器

```js
// how to override the default document loader with a custom one -- for
// example, one that uses pre-loaded contexts:

// define a mapping of context URL => context doc
const CONTEXTS = {
  "http://example.com": {
    "@context": ...
  }, ...
};

// grab the built-in Node.js doc loader
const nodeDocumentLoader = jsonld.documentLoaders.node();
// or grab the XHR one: jsonld.documentLoaders.xhr()

// change the default document loader
const customLoader = async (url, options) => {
  if(url in CONTEXTS) {
    return {
      contextUrl: null, // this is for a context via a link header
      document: CONTEXTS[url], // this is the actual document that was loaded
      documentUrl: url // this is the actual context URL after redirects
    };
  }
  // call the default documentLoader
  return nodeDocumentLoader(url);
};
jsonld.documentLoader = customLoader;

// alternatively, pass the custom loader for just a specific call:
const compacted = await jsonld.compact(
  doc, context, {documentLoader: customLoader});
```

### 节点.js 文档加载器用户代理

建议设置默认值 `user-agent` 节点.js 的标题 应用。 默认的节点文件加载器默认为 `jsonld.js`。 。 。 .

### 安全模式

常见的用法是避免JSON-LD构造导致损失 行为 JSON-LD规格有关于数据何时被放弃的注释. 这在打电话时特别重要`canonize`\[ 以便 数字签名数据。 特殊“ 安全模式” 可以检测到这些 并导致处理失败.

**说明**:这种模式的设计是数字签名和 类似的应用程序使用此库.

这个 `safe` 选项标记设置为 `true` 启用此行为 :

```js
// expand a document in safe mode
const expanded = await jsonld.expand(data, {safe: true});
```

## 测试

这个库包括一个样本测试工具,可用于验证 对处理器的更改保持正确的输出.

主要测试套房包含在外置寄存器中. 检查每个 目标如下:

```
https://github.com/w3c/json-ld-api
https://github.com/w3c/json-ld-framing
https://github.com/json-ld/json-ld.org
https://github.com/w3c/rdf-canon
```

它们应该是jsonld.js目录的姊妹目录,或者在一个 `test-suites` 目录 。 复制浅拷贝到 `test-suites` 您可以打开目录 使用下列方法:

```
npm run fetch-test-suites
```

节点.js测试可以使用简单的命令运行:

```
npm test
```

如果您在别处安装了测试套房, 或者希望运行其他测试, 请使用 页:1 `TESTS` 环境 var:

```
TESTS="/tmp/org/test-suites /tmp/norm/tests" npm test
```

这个功能可用于运行更古老的json-ld.org测试套件:

```
TESTS=/tmp/json-ld.org/test-suite npm test
```

浏览器测试可以用Karma进行:

```
npm run test-karma
npm run test-karma -- --browsers Firefox,Chrome
```

节点测试的代码覆盖可生成于 `coverage/`数字 :

```
npm run coverage
```

从覆盖数据显示控制台的全覆盖报告:

```
npm run coverage-report
```

Mocha 输出报告器可以被更改为min, dot,list,nyan等:

```
REPORTER=dot npm test
```

还提供远程上下文测试:

```
# run the context server in the background or another terminal
node tests/remote-context-server.js

TESTS=`pwd`/tests npm test
```

生成EARL报告:

```
# generate the EARL report for Node.js
EARL=earl-node.jsonld npm test

# generate the EARL report for the browser
EARL=earl-firefox.jsonld npm run test-karma -- --browser Firefox
```

编写EAR报告 `json-ld-api` 财务报告和审定财务报表 `json-ld-framing` 测试 用于官方 [JSON-LD 处理器](https://w3c.github.io/json-ld-api/reports) 页 次

```
TESTS="`pwd`/../json-ld-api/tests `pwd`/../json-ld-framing/tests" EARL="jsonld-js-earl.jsonld" npm test
```

地狱 `.jsonld` 输出可转换为 `.ttl` 使用 [页:1](https://rubygems.org/gems/rdf) 工具:

```
rdf serialize jsonld-js-earl.jsonld --output-format turtle -o jsonld-js-earl.ttl
```

可选择遵循 [报告 指令](https://github.com/w3c/json-ld-api/tree/master/reports) 改为 生成 HTML 报表以供检查。 维护者可以 [提交](https://github.com/w3c/json-ld-api/pulls) 视需要更新成果.

## 基准

可从测试系统支持的任何表单中创建基准. 使用带有测试套件和基准旗的命令行 :

```
TESTS=/tmp/benchmark-manifest.jsonld BENCHMARK=1 npm test
```

在可选环境中可生成带有基准数据的EARL报告 细节 :

```
TESTS=`pwd`/../json-ld.org/benchmarks/b001-manifiest.jsonld BENCHMARK=1 EARL=earl-test.jsonld TEST_ENV=1 npm test
```

见 `tests/test.js` 为了更多 `TEST_ENV` 财务报告和审定财务报表 `BENCHMARK` 控制和选项.

这些报告可以与本报告相比较 `benchmarks/compare/` 工具及在 [JSON-LD 基准](https://json-ld.org/benchmarks/) 网站.

## 相关模块

-   [jsonld-cli (英语)](https://github.com/digitalbazaar/jsonld-cli): 一个名为命令行接口的工具 `jsonld` 这暴露了 大多数基础jsonld.js API.
-   [jsonld 请求](https://github.com/digitalbazaar/jsonld-request): 从 stdin、 URL 和文件读取数据的模块 和各种格式,并返回 JSON-LD.

## 来源

JSON- LD API 的 JavaScript 执行的源代码 可在下列地点获得:

[https://github.com/digitalbazaar/jsonld.js (中文(简体) )](https://github.com/digitalbazaar/jsonld.js)

## 商业支助

该图书馆的商务支助可应下列请求提供: [数字集市](https://digitalbazaar.com/)数字 : [支持@ digitalbazaar.com](mailto:support@digitalbazaar.com)

## 常见问题

### @digitalcredentials/jsonld 是什么？

一个JSON-LD处理器和JavaScript中的API执行\.

### 如何安装 @digitalcredentials/jsonld？

在项目目录运行 npm install @digitalcredentials/jsonld，或使用 pnpm add / yarn add / bun add。

### @digitalcredentials/jsonld 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/digitalcredentials\_\_jsonld 是否存在。

### @digitalcredentials/jsonld 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @digitalcredentials/jsonld 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @digitalcredentials/jsonld 可以商用吗？

@digitalcredentials/jsonld 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @digitalcredentials/jsonld 的下载量有多少？

根据 npm 官方下载统计，@digitalcredentials/jsonld 在 2026/10/12 – 2026/11/10 这 30 天内被下载 103,647 次，日均约 3,455 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @digitalcredentials/jsonld 还在维护吗？

最新版本 9\.0\.0 发布于 2024/08/04（2 年前）；至今共发布 6 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/05/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。