@carrot-foundation/schemas 0.1.6

package/dist/shared/nft.schema.js

@@ -0,0 +1,193 @@
+import { z } from 'zod';
+import { BaseIpfsSchema } from './base.schema.js';
+import { EthereumAddressSchema, BlockchainChainIdSchema, TokenIdSchema, IpfsUriSchema, HexColorSchema, NonNegativeFloatSchema, RecordSchemaTypeSchema, } from './definitions.schema.js';
+import { uniqueBy } from './helpers.schema.js';
+const NftSchemaTypeSchema = RecordSchemaTypeSchema.extract([
+    'MassID',
+    'RecycledID',
+    'GasID',
+    'PurchaseID',
+]).meta({
+    title: 'NFT Schema Type',
+    description: 'Type of schema for NFT records',
+});
+const BlockchainReferenceSchema = z
+    .strictObject({
+    smart_contract_address: EthereumAddressSchema.meta({
+        title: 'Smart Contract Address',
+    }),
+    chain_id: BlockchainChainIdSchema.meta({
+        title: 'Chain ID',
+        description: 'Blockchain chain ID',
+    }),
+    network_name: z.string().min(5).max(100).meta({
+        title: 'Network Name',
+        description: 'Name of the blockchain network',
+    }),
+    token_id: TokenIdSchema.meta({
+        title: 'Token ID',
+        description: 'NFT token ID',
+    }),
+})
+    .meta({
+    title: 'Blockchain Information',
+    description: 'Blockchain-specific information for the NFT',
+});
+const ExternalLinkSchema = z
+    .strictObject({
+    label: z.string().min(1).max(50).meta({
+        title: 'Link Label',
+        description: 'Display name for the external link',
+    }),
+    url: z.url('Must be a valid URI').meta({
+        title: 'Link URL',
+        description: 'Direct URI to the linked resource',
+    }),
+    description: z.string().min(10).max(100).optional().meta({
+        title: 'Link Description',
+        description: 'Optional context about what the link provides',
+    }),
+})
+    .meta({
+    title: 'External Link',
+    description: 'External link with label and description',
+});
+const NftAttributeSchema = z
+    .strictObject({
+    trait_type: z.string().max(50).meta({
+        title: 'Trait Type',
+        description: 'Name of the trait or attribute',
+    }),
+    value: z.union([z.string(), z.number(), z.boolean()]).meta({
+        title: 'Trait Value',
+        description: 'Value of the trait - can be string, number, or boolean',
+    }),
+    display_type: z
+        .enum(['number', 'date', 'boost_number', 'boost_percentage'])
+        .optional()
+        .meta({
+        title: 'Display Type',
+        description: 'How the trait should be displayed in marketplace UIs',
+    }),
+    max_value: NonNegativeFloatSchema.optional().meta({
+        title: 'Max Value',
+        description: 'Maximum possible value for numeric traits',
+    }),
+})
+    .meta({
+    title: 'NFT Attribute',
+    description: 'NFT attribute or trait with type and value',
+});
+export const NftIpfsSchema = BaseIpfsSchema.safeExtend({
+    schema: BaseIpfsSchema.shape.schema.safeExtend({
+        type: NftSchemaTypeSchema.meta({
+            title: 'NFT Schema Type',
+            description: 'Type/category of this NFT schema',
+        }),
+    }),
+    blockchain: BlockchainReferenceSchema,
+    name: z
+        .string()
+        .min(1)
+        .max(100)
+        .meta({
+        title: 'NFT Name',
+        description: 'Full display name for this NFT, including extra context',
+        examples: [
+            'MassID #123 • Organic • 3.0t',
+            'RecycledID #456 • Plastic • 2.5t',
+            'GasID #789 • Methane • 1000 m³',
+        ],
+    }),
+    short_name: z
+        .string()
+        .min(1)
+        .max(50)
+        .meta({
+        title: 'Short Name',
+        description: 'Compact name for UI summaries, tables, or tooltips',
+        examples: ['MassID #123', 'RecycledID #456', 'GasID #789'],
+    }),
+    description: z
+        .string()
+        .min(10)
+        .max(500)
+        .meta({
+        title: 'Description',
+        description: "Human-readable summary of the NFT's role and context. Ideally, maximum 300 characters.",
+        examples: [
+            'This MassID represents 3 metric tons of organic food waste from Enlatados Produção, tracked through complete chain of custody from generation to composting.',
+            'This RecycledID represents 2.5 metric tons of recycled plastic bottles processed by Green Solutions Ltd.',
+        ],
+    }),
+    image: IpfsUriSchema.meta({
+        title: 'Image URI',
+        description: 'IPFS URI pointing to the preview image',
+    }),
+    background_color: HexColorSchema.optional().meta({
+        title: 'Background Color',
+        description: 'Hex color code for marketplace background display',
+    }),
+    animation_url: IpfsUriSchema.optional().meta({
+        title: 'Animation URL',
+        description: 'IPFS URI pointing to an animated or interactive media file',
+        examples: [
+            'ipfs://QmAnimation123/mass-id-animation.mp4',
+            'ipfs://QmInteractive456/recycled-visualization.webm',
+        ],
+    }),
+    external_links: uniqueBy(ExternalLinkSchema, (link) => link.url, 'External link URLs must be unique')
+        .max(10)
+        .optional()
+        .meta({
+        title: 'External Links',
+        description: 'Optional list of public resource links with labels',
+        examples: [
+            [
+                {
+                    label: 'Carrot Explorer',
+                    url: 'https://explore.carrot.eco/document/ad44dd3f-f176-4b98-bf78-5ee6e77d0530',
+                    description: 'Complete chain of custody and audit trail',
+                },
+                {
+                    label: 'Carrot White Paper',
+                    url: 'https://carrot.eco/whitepaper.pdf',
+                    description: 'Carrot Foundation technical and impact white paper',
+                },
+            ],
+        ],
+    }),
+    attributes: uniqueBy(NftAttributeSchema, (attr) => attr.trait_type, 'Attribute trait_type values must be unique').meta({
+        title: 'NFT Attributes',
+        description: 'List of visual traits and filterable attributes compatible with NFT marketplaces',
+        examples: [
+            [
+                {
+                    trait_type: 'Waste Type',
+                    value: 'Organic',
+                },
+                {
+                    trait_type: 'Waste Subtype',
+                    value: 'Food, Food Waste and Beverages',
+                },
+                {
+                    trait_type: 'Weight (kg)',
+                    value: 3000,
+                    display_type: 'number',
+                },
+                {
+                    trait_type: 'Origin Country',
+                    value: 'Brazil',
+                },
+                {
+                    trait_type: 'Pick-up Date',
+                    value: '2024-12-05',
+                    display_type: 'date',
+                },
+            ],
+        ],
+    }),
+}).meta({
+    title: 'NFT IPFS Record',
+    description: 'NFT-specific fields for Carrot IPFS records',
+});

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@carrot-foundation/schemas",
+  "version": "0.1.6",
+  "description": "Carrot schema definitions and zod validation schemas",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./schemas/*": {
+      "import": "./schemas/*",
+      "require": "./schemas/*",
+      "default": "./schemas/*"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "schemas/**/*"
+  ],
+  "packageManager": "pnpm@10.14.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "carrot",
+    "ipfs",
+    "schema",
+    "validation",
+    "zod",
+    "typescript",
+    "blockchain",
+    "json-schema"
+  ],
+  "author": "Carrot Foundation",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/carrot-foundation/schemas.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check-refs": "node scripts/check-refs.js",
+    "clean": "rm -rf dist",
+    "generate-ipfs-schemas": "node scripts/generate-ipfs-schemas.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "pkgJsonLint": "npmPkgJsonLint .",
+    "prebuild": "pnpm clean",
+    "pregenerate-ipfs-schemas": "pnpm build",
+    "preinstall": "npx only-allow pnpm",
+    "prepare": "husky",
+    "prepublishOnly": "pnpm build",
+    "type-check": "tsc --noEmit",
+    "validate-schemas": "node scripts/validate-schemas.js"
+  },
+  "dependencies": {
+    "zod": "4.1.9"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "19.8.1",
+    "@commitlint/config-conventional": "19.8.1",
+    "@cspell/dict-pt-br": "2.4.2",
+    "@eslint/js": "9.36.0",
+    "@tsconfig/recommended": "1.0.10",
+    "@types/node": "22.15.0",
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1",
+    "cspell": "9.2.0",
+    "eslint": "9.36.0",
+    "glob": "11.0.3",
+    "globals": "16.4.0",
+    "husky": "9.1.7",
+    "jiti": "2.6.1",
+    "lint-staged": "16.1.4",
+    "npm-package-json-lint": "9.0.0",
+    "npm-package-json-lint-config-default": "8.0.1",
+    "typescript": "5.3.3",
+    "typescript-eslint": "8.45.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/ipfs/collection/collection.example.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/heads/main/schemas/ipfs/credit/credit.schema.json",
+  "schema": {
+    "hash": "0x8b33fe7f20e0b71c003e63f7db6da83fedef22b4229b5089b78554fc8a2cb987",
+    "type": "Collection",
+    "version": "v0.1.0"
+  },
+  "environment": {
+    "blockchain_network": "testnet",
+    "deployment": "production",
+    "data_set_name": "TEST"
+  },
+  "created_at": "2024-12-05T14:30:00.000Z",
+  "external_id": "8f2c3445-ef89-4de7-8d95-7c814d5c8af9",
+  "external_url": "https://explore.carrot.eco/collection/bold-cold-start-carazinho",
+  "content_hash": "8b33fe7f20e0b71c003e63f7db6da83fedef22b4229b5089b78554fc8a2cb987",
+  "creator": {
+    "name": "Carrot Foundation",
+    "id": "fcdc0eb6-fae9-4aed-8523-a53953910a73"
+  },
+  "name": "BOLD Cold Start - Carazinho",
+  "slug": "bold-cold-start-carazinho",
+  "image": "ipfs://QmCollectionImageHash/bold-cold-start-carazinho-icon.png",
+  "description": "Cold Start is a limited-edition collection created for early supporters of BOLD - Breakthrough in Organic Landfill Diversion. This purchase contributes to reducing global waste and promoting circularity, with funds distributed via smart contract to local recycling operations and communities."
+}

