# @carrot-foundation/schemas 中文文档

规范地址：https://npmcn.com/package/%40carrot-foundation/schemas/

版本：6\.1\.1
npm 元数据更新时间：2026-11-06T10:36:35.014Z
中文译文更新时间：2026-11-09T20:52:56.269Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40carrot-foundation/schemas
原文对照：https://npmcn.com/package/%40carrot-foundation/schemas/?lang=original
项目主页：https://github.com/carrot-foundation/schemas#readme
源码仓库：https://github.com/carrot-foundation/schemas

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

- 包体积（解压后）：5.1 MB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2025-10-08T15:06:13.438Z
- 最新版本发布：2026-11-06T10:36:34.622Z
- 近 30 天下载量：1735（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：77（近 12 个月 70 个）

## 中文简介

Carrot schema 定义和 Zod 验证计划

## 安装

```sh
npm install @carrot-foundation/schemas
```

也可以使用：`pnpm add @carrot-foundation/schemas`、`yarn add @carrot-foundation/schemas`、`bun add @carrot-foundation/schemas`

## README

# @carrot- foundation/ schemas (中文(简体) )

[![npm version](https://img.shields.io/npm/v/@carrot-foundation/schemas)](https://www.npmjs.com/package/@carrot-foundation/schemas) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://npmcn.com/package/%40carrot-foundation/schemas/LICENSE)

Zod 验证计划并生成 JSON Schemas 用于 IPFS 元数据 [胡萝卜](https://carrot.eco/) 生态系统。 支持无害环境管理和CJS.

## 安装

```bash
pnpm add @carrot-foundation/schemas
# or
npm install @carrot-foundation/schemas
```

> 需要节点.js 22

## 可用的外观

| 类别 | 司马 | 说明 |
| --- | --- | --- |
| **资产** | `MassIDIpfsSchema` | 带有监管链事件的废物跟踪标志 |
|  | `GasIDIpfsSchema` | 气体/排放减少指数 |
|  | `RecycledIDIpfsSchema` | 回收的材料符号 |
|  | `CreditSchema` | 环境信贷券 |
|  | `CollectionSchema` | 收集分类资产元数据 |
| **收款** | `CreditPurchaseReceiptIpfsSchema` | 信用购买交易的证据 |
|  | `CreditRetirementReceiptIpfsSchema` | 信用退休交易证明 |
| **审计** | `MassIDAuditSchema` | MassID 令牌的审计线索记录 |
| **参考文献** | `MethodologySchema` | 方法定义和规则 |

资产、收货、审计和参考计划类型也酌情输出其数据计划(例如:, `MassIDDataSchema`)和推断出类型(例如, `MassIDIpfs`, (中文(简体) ), `MassIDData`) (中文(简体) ).

## 使用量

### 验证

```typescript
import { MassIDIpfsSchema } from '@carrot-foundation/schemas';

const result = MassIDIpfsSchema.safeParse(data);

if (result.success) {
  console.log('Valid MassID record:', result.data);
} else {
  console.error('Validation errors:', result.error.issues);
}
```

### 类型脚本

```typescript
import type { MassIDIpfs, Credit } from '@carrot-foundation/schemas';

// NFT-based schemas include blockchain, attributes, and data
function processMassID(record: MassIDIpfs) {
  const { data, blockchain, attributes } = record;
}

// Non-NFT schemas extend BaseIpfsSchema directly
function processCredit(record: Credit) {
  const { schema, created_at, external_id } = record;
}
```

### 共享原始内容

套件导出可重复使用的自定义方案构件 :

```typescript
import {
  IsoDateTimeSchema, // ISO 8601 date-time strings
  Sha256HashSchema, // SHA-256 hash validation
  IpfsUriSchema, // IPFS URI format (ipfs://...)
  SemanticVersionSchema, // Semver strings
  UuidSchema, // UUID v4
  LatitudeSchema, // Geographic coordinates
  LongitudeSchema,
  ParticipantSchema, // Stakeholder entities
  LocationSchema, // Geographic locations
} from '@carrot-foundation/schemas';
```

### 常见JS

```javascript
const { MassIDIpfsSchema } = require('@carrot-foundation/schemas');
```

### JSON Schema 参考文献

生成 JSON 在稳定的 URL 中可以提供模型,并包含在 npm 包中 `schemas/`数字 :

```text
https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/v{version}/schemas/ipfs/{type}/{type}.schema.json
```

还可以提供每个计划的JSON示例数据:

```text
schemas/ipfs/mass-id/mass-id.schema.json
schemas/ipfs/mass-id/mass-id.example.json
```

发表的例子来自共同的参考故事,然后 后处理有计划/版本/hash元数据。 编辑参考故事 或发射模块,而不是手动编辑 释放出的例子JSON.

## 建筑

Schemas采用Zod的分层组成模式 `.safeExtend()`数字 :

```text
BaseIpfsSchema            Common IPFS record fields ($schema, created_at, external_id, ...)
├─ NftIpfsSchema          NFT fields (blockchain, name, description, image, attributes)
│    └─ Asset/Receipt     MassIDIpfsSchema, GasIDIpfsSchema, RecycledIDIpfsSchema,
│         Schemas         CreditPurchaseReceiptIpfsSchema, CreditRetirementReceiptIpfsSchema
└─ Non-NFT Schemas        CreditSchema, CollectionSchema, MassIDAuditSchema, MethodologySchema
```

### 源结构

```text
src/
├── mass-id/                    # Example: NFT schema type (has all files)
│   ├── mass-id.schema.ts       #   IPFS schema (extends NftIpfsSchema)
│   ├── mass-id.data.schema.ts  #   Type-specific data structure
│   ├── mass-id.attributes.ts   #   NFT display attributes
│   ├── index.ts                #   Public exports
│   └── __tests__/              #   Tests (100% coverage enforced)
├── credit/                     # Example: non-NFT schema type (simpler structure)
│   ├── credit.schema.ts        #   Schema (extends BaseIpfsSchema directly)
│   ├── index.ts
│   └── __tests__/
├── shared/
│   ├── schemas/
│   │   ├── core/               #   BaseIpfsSchema, NftIpfsSchema, attributes
│   │   ├── primitives/         #   Blockchain, time, geo, IDs, hashes, URIs, enums
│   │   ├── entities/           #   Participant, Location
│   │   ├── references/         #   Cross-schema linking (MassID ref, Credit ref, ...)
│   │   ├── receipt/            #   Receipt base schemas
│   │   └── certificate/        #   Certificate schemas
│   ├── schema-version.ts       #   Version management utilities
│   ├── schema-helpers.ts       #   Zod utilities (uniqueArrayItems, uniqueBy)
│   ├── schema-validation.ts    #   Validation helpers
│   ├── hash.ts                 #   Canonical hashing (canonicalize + SHA-256)
│   └── data/                   #   Reference data (Brazil municipalities)
├── test-utils/                 #   Shared fixtures and test assertions
└── index.ts                    #   Package entry point
```

## 版本

司马 `$id` 字段 :

```json
"$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/v0.2.4/schemas/ipfs/mass-id/mass-id.schema.json"
```

-   **默认**: 版本从 `package.json`
-   **刑事调查/释放**: 通过 `SCHEMA_VERSION` 环境变量
-   **本地覆盖**数字 : `SCHEMA_VERSION=1.2.3 pnpm build`

### 释放进程

通过 GitHub 自动启动 `main`数字 :

1.  确定常规承诺的版本折叠
2.  将软件包构建为嵌入图中的版本 `$id` URL( URL)
3.  生成 JSON Schemas, 散列和实例
4.  创建 Git 标签, 发布到 npm, 创建 GitHub 发布

## 发展

```bash
pnpm install                      # Install dependencies
pnpm build                        # TypeScript -> dist/ (ESM + CJS)
pnpm test                         # Run all tests (100% coverage enforced)
pnpm generate-ipfs-schemas        # Generate JSON Schemas from Zod
pnpm check                        # Run ALL quality gates
```

### 质量门`pnpm check`(中文(简体) )

林特 格式 类型检查 拼写检查 计划生成 散列核查 实例更新 计划验证 版本验证 参考检查 实例验证 测试 死码检测 许可证检查 捆绑大小 publint 和类型出口核查.

### 测试

```bash
pnpm test                         # Run once
pnpm test:watch                   # Watch mode
pnpm test:coverage                # Coverage report
pnpm test:ui                      # Vitest UI
```

测试验证了有效数据的接受计划,否定了无效的数据,类型推论,以及跨场的改进. 覆盖率阈值 : **100%** 用于分支、功能、行和语句.

## 许可证

[Apache 许可证 2.0](https://npmcn.com/package/%40carrot-foundation/schemas/LICENSE)。仅供公众参考和验证。 见 [通知](https://npmcn.com/package/%40carrot-foundation/schemas/NOTICE) 使用限制.

## 常见问题

### @carrot-foundation/schemas 是什么？

Carrot schema 定义和 Zod 验证计划

### 如何安装 @carrot-foundation/schemas？

在项目目录运行 npm install @carrot-foundation/schemas，或使用 pnpm add / yarn add / bun add。

### @carrot-foundation/schemas 支持 TypeScript 吗？

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

### @carrot-foundation/schemas 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @carrot-foundation/schemas 需要什么版本的 Node\.js？

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

### @carrot-foundation/schemas 可以商用吗？

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

### @carrot-foundation/schemas 的下载量有多少？

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

### @carrot-foundation/schemas 还在维护吗？

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