Skip to content

renaming fields to contributorIdentity and contributionWeight in activity claim #114

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 21, 2026
Merged

renaming fields to contributorIdentity and contributionWeight in activity claim #114

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
43 changes: 29 additions & 14 deletions .changeset/refactor-contributions-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,40 @@
"@hypercerts-org/lexicon": minor
---

Refactor contributions structure and split contributor lexicon
Refactor contributions structure in activity lexicon

**Breaking Changes:**

- **Activity lexicon (`org.hypercerts.claim.activity`):**
- Renamed `contributions` field to `contributors`
- Replaced `contributions` array (array of strongRefs) with new `contributors` array containing contributor objects
- Each contributor object has three fields:
- `contributorInformation` (required): string (DID/identifier) or strongRef to `org.hypercerts.claim.contributorInformation#main`
- `weight` (optional): positive number (stored as string)
- `contributionDetails` (optional): string or strongRef to `org.hypercerts.claim.contributionDetails#main`
- Renamed internal `contribution` object type to `contributor`
- Renamed string wrapper defs: `contributorInformationString` → `contributorIdentity`, `contributionDetailsString` → `contributorRole`
- Updated `contributorRole` string limits: maxLength 10000, maxGraphemes 1000
- Each contributor object (`org.hypercerts.claim.activity#contributor`) has three fields:
- `contributorIdentity` (required): string (DID/identifier) or strongRef to a contributor information record
- `contributionWeight` (optional): positive numeric value stored as string
- `contributionDetails` (optional): string or strongRef to a contribution details record
- Added internal defs:
- `#contributor`: object type for contributor entries
- `#contributorIdentity`: string type for DID/identifier values
- `#contributorRole`: string type for contribution details (maxLength 10000, maxGraphemes 1000)

- **Contributor lexicon (`org.hypercerts.claim.contributor`):**
- Split into two separate lexicon files:
- `org.hypercerts.claim.contributorInformation`: new lexicon file containing `identifier`, `displayName`, `image` (contributor profile information)
- `org.hypercerts.claim.contributionDetails`: new lexicon file containing `role`, `contributionDescription`, `startDate`, `endDate` (contribution-specific details)
- The original `org.hypercerts.claim.contributor` lexicon has been removed
**Migration:**

Existing contributions using the old structure will need to be migrated to the new format.
Convert from array of strongRefs to array of contributor objects:

```json
// Before
"contributions": [strongRef1, strongRef2]

// After
"contributors": [
{
"contributorIdentity": "did:example:123",
"contributionWeight": "1.5",
"contributionDetails": "Lead developer"
},
{
"contributorIdentity": strongRefToContributorInfo,
"contributionDetails": strongRefToContributionDetails
}
]
Comment on lines +25 to +40

@coderabbitai coderabbitai Bot Jan 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use valid JSON (or label as JSONC) in the migration example.

The // Before/// After comments make the json block invalid to copy/paste. Consider switching to jsonc or removing the inline comments.

💡 Suggested tweak 
-```json
+```jsonc
🤖 Prompt for AI Agents 
In @.changeset/refactor-contributions-structure.md around lines 25 - 40, The
migration example uses a fenced block labeled "json" but contains inline
comments ("// Before"/"// After") which makes it invalid JSON; update the fenced
block language to "jsonc" or remove the inline comment lines so the example is
valid JSON, and ensure the example shows the original "contributions" array and
the new "contributors" array with fields like "contributorIdentity",
"contributionWeight", and "contributionDetails" exactly as in the diff so
readers can copy/paste without syntax errors.

```
19 changes: 19 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -281,3 +281,22 @@ const collectionRecord = {
**Note**: Both `avatar` (up to 5MB) and `banner` (up to 10MB) fields
are optional and support either embedded image blobs or URI references to
external images.

### Adding Locations to Activities

The `locations` field in activity records is an array of strong references
(`com.atproto.repo.strongRef`) pointing to `app.certified.location` records.
Each strong reference contains two required fields:

- `uri`: The ATProto URI of the location record (e.g., `at://did:plc:alice/app.certified.location/abc123`)
- `cid`: The content identifier (CID) of the location record, ensuring referential integrity

**Validation and Expectations**:

- All location records referenced in the `locations` array must conform to the
`app.certified.location` lexicon schema
- The `uri` field must be a valid ATProto URI pointing to an existing location record
- The `cid` field must match the current CID of the referenced location record
- The `locations` field is optional; activities can be created without location data
- When using the sidecar pattern (same TID), ensure the location record is created
or updated alongside the activity record for consistency
10 changes: 5 additions & 5 deletions SCHEMAS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,11 +35,11 @@ Hypercerts-specific lexicons for tracking impact work and claims.

##### contributor

| Property | Type | Required | Description |
| ------------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `contributorInformation` | `union` | ✅ | Contributor information as a string (DID or identifier) or strong reference to for instance org.hypercerts.claim.contributorInformation#main. |
| `weight` | `string` | ❌ | The relative weight/importance of this contribution (stored as a string to avoid float precision issues). Must be a positive numeric value. Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed. |
| `contributionDetails` | `union` | ❌ | Contribution details as a string or strong reference to org.hypercerts.claim.contributionDetails#main. |
| Property | Type | Required | Description |
| --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `contributorIdentity` | `union` | ✅ | Contributor identity as a string (DID or identifier) via org.hypercerts.claim.activity#contributorIdentity, or a strong reference to a contributor information record. |
| `contributionWeight` | `string` | ❌ | The relative weight/importance of this contribution (stored as a string to avoid float precision issues). Must be a positive numeric value. Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed. |
| `contributionDetails` | `union` | ❌ | Contribution details as a string via org.hypercerts.claim.activity#contributorRole, or a strong reference to a contribution details record. |

---

Expand Down
10 changes: 5 additions & 5 deletions lexicons/org/hypercerts/claim/activity.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,21 +97,21 @@
},
"contributor": {
"type": "object",
"required": ["contributorInformation"],
"required": ["contributorIdentity"],
"properties": {
"contributorInformation": {
"contributorIdentity": {
"type": "union",
"refs": ["#contributorIdentity", "com.atproto.repo.strongRef"],
"description": "Contributor information as a string (DID or identifier) or strong reference to for instance org.hypercerts.claim.contributorInformation#main."
"description": "Contributor identity as a string (DID or identifier) via org.hypercerts.claim.activity#contributorIdentity, or a strong reference to a contributor information record."
},
Comment thread
coderabbitai[bot] marked this conversation as resolved.
"weight": {
"contributionWeight": {
"type": "string",
"description": "The relative weight/importance of this contribution (stored as a string to avoid float precision issues). Must be a positive numeric value. Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed."
},
"contributionDetails": {
"type": "union",
"refs": ["#contributorRole", "com.atproto.repo.strongRef"],
"description": "Contribution details as a string or strong reference to org.hypercerts.claim.contributionDetails#main."
"description": "Contribution details as a string via org.hypercerts.claim.activity#contributorRole, or a strong reference to a contribution details record."
}
}
},
Expand Down