package/schemas/ipfs/collection/collection.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/heads/main/schemas/ipfs/collection/collection.schema.json",
+  "title": "Collection IPFS Record",
+  "unevaluatedProperties": false,
+  "allOf": [
+    {
+      "$ref": "../shared/base/base.schema.json"
+    },
+    {
+      "type": "object",
+      "required": ["name", "description", "image"],
+      "properties": {
+        "schema": {
+          "properties": {
+            "type": {
+              "const": "Collection"
+            }
+          }
+        },
+        "name": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_empty_string",
+          "title": "Collection Name",
+          "example": "BOLD Cold Start - Carazinho"
+        },
+        "slug": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/slug",
+          "title": "Collection Slug",
+          "example": "bold-cold-start-carazinho"
+        },
+        "image": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/ipfs_uri",
+          "title": "Collection Image",
+          "description": "IPFS URI pointing to the collection's visual representation image.",
+          "example": "ipfs://QmCollectionImageHash/collection-icon.png"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 50,
+          "maxLength": 1000,
+          "title": "Collection Description",
+          "example": "Cold Start is a limited-edition collection created for early supporters of BOLD - Breakthrough in Organic Landfill Diversion. This purchase contributes to reducing global waste and promoting circularity, with funds distributed via smart contract to local recycling operations and communities."
+        }
+      }
+    }
+  ]
+}

