# @finos/fdc3-schema 中文文档

规范地址：https://npmcn.com/package/%40finos/fdc3-schema/

版本：3\.0\.0
npm 元数据更新时间：2026-10-26T14:57:44.506Z
中文译文更新时间：2026-11-14T19:01:14.110Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40finos/fdc3-schema
原文对照：https://npmcn.com/package/%40finos/fdc3-schema/?lang=original
项目主页：https://fdc3.finos.org/
源码仓库：https://github.com/finos/FDC3

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

- 包体积（解压后）：994 kB，172 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2025-01-14T17:24:04.769Z
- 最新版本发布：2026-10-26T14:57:43.720Z
- 近 30 天下载量：34609（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 9 个）

## 中文简介

此软件包既持有由它们生成的用于定义FDC3桌面代理Britching协议和Web Connection协议(WCP)和桌面代理COmmunication协议(D)中使用的JSON消息格式的图案文件和类型

## 安装

```sh
npm install @finos/fdc3-schema
```

也可以使用：`pnpm add @finos/fdc3-schema`、`yarn add @finos/fdc3-schema`、`bun add @finos/fdc3-schema`

## README

# FDC3 连接和FDC3 用于网络信件Schemas

此软件包既持有由它们生成的用于定义FDC3桌面代理Britching协议和允许FDC3用于Web浏览器的Web连接代理COmmunication协议(WCP)和桌面代理COmmunication协议(DACP)所使用的JSON消息格式的图案文件和TypeScript类型.

在此软件包中分发的Schema文件也部署在它们给出的地点的网上 `$id` 字段,可见FDC3文件的有关章节([桥梁](https://fdc3.finos.org/docs/next/agent-bridging/spec), (中文(简体) ), [Web 连接协议](https://fdc3.finos.org/docs/next/api/specs/webConnectionProtocol), (中文(简体) ), [桌面代理通信协议](https://fdc3.finos.org/docs/next/api/specs/desktopAgentCommunicationProtocol)) (中文(简体) ).

TypeScript 类型由每个计划产生,可以作为一组从包中导入:

```ts
import { BrowserTypes, BridgingTypes } from '@finos/fdc3-schema';
```

或个人:

```ts
import {
  GetUserChannelsRequest,
  JoinUserChannelRequest,
  LeaveCurrentChannelRequest
} from '@finos/fdc3-schema/dist/generated/api/BrowserTypes.js';
```

详情:

-   [https://github.com/finos/FDC3 请检查isbn=值 (帮助)](https://github.com/finos/FDC3)
-   [FDC3 规格](https://fdc3.finos.org/)
-   主要FDC3单元:https://www.npmjs.com/package/@finos/fdc3

## 信件类型生成注释

此文件夹包含 Typescription 接口, 由上下文 JSONSchema 生成 BritchingTypes.ts ()[https://json-schema.org/ (中文(简体) )](https://json-schema.org/)通过快取类型的文件( )[https://quicktype.io/ 互联网档案馆的存檔,存档日期2013-12-02](https://quicktype.io/)) (中文(简体) ). 也可以用Quicktype支持的其他语言为我们生成源文件.

请注意,提供这些定义是为了帮助在TypeScript中工作的开发者为Web消息对象生成有效的接通或FDC3——但不应被认为是消息定义的"真理之源"(而不是看图和文档).

并非总能通过 TypeScript 完美地复制 JSONSchema 中定义的类型/界面. 因此,如果定义之间有任何分歧,JSON Schema应该被假定是正确的,而不是TypeScript. 例如,JSON Schema可以定义对象+附加属性类型的限制上的可选字段(通过 `"additionalProperties": { "type": "string"}`)),将产生索引签名 `[property: string]: string;` 在生成的 TypeScript 中。 该签名与可选属性(包括字符串属性)不兼容,因为它们有类型 `string | undefined`JSON Schema中可能会出现类似的问题,如果使用这个方案通过组分生成一个子类型: `additionalProperties` 并不知道子schema的定义。 两个问题都可以通过使用 `unevaluatedProperties` 在 schema 中,它将遵从 subschema 中可选属性的已声明类型,但目前也被 Quicktype 所忽略 - 导致一种将编译但不限制 schema 中定义的可选属性值的类型.

此外,Quicktype并不总是完全复制指定的多形态字段 `oneOf` 或者说 `allOf` 在 JSON Schema 中,因为它通常会将不同的对象合并成单一类型(其中不包含在某一组成方案中的字段成为可选),而不是创建一个联盟类型。 在这种情况下,生产的类型可以使用(具有所有必要字段),但可能允许建造缺失必要属性的无效实例,或者包括多种组合的特性,根据JSON Schema,这些特性是不可能/有效的.

因此,这里提供的类型可用于提供有效的消息对象并读取/写入他们的JSON编码,但可能无法检测或防止JSON Schema识别出有限的一组无效对象.

最后,Quicktype将生成代表schema子单元的类型或接口,然后在主界面定义中引用. 这些往往没有独有的名称(出自图中的标题字段). 如果遇到名称冲突,Quicktype会为这样的接口生成一个随机名称,用于引用,由于是随机生成的,它可能显得奇怪地命名(例如. `PurpleId`, (中文(简体) ), `FluffyMarket`, (中文(简体) ), `TentacledIdentifier` 页:1 请忽略这些名称,因为这些类型/界面通常不会在主类型组成之外使用,例如:

```TypeScript
export interface Instrument {
  id: StickyId;
  market?: FluffyMarket;
  type: string;
  name?: string;
  [property: string]: any;
}

export interface StickyId {
  BBG?: string;
  CUSIP?: string;
  FDS_ID?: string;
  FIGI?: string;
  ISIN?: string;
  PERMID?: string;
  RIC?: string;
  SEDOL?: string;
  ticker?: string;
  [property: string]: any;
}

export interface FluffyMarket {
  BBG?: string;
  COUNTRY_ISOALPHA2?: string;
  MIC?: string;
  name?: string;
  [property: string]: any;
}
```

并且不应被视为该类型结构的计划部分(不应被任何衍生作品所复制). 在应用时,不使用这些子单元的命名,而是用其内容来取而代之. 为这些子单位生成更好的名称通常是一个添加或调整的例子 `title` 字段.

最后,请注意最新版本的Quicktype(在编写本报告时) `23.0.49`) 有一些错误必须围绕:

-   使用目录或.schema.json文件作为源会引发输入类型参数 `-s schema` 被忽略,导致文件被解释为JSON而不是JSON Schema.
    -   该存储库提供了一种工具(_././快速型Util.js_) 围绕此错误工作, 方法是列出目录并构建快速类型的呼叫, 每个文件都作为单个源提供 .
-   设置 `--nice-property-names` TypeScript 输出选项将崩溃生成器,无法使用.
-   \--debug 设置必须是第一个通过的参数, 否则会被忽略 .

## 常见问题

### @finos/fdc3-schema 是什么？

此软件包既持有由它们生成的用于定义FDC3桌面代理Britching协议和Web Connection协议\(WCP\)和桌面代理COmmunication协议\(D\)中使用的JSON消息格式的图案文件和类型

### 如何安装 @finos/fdc3-schema？

在项目目录运行 npm install @finos/fdc3-schema，或使用 pnpm add / yarn add / bun add。

### @finos/fdc3-schema 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @finos/fdc3-schema 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @finos/fdc3-schema 需要什么版本的 Node\.js？

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

### @finos/fdc3-schema 可以商用吗？

@finos/fdc3-schema 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @finos/fdc3-schema 的下载量有多少？

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

### @finos/fdc3-schema 还在维护吗？

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