Skip to content

update measurement schema #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aspiers merged 1 commit into from
Jan 24, 2026
Merged

update measurement schema #120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions .changeset/refactor-measurement-schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
27 changes: 16 additions & 11 deletions SCHEMAS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,17 +102,22 @@ Hypercerts-specific lexicons for tracking impact work and claims.

#### Properties

| Property | Type | Required | Description | Comments |
| ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `subject` | `ref` | ❌ | A strong reference to the record this measurement refers to (e.g. an activity, project, or claim). | |
| `measurers` | `ref` | ✅ | DIDs of the entity (or entities) that measured this data | maxLength: 100 |
| `metric` | `string` | ✅ | The metric being measured | maxLength: 500 |
| `value` | `string` | ✅ | The measured value | maxLength: 500 |
| `methodType` | `string` | ❌ | Short identifier for the measurement methodology | maxLength: 30 |
| `methodURI` | `string` | ❌ | URI to methodology documentation, standard protocol, or measurement procedure | |
| `evidenceURI` | `string` | ❌ | URIs to related evidence or underlying data (e.g. org.hypercerts.claim.evidence records or raw datasets) | maxLength: 50 |
| `location` | `ref` | ❌ | A strong reference to the location where the measurement was taken. The record referenced must conform with the lexicon app.certified.location | |
| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | |
| Property | Type | Required | Description | Comments |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `subject` | `ref` | ❌ | A strong reference to the record this measurement refers to (e.g. an activity, project, or claim). | |
| `metric` | `string` | ✅ | The metric being measured, e.g. forest area restored, number of users, etc. | maxLength: 500 |
| `unit` | `string` | ✅ | The unit of the measured value (e.g. kg CO₂e, hectares, %, index score). | maxLength: 50 |
| `value` | `string` | ✅ | The measured numeric value. | maxLength: 500 |
| `startDate` | `string` | ❌ | The start date and time when the measurement began. | |
| `endDate` | `string` | ❌ | 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` | `ref` | ❌ | Optional geographic references related to where the measurement was taken. Each referenced record must conform with the app.certified.location lexicon. | maxLength: 100 |
| `methodType` | `string` | ❌ | Short identifier for the measurement methodology | maxLength: 30 |
| `methodURI` | `string` | ❌ | URI to methodology documentation, standard protocol, or measurement procedure | |
| `evidenceURI` | `string` | ❌ | URIs to related evidence or underlying data (e.g. org.hypercerts.claim.evidence records or raw datasets) | maxLength: 50 |
| `measurers` | `ref` | ❌ | DIDs of the entity (or entities) that measured this data | maxLength: 100 |
| `comment` | `string` | ❌ | Short comment of this measurement, suitable for previews and list views. Rich text annotations may be provided via `commentFacets`. | maxLength: 3000, maxGraphemes: 300 |
| `commentFacets` | `ref` | ❌ | Rich text annotations for `comment` (mentions, URLs, hashtags, etc). | |
| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | |
Comment thread
s-adamantine marked this conversation as resolved.

---

Expand Down
65 changes: 49 additions & 16 deletions lexicons/org/hypercerts/claim/measurement.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand Down