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

Zod 验证计划并生成 JSON Schemas 用于 IPFS 元数据 胡萝卜 生态系统。 支持无害环境管理和CJS.

安装

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

需要节点.js 22

可用的外观

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

使用量

验证

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);
}

类型脚本

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;
}

共享原始内容

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

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

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

JSON Schema 参考文献

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

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

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

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

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

建筑

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

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

源结构

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 字段 :

"$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 发布

发展

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 和类型出口核查.

测试

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

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

许可证

Apache 许可证 2.0。仅供公众参考和验证。 见 通知 使用限制.