package/schemas/ipfs/credit/credit.example.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/heads/main/schemas/ipfs/credit/credit.schema.json",
+  "schema": {
+    "hash": "0x8b33fe7f20e0b71c003e63f7db6da83fedef22b4229b5089b78554fc8a2cb987",
+    "type": "Credit",
+    "version": "v0.1.0"
+  },
+  "environment": {
+    "blockchain_network": "testnet",
+    "deployment": "production",
+    "data_set_name": "TEST"
+  },
+  "created_at": "2024-12-05T14:30:00.000Z",
+  "external_id": "8f2c3445-ef89-4de7-8d95-7c814d5c8af9",
+  "external_url": "https://explore.carrot.eco/credit/carrot-carbon",
+  "content_hash": "8b33fe7f20e0b71c003e63f7db6da83fedef22b4229b5089b78554fc8a2cb987",
+  "creator": {
+    "name": "Carrot Foundation",
+    "id": "89bb07f3-1a6f-4d8a-aa1d-b5cbdb342c78"
+  },
+  "symbol": "C-CARB",
+  "slug": "carbon",
+  "name": "Carrot Carbon",
+  "decimals": 18,
+  "image": "ipfs://QmCreditImageHash/c-carb-icon.png",
+  "description": "Carrot Carbon (C-CARB) represents verified carbon emissions reductions from organic waste composting projects. Each token equals one metric ton of CO2 equivalent prevented from entering the atmosphere through sustainable waste management practices. These credits are generated through the BOLD Carbon methodology and provide transparent, traceable environmental impact."
+}

