Skip to content

refactor: convert measurement subject to subjects array #143

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 5 commits into from
Mar 2, 2026
+61 −93
Merged

refactor: convert measurement subject to subjects array #143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ba913e1
refactor: convert measurement subject to subjects array
holkexyz Feb 25, 2026
bab9b24
fix: update SCHEMAS.md and ERD.puml for subjects array rename
aspiers Feb 26, 2026
5064fa5
docs: improve measurement record description
holkexyz Feb 27, 2026
7a4c083
refactor: move measurement to org.hypercerts.context namespace
holkexyz Feb 27, 2026
efafb8f
fix: sync ERD.puml with measurement lexicon schema changes
aspiers Mar 1, 2026
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
46 changes: 3 additions & 43 deletions .changeset/refactor-measurement-schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@
"@hypercerts-org/lexicon": minor
---

Refactor measurement lexicon schema: add unit field, date ranges, and locations array
Refactor measurement lexicon schema: convert subject to subjects array, add unit field, date ranges, and locations array

**Breaking Changes:**

- **Measurement lexicon (`org.hypercerts.claim.measurement`):**
- **Measurement lexicon (`org.hypercerts.context.measurement`):**
- Changed `subject` (single strongRef) to `subjects` (array of strongRefs, maxLength: 100)
- 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
Expand All @@ -16,44 +17,3 @@ Refactor measurement lexicon schema: add unit field, date ranges, and locations
- 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.
16 changes: 10 additions & 6 deletions ERD.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,17 +94,21 @@ dataclass attachment {
!endif
}

' org.hypercerts.claim.measurement
' org.hypercerts.context.measurement
dataclass measurement {
!if (SHOW_FIELDS == "true")
subject?
measurers[]
subjects[]?
measurers[]?
metric
unit
value
startDate?
endDate?
methodType?
methodURI?
evidenceURI[]?
location?
locations[]?
comment?
createdAt
!endif
}
Expand Down Expand Up @@ -301,13 +305,13 @@ hiddenLocation1 -[hidden]-> activity
attachment::subjects --> activity
attachment::location --> location

measurement::subject --> activity
measurement::subjects --> activity

' Somewhat similarly for measurement --> location
!if (SHOW_FIELDS == "true")
class " " as hiddenLocation2 <<Ghost>>
hide hiddenLocation2 circle
measurement::location --> hiddenLocation2
measurement::locations --> hiddenLocation2
' Also ensure the hidden class is somewhere "en route" to location
hiddenLocation2 -[hidden]-> location
!else
Expand Down
74 changes: 37 additions & 37 deletions SCHEMAS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,33 +145,6 @@ Hypercerts-specific lexicons for tracking impact work and claims.

---

### `org.hypercerts.claim.measurement`

**Description:** Measurement data related to a hypercert record (e.g. an activity and its impact).

**Key:** `tid`

#### 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). | |
| `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 value as a numeric string (e.g. '1234.56') | maxLength: 500 |
| `startDate` | `string` | ❌ | The start date and time when the measurement began. | |
| `endDate` | `string` | ❌ | The end date and time when the measurement ended. For one-time measurements, this should equal the start date. | |
| `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 entities that performed this measurement | 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 | |

---

### `org.hypercerts.claim.rights`

**Description:** Describes the rights that a contributor and/or an owner has, such as whether the hypercert can be sold, transferred, and under what conditions.
Expand Down Expand Up @@ -221,16 +194,16 @@ Hypercerts-specific lexicons for tracking impact work and claims.

#### Properties

| Property | Type | Required | Description | Comments |
| -------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `subject` | `ref` | ❌ | A strong reference to what is being evaluated (e.g. activity, measurement, contribution, etc.) | |
| `evaluators` | `ref[]` | ✅ | DIDs of the evaluators | maxLength: 1000 |
| `content` | `union[]` | ❌ | Evaluation data (URIs or blobs) containing detailed reports or methodology | maxLength: 100 |
| `measurements` | `ref[]` | ❌ | Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.claim.measurement | maxLength: 100 |
| `summary` | `string` | ✅ | Brief evaluation summary | maxLength: 5000, maxGraphemes: 1000 |
| `score` | `ref` | ❌ | Overall score for an evaluation on a numeric scale. | |
| `location` | `ref` | ❌ | An optional reference for georeferenced evaluations. 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 what is being evaluated (e.g. activity, measurement, contribution, etc.) | |
| `evaluators` | `ref[]` | ✅ | DIDs of the evaluators | maxLength: 1000 |
| `content` | `union[]` | ❌ | Evaluation data (URIs or blobs) containing detailed reports or methodology | maxLength: 100 |
| `measurements` | `ref[]` | ❌ | Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.context.measurement | maxLength: 100 |
| `summary` | `string` | ✅ | Brief evaluation summary | maxLength: 5000, maxGraphemes: 1000 |
| `score` | `ref` | ❌ | Overall score for an evaluation on a numeric scale. | |
| `location` | `ref` | ❌ | An optional reference for georeferenced evaluations. The record referenced must conform with the lexicon app.certified.location. | |
| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | |

#### Defs

Expand All @@ -244,6 +217,33 @@ Hypercerts-specific lexicons for tracking impact work and claims.

---

### `org.hypercerts.context.measurement`

**Description:** Measurement data related to one or more records (e.g. activities, projects, etc.).

**Key:** `tid`

#### Properties

| Property | Type | Required | Description | Comments |
| --------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `subjects` | `ref[]` | ❌ | Strong references to the records this measurement refers to (e.g. activities, projects, or claims). | maxLength: 100 |
| `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 value as a numeric string (e.g. '1234.56') | maxLength: 500 |
| `startDate` | `string` | ❌ | The start date and time when the measurement began. | |
| `endDate` | `string` | ❌ | The end date and time when the measurement ended. For one-time measurements, this should equal the start date. | |
| `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 entities that performed this measurement | 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 | |

---

### `org.hypercerts.funding.receipt`

**Description:** Records a funding receipt for a payment from one user to another user. It may be recorded by the recipient, by the sender, or by a third party. The sender may remain anonymous.
Expand Down
2 changes: 1 addition & 1 deletion lexicons/org/hypercerts/context/evaluation.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
},
"measurements": {
"type": "array",
"description": "Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.claim.measurement",
"description": "Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.context.measurement",
"items": {
"type": "ref",
"ref": "com.atproto.repo.strongRef"
Expand Down
16 changes: 10 additions & 6 deletions ...ons/org/hypercerts/claim/measurement.json → ...s/org/hypercerts/context/measurement.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,23 @@
{
"lexicon": 1,
"id": "org.hypercerts.claim.measurement",
"id": "org.hypercerts.context.measurement",
"defs": {
"main": {
"type": "record",
"description": "Measurement data related to a hypercert record (e.g. an activity and its impact).",
"description": "Measurement data related to one or more records (e.g. activities, projects, etc.).",
"key": "tid",
"record": {
"type": "object",
"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)."
"subjects": {
"type": "array",
"description": "Strong references to the records this measurement refers to (e.g. activities, projects, or claims).",
"items": {
"type": "ref",
"ref": "com.atproto.repo.strongRef"
},
"maxLength": 100
},
"metric": {
"type": "string",
Expand Down