@carrot-foundation/schemas 0.1.21 → 0.1.23

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",
@@ -267,9 +271,9 @@ var CoordinatesSchema = zod.z.strictObject({
   description: "GPS coordinates of the location"
 });
 var LocationSchema = zod.z.strictObject({
-  id: UuidSchema.meta({
-    title: "Location ID",
-    description: "Unique identifier for the location"
+  id_hash: Sha256HashSchema.meta({
+    title: "Location ID Hash",
+    description: "Anonymized identifier for the location"
   }),
   municipality: NonEmptyStringSchema.max(50).meta({
     title: "Municipality",
@@ -294,9 +298,9 @@ var LocationSchema = zod.z.strictObject({
     title: "Country Code",
     description: "ISO 3166-1 alpha-2 country code"
   }),
-  responsible_participant_id: UuidSchema.meta({
-    title: "Responsible Participant ID",
-    description: "ID of the participant responsible for this location"
+  responsible_participant_id_hash: Sha256HashSchema.meta({
+    title: "Responsible Participant ID Hash",
+    description: "Anonymized ID of the participant responsible for this location"
   }),
   coordinates: CoordinatesSchema,
   facility_type: FacilityTypeSchema.optional().meta({
@@ -326,9 +330,9 @@ function uniqueBy(schema, selector, errorMessage = "Items must be unique") {
 
 // src/shared/entities/participant.schema.ts
 var ParticipantSchema = zod.z.strictObject({
-  id: UuidSchema.meta({
-    title: "Participant ID",
-    description: "Unique identifier for the participant"
+  id_hash: Sha256HashSchema.meta({
+    title: "Participant ID Hash",
+    description: "Anonymized identifier for the participant"
   }),
   name: ParticipantNameSchema.meta({
     title: "Participant Name",
@@ -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",
@@ -529,12 +532,12 @@ var MassIDChainOfCustodyEventSchema = zod.z.strictObject({
     title: "Event Timestamp",
     description: "ISO 8601 timestamp when the event occurred"
   }),
-  participant_id: UuidSchema.meta({
-    title: "Participant ID",
+  participant_id_hash: Sha256HashSchema.meta({
+    title: "Participant ID Hash",
     description: "Reference to participant in the participants array"
   }),
-  location_id: UuidSchema.meta({
-    title: "Location ID",
+  location_id_hash: Sha256HashSchema.meta({
+    title: "Location ID Hash",
     description: "Reference to location in the locations array"
   }),
   weight: NonNegativeFloatSchema.optional().meta({
@@ -575,12 +578,12 @@ var MassIDChainOfCustodySchema = zod.z.strictObject({
   description: "Complete chain of custody tracking from waste generation to final processing"
 });
 var MassIDTransportRouteSchema = zod.z.strictObject({
-  from_location_id: UuidSchema.meta({
-    title: "From Location ID",
+  from_location_id_hash: Sha256HashSchema.meta({
+    title: "From Location ID Hash",
     description: "Reference to the origin location in the locations array"
   }),
-  to_location_id: UuidSchema.meta({
-    title: "To Location ID",
+  to_location_id_hash: Sha256HashSchema.meta({
+    title: "To Location ID Hash",
     description: "Reference to the destination location in the locations array"
   }),
   distance_km: NonNegativeFloatSchema.meta({
@@ -610,16 +613,16 @@ var MassIDTransportRouteSchema = zod.z.strictObject({
   description: "Transport route segment information"
 });
 var MassIDGeographicDataSchema = zod.z.strictObject({
-  origin_location_id: UuidSchema.meta({
-    title: "Origin Location ID",
+  origin_location_id_hash: Sha256HashSchema.meta({
+    title: "Origin Location ID Hash",
     description: "Reference to origin location in the locations array"
   }),
-  processing_location_ids: zod.z.array(UuidSchema).optional().meta({
-    title: "Processing Location IDs",
+  processing_location_id_hashes: zod.z.array(Sha256HashSchema).optional().meta({
+    title: "Processing Location ID Hashes",
     description: "Locations where the waste was processed or handled"
   }),
-  final_destination_id: UuidSchema.meta({
-    title: "Final Destination ID",
+  final_destination_id_hash: Sha256HashSchema.meta({
+    title: "Final Destination ID Hash",
     description: "Reference to final destination in the locations array"
   }),
   transport_routes: zod.z.array(MassIDTransportRouteSchema).meta({
@@ -631,19 +634,19 @@ 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,
-    "Location IDs must be unique"
+    (loc) => loc.id_hash,
+    "Location ID hashes must be unique"
   ).min(1).meta({
     title: "Locations",
     description: "All locations referenced in this MassID, indexed by ID"
   }),
   participants: uniqueBy(
     ParticipantSchema,
-    (p) => p.id,
-    "Participant IDs must be unique"
+    (p) => p.id_hash,
+    "Participant ID hashes must be unique"
   ).min(1).meta({
     title: "Participants",
     description: "All participants referenced in this MassID, indexed by ID"
@@ -652,27 +655,27 @@ var MassIDDataSchema = zod.z.strictObject({
   geographic_data: MassIDGeographicDataSchema
 }).refine((data) => {
   const participantIdSet = new Set(
-    data.participants.map((participant) => participant.id)
+    data.participants.map((participant) => participant.id_hash)
   );
   const eventParticipantIds = data.chain_of_custody.events.map(
-    (event) => event.participant_id
+    (event) => event.participant_id_hash
   );
   const allEventParticipantsExist = eventParticipantIds.every(
     (participantId) => participantIdSet.has(participantId)
   );
   return allEventParticipantsExist;
-}, "All participant IDs in chain of custody events must exist in participants array").refine((data) => {
+}, "All participant ID hashes in chain of custody events must exist in participants array").refine((data) => {
   const locationIdSet = new Set(
-    data.locations.map((location) => location.id)
+    data.locations.map((location) => location.id_hash)
   );
   const eventLocationIds = data.chain_of_custody.events.map(
-    (event) => event.location_id
+    (event) => event.location_id_hash
   );
   const allEventLocationsExist = eventLocationIds.every(
     (locationId) => locationIdSet.has(locationId)
   );
   return allEventLocationsExist;
-}, "All location IDs in chain of custody events must exist in locations array").meta({
+}, "All location ID hashes in chain of custody events must exist in locations array").meta({
   title: "MassID Data",
   description: "MassID data containing waste tracking and chain of custody information"
 });
@@ -696,7 +699,7 @@ var RecordCreatorSchema = zod.z.strictObject({
   name: zod.z.string().meta({
     title: "Creator Name",
     description: "Company or individual name that created this record",
-    examples: ["Carrot Foundation", "Alice", "Bob"]
+    examples: ["Carrot Foundation"]
   }),
   id: UuidSchema.meta({
     title: "Creator 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({