package/schemas/ipfs/credit/credit.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/heads/main/schemas/ipfs/credit/credit.schema.json",
+  "title": "Credit IPFS Record",
+  "description": "Complete schema for Credit ERC20 token IPFS records, extending the base Carrot schema with credit-specific data.",
+  "unevaluatedProperties": false,
+  "allOf": [
+    {
+      "$ref": "../shared/base/base.schema.json"
+    },
+    {
+      "type": "object",
+      "required": ["symbol", "name", "decimals", "image", "description"],
+      "properties": {
+        "schema": {
+          "properties": {
+            "type": {
+              "const": "Credit"
+            }
+          }
+        },
+        "symbol": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/token_symbol"
+        },
+        "slug": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/slug",
+          "title": "Token Slug",
+          "example": "carbon"
+        },
+        "name": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_empty_string",
+          "title": "Token Name",
+          "description": "Full human-readable name of the ERC20 token.",
+          "example": "Carrot Carbon"
+        },
+        "decimals": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 18,
+          "title": "Token Decimals",
+          "description": "Number of decimal places for the ERC20 token.",
+          "example": 18
+        },
+        "image": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/ipfs_uri",
+          "title": "Token Image",
+          "description": "IPFS URI pointing to the token's visual representation image.",
+          "example": "ipfs://QmTokenImageHash/credit-icon.png"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 50,
+          "maxLength": 1000,
+          "title": "Token Description",
+          "description": "Comprehensive description of the credit token, its purpose, environmental impact, and utility within the Carrot ecosystem.",
+          "example": "Carrot Carbon (C-CARB) represents verified carbon emissions reductions from organic waste composting projects. Each token equals one metric ton of CO2 equivalent prevented from entering the atmosphere through sustainable waste management practices."
+        }
+      }
+    }
+  ]
+}

package/schemas/ipfs/gas-id/gas-id.attributes.schema.json

