feat: allow for multiple location refs in activity claims

[satyam-mishra-pce]

Every organization would have some sites (aka location records) in their organization. They should be able to choose multiple of these sites or location records, at the time of creation of an activity claim.

Until now, we thought the following solution is best:

Fetch the sites in the organization → Merge into a single feature collection → Regenerate a single geojson → Upload as location lexicon.

But it poses some problems:

• This creates an additional “location” record in the repository. Apps might be using this lexicon to display all the sites in an organization, and an additional record with the same data would just add redundancy.
• Location lexicon has some required properties, like createdAt, srs, lpVersion, etc… which might be important for the sites if they exist individually. Creating a new location lexicon would REQUIRE those properties, and would also lead to loss of information holded by the individual sites. Other unrequired fields, such as “name” that exist for individual location records would also be lost.
• Most importantly, the new aggregated location record just created, would not be able to reference to the other stuff that the individual location records did. For example, if there is a relationship defined between a project and a location record, it would be lost if we just create a new location record with the same geojson data.
• Changes in the location record, such as “name” of the site.. won’t be synced once the claim activity is created.

Therefore, we propose a solution where the location property in the activity record holds an array of multiple location refs. This would solve all the problems listed so far.. and doesn’t seem to have any downsides.

Summary by CodeRabbit

• New Features
  • Activities can now be associated with multiple locations instead of a single location, providing greater flexibility in tracking where activities were performed.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

A single lexicon file was updated to change the location field in the activity record from a single strong reference to an array of strong references, enabling support for multiple location references per activity record.

Changes

Cohort / File(s)	Summary
Lexicon Schema Update lexicons/org/hypercerts/claim/activity.json	Modified location property within the main activity record definition from a single reference type to an array of references, allowing multiple location associations per activity while maintaining the same reference target type.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

• Single-file change with straightforward structural modification
• Schema change only; no logic or control flow implications
• Clear migration path from single to multi-valued field

Poem

🐰 One location stood alone, so still and shy,
Now many gather 'neath the open sky,
An array blooms where once a single ref did stay,
The activity roams to places far away! 🌍✨

Pre-merge checks and finishing touches

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Lexicon Documentation Sync	❌ Error	The location property in activity.json was changed from a single ref to an array, but README.md documentation was not updated to match the schema change.	Update README.md location property type from ref to array and ensure all documentation files are consistent with the JSON schema definitions.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: allowing multiple location references in activity claims instead of a single reference.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch multiple-location-refs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d28e27b and 6fbcb6c.

📒 Files selected for processing (1)

• lexicons/org/hypercerts/claim/activity.json

🧰 Additional context used

📓 Path-based instructions (2)

lexicons/**/*.json

📄 CodeRabbit inference engine (Custom checks)

lexicons/**/*.json: When adding, modifying, or deleting files in lexicons//*.json, update README.md to reflect changes (document new lexicons, update modified properties, remove deleted lexicons from documentation)
When adding, modifying, or deleting files in lexicons//*.json, update ERD.puml if entity relationships changed (add new entities, modify relationships, remove deleted entities)
Verify that lexicon IDs in JSON files match what's documented in README.md

