update measurement schema

Author: holkexyz

.changeset/refactor-measurement-schema.md

@@ -0,0 +1,59 @@
+---
+"@hypercerts-org/lexicon": minor
+---
+
+Refactor measurement lexicon schema: add unit field, date ranges, and locations array
+
+**Breaking Changes:**
+
+- **Measurement lexicon (`org.hypercerts.claim.measurement`):**
+  - Changed required fields: removed `measurers` from required, added `unit` as required
+  - Added `unit` field (required, string, maxLength: 50): The unit of the measured value (e.g. kg CO₂e, hectares, %, index score)
+  - Added `startDate` field (optional, datetime): The start date and time when the measurement began
+  - Added `endDate` field (optional, datetime): The end date and time when the measurement ended
+  - Changed `location` (single strongRef) to `locations` (array of strongRefs, maxLength: 100)
+  - Moved `measurers` from required to optional field
+  - Added `comment` field (optional, string): Short comment suitable for previews and list views
+  - Added `commentFacets` field (optional, array): Rich text annotations for `comment` (mentions, URLs, hashtags, etc.)
+  - Updated field descriptions for `metric` and `value` with more detailed examples
+
+**Migration:**
+
+**Required fields:** Update measurement records to include the new required `unit` field:
+
+```json
+// Before
+{
+  "$type": "org.hypercerts.claim.measurement",
+  "measurers": [...],
+  "metric": "CO₂ sequestered",
+  "value": "1000",
+  "createdAt": "..."
+}
+
+// After
+{
+  "$type": "org.hypercerts.claim.measurement",
+  "metric": "CO₂ sequestered",
+  "unit": "kg CO₂e",
+  "value": "1000",
+  "measurers": [...],  // Now optional
+  "createdAt": "..."
+}
+```
+
+**Location field:** Convert from single location to locations array:
+
+```json
+// Before
+{
+  "location": { "uri": "...", "cid": "..." }
+}
+
+// After
+{
+  "locations": [{ "uri": "...", "cid": "..." }]
+}
+```
+
+**Date ranges:** Optionally add `startDate` and `endDate` to specify when measurements were taken.

lexicons/org/hypercerts/claim/measurement.json

@@ -8,32 +8,47 @@
       "key": "tid",
       "record": {
         "type": "object",
-        "required": ["measurers", "metric", "value", "createdAt"],
+        "required": ["metric", "unit", "value", "createdAt"],
         "properties": {
           "subject": {
             "type": "ref",
             "ref": "com.atproto.repo.strongRef",
             "description": "A strong reference to the record this measurement refers to (e.g. an activity, project, or claim)."
           },
-          "measurers": {
-            "type": "array",
-            "description": "DIDs of the entity (or entities) that measured this data",
-            "items": {
-              "type": "ref",
-              "ref": "app.certified.defs#did"
-            },
-            "maxLength": 100
-          },
           "metric": {
             "type": "string",
-            "description": "The metric being measured",
+            "description": "The metric being measured, e.g. forest area restored, number of users, etc.",
             "maxLength": 500
           },
+          "unit": {
+            "type": "string",
+            "description": "The unit of the measured value (e.g. kg CO₂e, hectares, %, index score).",
+            "maxLength": 50
+          },
           "value": {
             "type": "string",
-            "description": "The measured value",
+            "description": "The measured numeric value.",
             "maxLength": 500
           },
+          "startDate": {
+            "type": "string",
+            "format": "datetime",
+            "description": "The start date and time when the measurement began."
+          },
+          "endDate": {
+            "type": "string",
+            "format": "datetime",
+            "description": "The end date and time when the measurement ended. If it was a one time measurement, the endDate should be equal to the startDate."
+          },
+          "locations": {
+            "type": "array",
+            "description": "Optional geographic references related to where the measurement was taken. Each referenced record must conform with the app.certified.location lexicon.",
+            "items": {
+              "type": "ref",
+              "ref": "com.atproto.repo.strongRef"
+            },
+            "maxLength": 100
+          },
           "methodType": {
             "type": "string",
             "description": "Short identifier for the measurement methodology",
@@ -53,10 +68,28 @@
             },
             "maxLength": 50
           },
-          "location": {
-            "type": "ref",
-            "ref": "com.atproto.repo.strongRef",
-            "description": "A strong reference to the location where the measurement was taken. The record referenced must conform with the lexicon app.certified.location"
+          "measurers": {
+            "type": "array",
+            "description": "DIDs of the entity (or entities) that measured this data",
+            "items": {
+              "type": "ref",
+              "ref": "app.certified.defs#did"
+            },
+            "maxLength": 100
+          },
+          "comment": {
+            "type": "string",
+            "description": "Short comment of this measurement, suitable for previews and list views. Rich text annotations may be provided via `commentFacets`.",
+            "maxLength": 3000,
+            "maxGraphemes": 300
+          },
+          "commentFacets": {
+            "type": "array",
+            "description": "Rich text annotations for `comment` (mentions, URLs, hashtags, etc).",
+            "items": {
+              "type": "ref",
+              "ref": "app.bsky.richtext.facet"
+            }
           },
           "createdAt": {
             "type": "string",