@carrot-foundation/schemas 0.1.21 → 0.1.22

package/README.md

@@ -14,15 +14,60 @@ They are versioned, publicly referenceable, and used for validation, traceabilit
 
 ## 🔖 Versioning
 
-- Schemas are versioned using isolated versioning; each schema can evolve independently.
-- For released versions, each schema’s `$id` must point to the tagged raw URL to remain immutable.
-- During development on `main`, `$id` may reference `refs/heads/main`, but consumers should pin to tags in production.
-- Keep `$ref` paths relative; they resolve against the `$id` base (the tag) at validation time.
+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.
 
-Example `$id` pinned to a tag:
+### 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 `0.0.0-dev`
+- **No special cases**: Development and production use the exact same versioning mechanism
+
+### Local Development
+
+For local development, the default version `0.0.0-dev` is used automatically:
+
+```bash
+# Build with default dev version (0.0.0-dev)
+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
+```
+
+### Release Process
+
+The release process automatically:
+
+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
+
+All of this happens automatically via the GitHub Actions workflow when you push to `main`.
+
+### Example Schema References
+
+**Development (default):**
+
+```json
+"$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/0.0.0-dev/schemas/ipfs/mass-id/mass-id.schema.json"
+```
+
+**Production (versioned):**
 
 ```json
-"$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/v0.1.0/schemas/ipfs/collection/collection.schema.json"
+"$id": "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/1.2.3/schemas/ipfs/mass-id/mass-id.schema.json"
 ```
 
 ## 📚 Package Usage