lexicons/**/*.json: After modifying lexicon JSON files, regenerate TypeScript types by running npm run gen-api
Lexicon JSON files should follow the ATProto lexicon schema v1 specification
Run npm run check before committing to validate lexicon syntax and ensure valid lexicon definitions
Update ERD.puml when modifying lexicon structures to reflect entity relationship changes
Update README.md documentation when adding or modifying lexicon definitions
Organize lexicon files by namespace following the directory structure pattern (e.g., org/hypercerts/claim/*.json)

Files:

• lexicons/org/hypercerts/claim/activity.json

!(types)/**/*.{js,ts,tsx,json,md}

📄 CodeRabbit inference engine (AGENTS.md)

Run npm run format with Prettier before committing to ensure consistent code formatting

Files:

• lexicons/org/hypercerts/claim/activity.json

🧠 Learnings (3)

📓 Common learnings

Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: coderabbit-custom-pre-merge-checks-unique-id-file-non-traceable-F7F2B60C-1728-4C9A-8889-4F2235E186CA.txt:0-0
Timestamp: 2025-12-11T15:44:24.397Z
Learning: Applies to lexicons/**/*.json : When adding, modifying, or deleting files in lexicons/**/*.json, update README.md to reflect changes (document new lexicons, update modified properties, remove deleted lexicons from documentation)

📚 Learning: 2025-12-15T10:13:17.689Z

Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 34
File: lexicons/org/hypercerts/claim/evaluation.json:45-63
Timestamp: 2025-12-15T10:13:17.689Z
Learning: In the hypercerts-lexicon repository, CI automatically runs npm run gen-api and npm run check to regenerate TypeScript types and validate lexicon definitions. Do not include manual reminders to run these commands in code reviews, as CI handles consistency and validation for all lexicon JSON definitions under lexicons/.

Applied to files:

• lexicons/org/hypercerts/claim/activity.json

📚 Learning: 2025-12-15T15:33:19.949Z

Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 37
File: lexicons/org/hypercerts/funding/receipt.json:1-71
Timestamp: 2025-12-15T15:33:19.949Z
Learning: In the hypercerts-lexicon repository, do not comment on Prettier/formatting issues in code reviews since they are reported by the lint workflow. Do not duplicate the lint output in reviews to reduce noise; focus review comments on functional/semantic issues and other non-formatting concerns.

Applied to files:

• lexicons/org/hypercerts/claim/activity.json

🪛 GitHub Actions: Lint

lexicons/org/hypercerts/claim/activity.json

[error] 1-1: Prettier formatting check failed. Run 'prettier --write' to fix code style issues.

🪛 GitHub Actions: Validate release (PR)

lexicons/org/hypercerts/claim/activity.json

[error] 1-1: Prettier formatting check failed in 'lexicons/org/hypercerts/claim/activity.json'. Run 'prettier --write lexicons/org/hypercerts/claim/activity.json' to fix code style issues. (format:check)

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Update README.md and ERD.puml to reflect the schema change.

The location property changed from a single reference to an array, altering the cardinality of the activity-to-location relationship. Per the coding guidelines, both README.md and ERD.puml should be updated:

• README.md: Document that location is now an array of strong references supporting multiple locations per activity.
• ERD.puml: Update the entity relationship diagram to reflect the new 1-to-many cardinality between activity and location records.

Based on coding guidelines: "When adding, modifying, or deleting files in lexicons/**/*.json, update README.md to reflect changes (document new lexicons, update modified properties, remove deleted lexicons from documentation)" and "update ERD.puml if entity relationships changed."

🤖 Prompt for AI Agents

In lexicons/org/hypercerts/claim/activity.json around lines 71-78, the
"location" property was changed from a single strongRef to an array of
strongRefs; update README.md to document that activity.location is now an array
(supports multiple locations) and revise any examples or schema snippets to show
an array of com.atproto.repo.strongRef items, and update ERD.puml to change the
relationship between Activity and Location from 1-to-1 to 1-to-many (adjust
cardinality notation and any labels) so the docs and diagram reflect the new
cardinality.

---

⚠️ Potential issue | 🔴 Critical

Breaking change: single ref → array requires migration strategy.

Changing location from a single strong reference to an array is a breaking change. Existing activity records that contain a single location reference will become invalid against the new schema. Consider:

• Migration path: How will existing records be migrated? Will there be a script to wrap single refs in arrays?
• Backward compatibility: Should there be a transition period supporting both formats via a union type?
• Client impact: All clients reading/writing activity records must be updated simultaneously.

Alternative: Union type for backward compatibility

If backward compatibility during migration is needed, consider a union that accepts both single ref and array:

 "location": {
-  "type": "array",
-  "description": "An array of strong references to the location where activity was performed. The record referenced must conform with the lexicon app.certified.location.",
-  "items": {
-    "type": "ref",
-    "ref": "com.atproto.repo.strongRef" 
-  }
+  "type": "union",
+  "description": "A strong reference or array of strong references to the location(s) where activity was performed. The record referenced must conform with the lexicon app.certified.location.",
+  "refs": ["com.atproto.repo.strongRef", "#locationArray"]
 }

Then define locationArray in defs:

"locationArray": {
  "type": "array",
  "items": {
    "type": "ref",
    "ref": "com.atproto.repo.strongRef"
  }
}

This would allow both old (single ref) and new (array) formats during transition, with eventual deprecation of the single-ref variant.

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents

In lexicons/org/hypercerts/claim/activity.json around lines 71-78, the schema
change from a single strongRef for "location" to an array is a breaking change;
update the schema and migration plan by either (1) providing a migration
script/utility to convert existing records by wrapping existing single refs into
single-element arrays and documenting the run procedure, or (2) implement a
backward-compatible union in the schema that accepts either a single ref or an
array (add a "locationArray" def for the array form and make "location" a union
of "ref" and "locationArray"), and communicate a deprecation timeline for the
single-ref variant so clients can be updated gradually.

[holkexyz]

Yes, this makes sense to me. Adding Adam as a reviewer.

[aspiers]

@satyam-mishra-pce Please could you fix the linting errors and include doc updates as highlighted by CodeRabbit? Thanks!