@@ -0,0 +1,219 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/heads/main/schemas/ipfs/gas-id/gas-id.attributes.schema.json",
+  "$defs": {
+    "attribute_methodology": {
+      "type": "object",
+      "required": ["trait_type", "value"],
+      "properties": {
+        "trait_type": {
+          "const": "Methodology"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_empty_string",
+          "maxLength": 100,
+          "description": "Name of the carbon methodology used for certification",
+          "example": "BOLD Carbon (CH₄)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_gas_type": {
+      "type": "object",
+      "required": ["trait_type", "value"],
+      "properties": {
+        "trait_type": {
+          "const": "Gas Type"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_empty_string",
+          "maxLength": 100,
+          "description": "Type of gas emitted",
+          "example": "Methane (CH₄)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_co2e_prevented": {
+      "type": "object",
+      "required": ["trait_type", "value", "display_type"],
+      "properties": {
+        "trait_type": {
+          "const": "CO₂e Prevented (kg)"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_negative_float",
+          "description": "Total CO₂ equivalent emissions prevented in kilograms"
+        },
+        "display_type": {
+          "const": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_credit_amount": {
+      "type": "object",
+      "required": ["trait_type", "value", "display_type"],
+      "properties": {
+        "trait_type": {
+          "const": "Credit Amount"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_negative_float",
+          "description": "Amount of credits issued"
+        },
+        "display_type": {
+          "const": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_credit_type": {
+      "type": "object",
+      "required": ["trait_type", "value"],
+      "properties": {
+        "trait_type": {
+          "const": "Credit Type"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_empty_string",
+          "maxLength": 100,
+          "description": "Type of credit issued",
+          "example": "Carrot Carbon"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_source_waste_type": {
+      "type": "object",
+      "required": ["trait_type", "value"],
+      "properties": {
+        "trait_type": {
+          "const": "Source Waste Type"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/waste_type"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_source_weight": {
+      "type": "object",
+      "required": ["trait_type", "value", "display_type"],
+      "properties": {
+        "trait_type": {
+          "const": "Source Weight (kg)"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/weight_kg"
+        },
+        "display_type": {
+          "const": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_origin_country": {
+      "type": "object",
+      "required": ["trait_type", "value"],
+      "properties": {
+        "trait_type": {
+          "const": "Origin Country"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_empty_string",
+          "maxLength": 100,
+          "description": "Country where the waste was generated",
+          "example": "Brazil"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_origin_municipality": {
+      "type": "object",
+      "required": ["trait_type", "value"],
+      "properties": {
+        "trait_type": {
+          "const": "Origin Municipality"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_empty_string",
+          "maxLength": 100,
+          "description": "Municipality where the waste was generated",
+          "example": "Macapá"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_recycler": {
+      "type": "object",
+      "required": ["trait_type", "value"],
+      "properties": {
+        "trait_type": {
+          "const": "Recycler"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_empty_string",
+          "maxLength": 100,
+          "description": "Organization that processed the waste",
+          "example": "Eco Reciclagem"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_mass_id_token_id": {
+      "type": "object",
+      "required": ["trait_type", "value"],
+      "properties": {
+        "trait_type": {
+          "const": "MassID"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/non_empty_string",
+          "pattern": "^#[0-9]+$",
+          "description": "Token ID of the source MassID NFT",
+          "example": "#123"
+        }
+      },
+      "additionalProperties": false
+    },
+    "attribute_mass_id_recycling_date": {
+      "type": "object",
+      "required": ["trait_type", "value", "display_type"],
+      "properties": {
+        "trait_type": {
+          "const": "MassID Recycling Date"
+        },
+        "value": {
+          "$ref": "../shared/definitions/definitions.schema.json#/$defs/iso_date",
+          "description": "Date when the source waste was recycled",
+          "example": "2025-02-22"
+        },
+        "display_type": {
+          "const": "date"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "title": "GasID NFT Attribute Array",
+  "description": "Schema for the fixed set of GasID NFT attributes, enforcing order and type for each trait.",
+  "type": "array",
+  "prefixItems": [
+    { "$ref": "#/$defs/attribute_methodology" },
+    { "$ref": "#/$defs/attribute_gas_type" },
+    { "$ref": "#/$defs/attribute_co2e_prevented" },
+    { "$ref": "#/$defs/attribute_credit_amount" },
+    { "$ref": "#/$defs/attribute_credit_type" },
+    { "$ref": "#/$defs/attribute_source_waste_type" },
+    { "$ref": "#/$defs/attribute_source_weight" },
+    { "$ref": "#/$defs/attribute_origin_country" },
+    { "$ref": "#/$defs/attribute_origin_municipality" },
+    { "$ref": "#/$defs/attribute_recycler" },
+    { "$ref": "#/$defs/attribute_mass_id_token_id" },
+    { "$ref": "#/$defs/attribute_mass_id_recycling_date" }
+  ],
+  "items": false,
+  "minItems": 12,
+  "maxItems": 12
+}