@@ -51,7 +96,10 @@ const result = MassIDIpfsSchema.safeParse(data);
 ### CommonJS
 
 ```javascript
-const { MassIDIpfsSchema, MassIDDataSchema } = require('@carrot-foundation/schemas');
+const {
+  MassIDIpfsSchema,
+  MassIDDataSchema,
+} = require('@carrot-foundation/schemas');
 
 // Use the schemas for validation
 const result = MassIDIpfsSchema.safeParse(data);

package/dist/index.cjs

@@ -35,6 +35,11 @@ var IsoDateSchema = zod.z.iso.date("Must be a valid ISO 8601 date (YYYY-MM-DD)")
   description: "ISO 8601 formatted date in YYYY-MM-DD format",
   examples: ["2024-12-05", "2025-02-22", "2024-02-10"]
 });
+var UnixTimestampSchema = zod.z.number().int().positive().meta({
+  title: "Unix Timestamp",
+  description: "Unix timestamp in milliseconds since epoch (January 1, 1970 00:00:00 UTC)",
+  examples: [17040672e5, 17356896e5, 1762371245149]
+});
 var IsoCountryCodeSchema = zod.z.string().regex(/^[A-Z]{2}$/, "Must be a valid ISO 3166-1 alpha-2 country code").meta({
   title: "ISO Country Code",
   description: "Two-letter country code following ISO 3166-1 alpha-2 standard",
@@ -48,14 +53,14 @@ var IsoAdministrativeDivisionCodeSchema = zod.z.string().regex(
   description: "Administrative division code following ISO 3166-2 standard",
   examples: ["BR-AP", "BR-ES", "US-CA"]
 });
-var LatitudeSchema = zod.z.number().min(-90).max(90).meta({
+var LatitudeSchema = zod.z.number().min(-90).max(90).multipleOf(1e-3).meta({
   title: "Latitude",
-  description: "Geographic latitude coordinate in decimal degrees",
-  examples: [-0.02, -20.38, 40.7128]
+  description: "Geographic latitude coordinate in decimal degrees with maximum 3 decimal places precision (~100m-1km accuracy for city-level, non-PII compliance)",
+  examples: [-0.02, -20.38, 40.713]
 });
-var LongitudeSchema = zod.z.number().min(-180).max(180).meta({
+var LongitudeSchema = zod.z.number().min(-180).max(180).multipleOf(1e-3).meta({
   title: "Longitude",
-  description: "Geographic longitude coordinate in decimal degrees",
+  description: "Geographic longitude coordinate in decimal degrees with maximum 3 decimal places precision (~100m-1km accuracy for city-level, non-PII compliance)",
   examples: [-51.06, -40.34, -74.006]
 });
 var WeightKgSchema = zod.z.number().min(0).meta({
@@ -97,19 +102,18 @@ var ParticipantNameSchema = NonEmptyStringSchema.max(100).meta({
   examples: ["Enlatados Produ\xE7\xE3o", "Eco Reciclagem", "Green Tech Corp"]
 });
 var FacilityTypeSchema = zod.z.enum([
-  "Waste Generation",
   "Collection Point",
-  "Transfer Station",
-  "Sorting Facility",
-  "Composting Facility",
   "Recycling Facility",
-  "Processing Facility",
-  "Disposal Facility",
-  "Administrative Office"
+  "Administrative Office",
+  "Other"
 ]).meta({
   title: "Facility Type",
-  description: "Type of facility in the waste management infrastructure",
-  examples: ["Waste Generation", "Recycling Facility", "Collection Point"]
+  description: "Type of facility in the waste management chain",
+  examples: [
+    "Collection Point",
+    "Recycling Facility",
+    "Administrative Office"
+  ]
 });
 var BlockchainChainIdSchema = zod.z.number().int().min(1).meta({
   title: "Chain ID",
@@ -363,15 +367,10 @@ var MassIDLocalClassificationSchema = zod.z.strictObject({
       "Municipal solid waste - organic fraction"
     ]
   }),
-  system: NonEmptyStringSchema.max(50).meta({
+  system: zod.z.enum(["IBAMA"]).meta({
     title: "Classification System",
-    description: 'Classification system name (e.g., "Ibama Waste Code", "European Waste Catalogue", "US EPA Codes")',
-    examples: [
-      "European Waste Catalogue",
-      "US EPA Codes",
-      "Ibama Waste Code",
-      "Brazilian ABNT Classification"
-    ]
+    description: "Classification system name - currently supports IBAMA (Instituto Brasileiro do Meio Ambiente e dos Recursos Naturais Renov\xE1veis)",
+    examples: ["IBAMA"]
   })
 }).meta({
   title: "Local Classification",
@@ -387,10 +386,10 @@ var ContaminationLevelSchema = zod.z.enum(["None", "Low", "Medium", "High"]).met
   description: "Level of contamination in the waste batch",
   examples: ["Low", "Medium", "None"]
 });
-var MassIDWasteClassificationSchema = zod.z.strictObject({
-  primary_type: WasteTypeSchema.meta({
-    title: "Primary Waste Type",
-    description: "Primary waste material category"
+var MassIDWastePropertiesSchema = zod.z.strictObject({
+  type: WasteTypeSchema.meta({
+    title: "Waste Type",
+    description: "Waste material category"
   }),
   subtype: WasteSubtypeSchema.meta({
     title: "Waste Subtype",
@@ -404,8 +403,8 @@ var MassIDWasteClassificationSchema = zod.z.strictObject({
   }),
   contamination_level: ContaminationLevelSchema.optional()
 }).meta({
-  title: "Waste Classification",
-  description: "Standardized waste material classification and regulatory information"
+  title: "Waste Properties",
+  description: "Standardized waste material properties and regulatory information"
 });
 var EventAttributeFormatSchema = zod.z.enum(["KILOGRAM", "DATE", "CURRENCY", "PERCENTAGE", "COORDINATE"]).meta({
   title: "Event Attribute Format",
@@ -427,7 +426,7 @@ var EventAttributeSchema = zod.z.strictObject({
       "processing_cost"
     ]
   }),
-  value: zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()]).meta({
+  value: zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()]).optional().meta({
     title: "Attribute Value",
     description: "Event attribute value",
     examples: [
@@ -441,6 +440,10 @@ var EventAttributeSchema = zod.z.strictObject({
       "OP-456"
     ]
   }),
+  preserved_sensitivity: zod.z.boolean().optional().meta({
+    title: "Preserved Sensitivity",
+    description: "Indicates if the attribute contains sensitive information that was preserved"
+  }),
   format: EventAttributeFormatSchema.optional()
 }).meta({
   title: "Event Attribute",
@@ -631,7 +634,7 @@ var MassIDGeographicDataSchema = zod.z.strictObject({
   description: "Geographic information about waste origin and processing locations"
 });
 var MassIDDataSchema = zod.z.strictObject({
-  waste_classification: MassIDWasteClassificationSchema,
+  waste_properties: MassIDWastePropertiesSchema,
   locations: uniqueBy(
     LocationSchema,
     (loc) => loc.id,
@@ -964,6 +967,18 @@ var NftIpfsSchema = BaseIpfsSchema.safeExtend({
   description: "NFT-specific fields for Carrot IPFS records"
 });
 
+// src/shared/schema-version.ts
+function getSchemaBaseUrl() {
+  return `https://raw.githubusercontent.com/carrot-foundation/schemas/refs/tags/${getSchemaVersionOrDefault()}/schemas/ipfs`;
+}
+function buildSchemaUrl(schemaPath) {
+  const cleanPath = schemaPath.startsWith("/") ? schemaPath.slice(1) : schemaPath;
+  return `${getSchemaBaseUrl()}/${cleanPath}`;
+}
+function getSchemaVersionOrDefault() {
+  return "0.0.0-dev";
+}
+
 // src/mass-id/mass-id.schema.ts
 var AttributeWasteTypeSchema = zod.z.strictObject({
   trait_type: zod.z.literal("Waste Type"),
@@ -1039,14 +1054,14 @@ var AttributeIntegratorSchema = zod.z.strictObject({
 });
 var AttributePickUpDateSchema = zod.z.strictObject({
   trait_type: zod.z.literal("Pick-up Date"),
-  value: zod.z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Must be a valid date in YYYY-MM-DD format").meta({
+  value: UnixTimestampSchema.meta({
     title: "Pick-up Date Value",
-    description: "Date when the waste was picked up from the source"
+    description: "Unix timestamp in milliseconds when the waste was picked up from the source"
   }),
   display_type: zod.z.literal("date")
 }).meta({
   title: "Pick-up Date Attribute",
-  description: "Pick-up date attribute"
+  description: "Pick-up date attribute with Unix timestamp"
 });
 var AttributeRecyclingDateSchema = zod.z.strictObject({
   trait_type: zod.z.literal("Recycling Date"),
@@ -1077,8 +1092,8 @@ var MassIDAttributesSchema = zod.z.tuple([
 var MassIDIpfsSchemaMeta = {
   title: "MassID NFT IPFS Record",
   description: "Complete MassID NFT IPFS record including fixed attributes and detailed waste tracking data",
-  $id: "https://raw.githubusercontent.com/carrot-foundation/schemas/refs/heads/main/schemas/ipfs/mass-id/mass-id.schema.json",
-  version: "1.0.1"
+  $id: buildSchemaUrl("mass-id/mass-id.schema.json"),
+  version: getSchemaVersionOrDefault()
 };
 var MassIDIpfsSchema = NftIpfsSchema.safeExtend({
   schema: NftIpfsSchema.shape.schema.safeExtend({