@carrot-foundation/schemas 0.2.4 → 0.3.1

package/README.md

@@ -1,172 +1,200 @@
-# 🥕 Carrot IPFS Schemas
+# @carrot-foundation/schemas
 
-This repository contains all JSON Schemas used across the Carrot ecosystem.
+[![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)](./LICENSE)
 
-These schemas define the structure of IPFS metadata for tokenized assets and other schemas.
+Zod validation schemas and generated JSON Schemas for IPFS metadata in the [Carrot](https://carrot.eco) ecosystem. Supports ESM and CJS.
 
-They are versioned, publicly referenceable, and used for validation, traceability, and frontend/backend integration.
-
-## 📦 Structure
-
-- Schemas are organized by type (e.g., `mass-id`, `gas-id`, `shared`) and follow [Semantic Versioning](https://semver.org/), but folder names are not versioned.
-- Each schema lives in its own folder and includes an `example.json` for testing and documentation.
-- Shared components are located in `src/shared/**`.
-
-## 🔖 Versioning
-
-This project uses automated schema reference versioning with a **unified versioning approach** for both development and production environments. All schema `$id` fields always reference Git tags, ensuring consistency across all environments.
-
-### How It Works
-
-- **All builds**: Schemas reference `refs/tags/{version}` where version is set via `SCHEMA_VERSION` environment variable
-- **Default version**: If `SCHEMA_VERSION` is not set, defaults to the version from `package.json`
-- **No special cases**: Development and production use the exact same versioning mechanism
-
-### Local Development
-
-For local development, the version from `package.json` is used automatically:
+## Installation
 
 ```bash
-# Build with package.json version as default
-pnpm build
-pnpm generate-ipfs-schemas
-```
-
-### Development Tag Management
-
-To test a versioned build locally:
-
-```bash
-# Build with a specific version
-SCHEMA_VERSION=1.2.3 pnpm build
-SCHEMA_VERSION=1.2.3 pnpm generate-ipfs-schemas
-SCHEMA_VERSION=1.2.3 pnpm verify-schema-versions
+pnpm add @carrot-foundation/schemas
+# or
+npm install @carrot-foundation/schemas
 ```
 
-### Release Process
+> Requires Node.js >= 22
 
-The release process automatically:
+## Available Schemas
 
-1. Calculates the next version based on conventional commits
-2. Builds the package with the new version embedded
-3. Generates JSON schemas with versioned `$id` references
-4. Creates a Git tag
-5. Publishes to npm
-6. Creates a GitHub release
+| Category      | Schema                              | Description                                        |
+| ------------- | ----------------------------------- | -------------------------------------------------- |
+| **Assets**    | `MassIDIpfsSchema`                  | Waste tracking tokens with chain of custody events |
+|               | `GasIDIpfsSchema`                   | Gas/emissions reduction tokens                     |
+|               | `RecycledIDIpfsSchema`              | Recycled material tokens                           |
+|               | `CreditSchema`                      | Environmental credit tokens                        |
+|               | `CollectionSchema`                  | Collection metadata for grouped assets             |
+| **Receipts**  | `CreditPurchaseReceiptIpfsSchema`   | Proof of credit purchase transactions              |
+|               | `CreditRetirementReceiptIpfsSchema` | Proof of credit retirement transactions            |
+| **Audit**     | `MassIDAuditSchema`                 | Audit trail records for MassID tokens              |
+| **Reference** | `MethodologySchema`                 | Methodology definitions and rules                  |
 
-All of this happens automatically via the GitHub Actions workflow when you push to `main`.
+Asset, receipt, audit, and reference schema types also export their data schema where applicable (e.g., `MassIDDataSchema`) and inferred TypeScript types (e.g., `MassIDIpfs`, `MassIDData`).
 
-### Example Schema References
+## Usage
 
-**Development (uses package.json version by default):**
+### Validation
 
-```json
-"$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/0.1.28/schemas/ipfs/mass-id/mass-id.schema.json"
-```
+```typescript
+import { MassIDIpfsSchema } from '@carrot-foundation/schemas';
 
-**Production (versioned via SCHEMA_VERSION env var):**
+const result = MassIDIpfsSchema.safeParse(data);
 
-```json
-"$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/1.2.3/schemas/ipfs/mass-id/mass-id.schema.json"
+if (result.success) {
+  console.log('Valid MassID record:', result.data);
+} else {
+  console.error('Validation errors:', result.error.issues);
+}
 ```
 
-## 📚 Package Usage
+### TypeScript Types
 
-This package is published to npm as `@carrot-foundation/schemas` and supports both **ESM** and **CommonJS** module formats.
+```typescript
+import type { MassIDIpfs, Credit } from '@carrot-foundation/schemas';
 
-### Installation
+// NFT-based schemas include blockchain, attributes, and data
+function processMassID(record: MassIDIpfs) {
+  const { data, blockchain, attributes } = record;
+}
 
-```bash
-npm install @carrot-foundation/schemas
-# or
-pnpm add @carrot-foundation/schemas
-# or
-yarn add @carrot-foundation/schemas
+// Non-NFT schemas extend BaseIpfsSchema directly
+function processCredit(record: Credit) {
+  const { schema, created_at, external_id } = record;
+}
 ```
 
-### ESM (ECMAScript Modules)
+### Shared Primitives
 
-```typescript
-import { MassIDIpfsSchema, MassIDDataSchema } from '@carrot-foundation/schemas';
+The package exports reusable building blocks for custom schemas:
 
-// Use the schemas for validation
-const result = MassIDIpfsSchema.safeParse(data);
+```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';
 ```
 
 ### CommonJS
 
 ```javascript
-const {
-  MassIDIpfsSchema,
-  MassIDDataSchema,
-} = require('@carrot-foundation/schemas');
-
-// Use the schemas for validation
-const result = MassIDIpfsSchema.safeParse(data);
+const { MassIDIpfsSchema } = require('@carrot-foundation/schemas');
 ```
 
-### TypeScript Support
+### JSON Schema References
 
-The package includes full TypeScript definitions:
+Generated JSON Schemas are available at stable URLs and included in the npm package under `schemas/`:
 
-```typescript
-import { MassIDIpfs, MassIDData } from '@carrot-foundation/schemas';
+```text
+https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/{version}/schemas/ipfs/{type}/{type}.schema.json
+```
 
-// Types are automatically inferred from the schemas
-const massIDData: MassIDData = {
-  // ...
-};
+Example JSON data for each schema is also available:
+
+```text
+schemas/ipfs/mass-id/mass-id.schema.json
+schemas/ipfs/mass-id/mass-id.example.json
 ```
 
-## 🧪 Testing
+Published examples are generated from the shared reference story and then
+post-processed with schema/version/hash metadata. Edit the reference story
+or emitter modules instead of hand-editing emitted example JSON.
 
-This repository uses [Vitest](https://vitest.dev/) for automated testing. Tests validate that schemas correctly validate example data and reject invalid inputs.
+## Architecture
 
-### Running Tests
+Schemas follow a layered composition pattern using Zod's `.safeExtend()`:
 
-```bash
-# Run all tests once
-pnpm test
+```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
+```
 
-# Run tests in watch mode
-pnpm test:watch
+### Source Structure
+
+```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
+```
+
+## Versioning
 
-# Run tests with coverage report
-pnpm test:coverage
+Schema `$id` fields reference Git tags for stable, immutable URLs:
 
-# Open Vitest UI for interactive testing
-pnpm test:ui
+```json
+"$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/0.2.4/schemas/ipfs/mass-id/mass-id.schema.json"
 ```
 
-### Test Structure
+- **Default**: version from `package.json`
+- **CI/Release**: set via `SCHEMA_VERSION` environment variable
+- **Local override**: `SCHEMA_VERSION=1.2.3 pnpm build`
 
-Tests are located alongside their schemas in `src/**/*.spec.ts` files. Each test file validates:
+### Release Process
 
-- Example JSON files pass schema validation
-- Invalid data is properly rejected
-- Type inference works correctly
-- Edge cases are handled appropriately
+Automated via GitHub Actions on push to `main`:
 
-### Coverage
+1. Determines version bump from conventional commits
+2. Builds the package with the version embedded in schema `$id` URLs
+3. Generates JSON Schemas, hashes, and examples
+4. Creates a Git tag, publishes to npm, creates a GitHub release
 
-Coverage thresholds are set at **100%** for branches, functions, lines, and statements.
+## Development
 
-## ✅ Usage
+```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
+```
 
-You may:
+### Quality Gates (`pnpm check`)
 
-- Reference any schema via its `$id` (e.g. in IPFS metadata)
-- Validate metadata files using these schemas
-- Link to them from applications, dashboards, or traceability tools
+Lint, format, type-check, spell-check, schema generation, hash verification, example updates, schema validation, version verification, reference checks, example validation, tests, dead code detection, license check, bundle size, publint, and type export verification.
 
-You may not:
+### Testing
 
-- Redistribute, rebrand, or fork these schemas for other ecosystems
-- Create derivative schemas that use Carrot's identity
+```bash
+pnpm test                         # Run once
+pnpm test:watch                   # Watch mode
+pnpm test:coverage                # Coverage report
+pnpm test:ui                      # Vitest UI
+```
 
-See [NOTICE](./NOTICE) for full usage guidance.
+Tests validate schema acceptance of valid data, rejection of invalid data, type inference, and cross-field refinements. Coverage thresholds: **100%** for branches, functions, lines, and statements.
 
-## 🔐 License
+## License
 
-Licensed under the [Apache License 2.0](./LICENSE).
-See [NOTICE](./NOTICE) for additional terms and usage intentions.
+[Apache License 2.0](./LICENSE). For public reference and validation only. See [NOTICE](./NOTICE) for usage restrictions.