Document location sidecar pattern for collections - #77
Conversation
🦋 Changeset detectedLatest commit: 0d61ff7 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
📝 WalkthroughWalkthroughAdds documentation, ERD updates, and a changelog entry for a "Location Sidecar Pattern" where collections associate location metadata via separate location records sharing the same TID; removes Changes
Sequence Diagram(s)sequenceDiagram
participant Client as Client
participant Repo as Repo Service
participant Collection as "Collection Record"
participant Location as "Location Record"
Client->>Repo: POST create collection (TID = X)
Repo->>Collection: persist collection CID, TID = X
Client->>Repo: POST create location record (TID = X)
Repo->>Location: persist location record with same TID
Repo->>Client: return collection CID and location record ID
Note over Collection,Location: Location acts as a sidecar (same TID) so location updates don't change collection CID
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 error, 1 warning)
✅ Passed checks (3 passed)
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. Comment |
40629f7 to
0c9216e
Compare
- Update collection.json description to mention location sidecar usage - Add location sidecar pattern section to README with usage example - Show how app.certified.location can be used as sidecar with same TID - Add ERD comment and dashed relationship showing sidecar pattern - Benefits: location updates without changing collection CID
0c9216e to
0d61ff7
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @.changeset/document-location-sidecar-pattern.md:
- Around line 1-5: Update the changeset header to bump "@hypercerts-org/lexicon"
from patch to minor; locate the YAML block at the top of
.changeset/document-location-sidecar-pattern.md and change the version tag value
from "patch" to "minor" so the release reflects the potentially breaking removal
of the collection.location field and addition of org.hypercerts.claim.project.
In `@README.md`:
- Around line 470-489: Create a new ATProto v1 lexicon JSON for lexicon id
"org.hypercerts.claim.project" (file named project.json under the lexicons
hierarchy) that defines the record with properties title (string, required),
shortDescription (string, required), description (ref, optional) referencing
"pub.leaflet.pages.linearDocument#main", avatar (blob, optional), coverPhoto
(blob, optional), activities (array, optional) with items referencing
"org.hypercerts.claim.activity#activityWeight", location (ref, optional)
referencing "app.certified.location", and createdAt (string, required); ensure
the top-level lexicon fields (lexicon, id, defs/types/record schema) follow
ATProto lexicon schema v1 conventions and mark required properties accordingly.
| --- | ||
| "@hypercerts-org/lexicon": patch | ||
| --- | ||
|
|
||
| Document ATProto sidecar pattern for collections using app.certified.location. Collections can now have location metadata by creating a location record with the same TID, allowing location updates without changing the collection CID. Updated README with usage example and ERD with sidecar relationship. |
There was a problem hiding this comment.
Consider using minor instead of patch for this version bump.
According to the context, this PR removes the location property from org.hypercerts.claim.collection and adds a new org.hypercerts.claim.project lexicon. Removing a property from an existing lexicon is a potentially breaking change for consumers who rely on that field.
Per the coding guidelines for 0.x packages: use minor for potentially breaking changes and patch for non-breaking changes.
📝 Suggested changeset version bump
---
-"@hypercerts-org/lexicon": patch
+"@hypercerts-org/lexicon": minor
---Based on coding guidelines for 0.x version semantic versioning.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| "@hypercerts-org/lexicon": patch | |
| --- | |
| Document ATProto sidecar pattern for collections using app.certified.location. Collections can now have location metadata by creating a location record with the same TID, allowing location updates without changing the collection CID. Updated README with usage example and ERD with sidecar relationship. | |
| --- | |
| "@hypercerts-org/lexicon": minor | |
| --- | |
| Document ATProto sidecar pattern for collections using app.certified.location. Collections can now have location metadata by creating a location record with the same TID, allowing location updates without changing the collection CID. Updated README with usage example and ERD with sidecar relationship. |
🤖 Prompt for AI Agents
In @.changeset/document-location-sidecar-pattern.md around lines 1 - 5, Update
the changeset header to bump "@hypercerts-org/lexicon" from patch to minor;
locate the YAML block at the top of
.changeset/document-location-sidecar-pattern.md and change the version tag value
from "patch" to "minor" so the release reflects the potentially breaking removal
of the collection.location field and addition of org.hypercerts.claim.project.
There was a problem hiding this comment.
CodeRabbit was correct here. Not a big deal to get it wrong for now while we're still pre-release, but even at this stage using version numbers correctly is helpful.
There was a problem hiding this comment.
@aspiers, thank you for confirming! I appreciate the feedback. The changeset still needs to be updated from patch to minor to properly reflect the potentially breaking change (removal of the location property from the collection lexicon). Even in pre-release, maintaining proper semantic versioning practices helps downstream consumers understand the impact of changes. 🐰
(\(\
( ^.^)
o_(")(") *confirmed!*
🧠 Learnings used
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-12T14:44:03.427Z
Learning: Applies to .changeset/*.md : Changeset files should use the format with frontmatter containing package name `hypercerts-org/lexicon` and version bump type (`major`, `minor`, or `patch`), followed by a description of changes
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-12T14:44:03.427Z
Learning: Applies to .changeset/*.md : For this package in 0.x version (initial development), do not use `major` version bumps in changesets. Use `minor` for potentially breaking changes and `patch` for non-breaking changes, as semantic versioning considers 0.x versions unstable
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)
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-12T14:44:03.427Z
Learning: Applies to lexicons/**/*.json : Create a changeset file in `.changeset/` directory when making changes that affect the public API, including: adding or modifying lexicon files, changing generated TypeScript exports, renaming constants/types/functions, or any change that users of this package need to know about
Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 39
File: README.md:17-17
Timestamp: 2025-12-15T16:39:31.022Z
Learning: In the hypercerts-org/hypercerts-lexicon repository, prefer the spelling "onchain" (without hyphen) over "on-chain" to match the increasingly adopted industry standard.
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 README.md : Ensure all properties documented in README.md match the actual JSON schema definitions in lexicons/**/*.json
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-12T14:44:03.427Z
Learning: Applies to lexicons/**/*.json : When adding or modifying a lexicon, update `README.md` as appropriate
| ### org.hypercerts.claim.project | ||
|
|
||
| **Lexicon ID:** `org.hypercerts.claim.project` | ||
|
|
||
| **Description:** A project that can include multiple activities | ||
|
|
||
| **Key:** `tid` | ||
|
|
||
| #### Properties | ||
|
|
||
| | Property | Type | Required | Description | Comments | | ||
| | ------------------ | -------- | -------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | ||
| | `title` | `string` | ✅ | Title of this project | | | ||
| | `shortDescription` | `string` | ✅ | Short summary of this project, suitable for previews and list views | | | ||
| | `description` | `ref` | ❌ | Rich-text description of this project, represented as a Leaflet linear document | References must conform to `pub.leaflet.pages.linearDocument#main` | | ||
| | `avatar` | `blob` | ❌ | Primary avatar image representing this project across apps and views | Typically a square logo or project identity image | | ||
| | `coverPhoto` | `blob` | ❌ | The cover photo of this project | | | ||
| | `activities` | `array` | ❌ | Array of activities with their associated weights in this project | Each item references `org.hypercerts.claim.activity#activityWeight` | | ||
| | `location` | `ref` | ❌ | A strong reference to a location record describing where the work took place | References must conform to `app.certified.location` | | ||
| | `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if the project lexicon file exists
if [ -f "lexicons/org/hypercerts/claim/project.json" ]; then
echo "✓ Lexicon file found"
echo ""
echo "=== Lexicon file structure ==="
cat lexicons/org/hypercerts/claim/project.json
else
echo "✗ Lexicon file NOT found at lexicons/org/hypercerts/claim/project.json"
echo ""
echo "Searching for project-related files..."
fd -e json "project" lexicons/ 2>/dev/null || echo "No project files found"
fiRepository: hypercerts-org/hypercerts-lexicon
Length of output: 187
🏁 Script executed:
#!/bin/bash
# Search more thoroughly for any project-related lexicon
echo "=== Searching for any project.json files in lexicons directory ==="
find lexicons/ -name "*project*" -type f 2>/dev/null
echo ""
echo "=== Checking directory structure of lexicons/org/hypercerts/claim/ ==="
if [ -d "lexicons/org/hypercerts/claim/" ]; then
ls -la lexicons/org/hypercerts/claim/
else
echo "Directory lexicons/org/hypercerts/claim/ does not exist"
fi
echo ""
echo "=== All lexicon files currently in repository ==="
find lexicons/ -name "*.json" -type f 2>/dev/null | sortRepository: hypercerts-org/hypercerts-lexicon
Length of output: 1463
Create the missing org.hypercerts.claim.project lexicon file.
The org.hypercerts.claim.project lexicon is documented in README.md (lines 470-489) but the corresponding JSON schema file does not exist. Per coding guidelines, all lexicons documented in README.md must exist as JSON files in the lexicons/ directory.
Create lexicons/org/hypercerts/claim/project.json with the 9 properties documented: title, shortDescription, description, avatar, coverPhoto, activities, location, and createdAt. Ensure the schema follows ATProto lexicon schema v1.
🧰 Tools
🪛 LanguageTool
[style] ~489-~489: This phrase is redundant. Consider writing “created”.
Context: ...declared timestamp when this record was originally created | ...
(ORIGINALLY_CREATED)
🤖 Prompt for AI Agents
In `@README.md` around lines 470 - 489, Create a new ATProto v1 lexicon JSON for
lexicon id "org.hypercerts.claim.project" (file named project.json under the
lexicons hierarchy) that defines the record with properties title (string,
required), shortDescription (string, required), description (ref, optional)
referencing "pub.leaflet.pages.linearDocument#main", avatar (blob, optional),
coverPhoto (blob, optional), activities (array, optional) with items referencing
"org.hypercerts.claim.activity#activityWeight", location (ref, optional)
referencing "app.certified.location", and createdAt (string, required); ensure
the top-level lexicon fields (lexicon, id, defs/types/record schema) follow
ATProto lexicon schema v1 conventions and mark required properties accordingly.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
404-422: README.md collection and project documentation contains critical property mismatches with the actual lexicon schema.The documented properties in README.md do not match the actual
org.hypercerts.claim.collectionlexicon schema:Property Name Mismatches:
collectionTitle(README) →title(actual schema)shortCollectionDescription(README) →shortDescription(actual schema)collectionDescription(README) →description(actual schema)items(README) →activities(actual schema)location(README) → does not exist in actual schema- Missing:
typefield (required in actual schema)Property Type Issues:
descriptionis documented asstringtype but is actually areftype pointing topub.leaflet.pages.linearDocument#main- Actual schema includes
avatarandcoverPhoto(blob types) not documented in READMEProject Sidecar Misconception:
The README documentsorg.hypercerts.claim.collection.projectas a separate sidecar lexicon, but no separate project lexicon file exists. The actual schema uses a requiredtypefield to distinguish projects from collections within the singleorg.hypercerts.claim.collectionlexicon.Examples Affected:
The TypeScript examples in README.md use incorrect property names (collectionTitle,items) that do not match the actual schema (title,activities), and the project example shows a non-existent lexicon.Update README.md to reflect the actual schema: rename properties to match the lexicon definition, correct the
descriptiontype documentation, remove the location field reference, and replace the sidecar pattern explanation with the actualtypefield mechanism.
🤖 Fix all issues with AI agents
In `@README.md`:
- Around line 454-524: The README documents a missing lexicon for
org.hypercerts.claim.collection.project; add a new lexicon JSON for the lexicon
id "org.hypercerts.claim.collection.project" that defines the properties
projectTitle (string, maxLength 800, maxGraphemes 80), shortProjectDescription
(string, maxLength 3000, maxGraphemes 300), projectDescription (ref to
pub.leaflet.pages.linearDocument#main, required), avatar (blob,
image/png|image/jpeg, maxSize 1000000), coverPhoto (blob, image/png|image/jpeg,
maxSize 1000000), and createdAt (string, required) with appropriate types,
required flags and validation constraints matching README.md; ensure the
lexicon's $id/$defs mirror project semantics and then update the ERD.puml
project entity references to reflect the new complete lexicon definition.
🧹 Nitpick comments (1)
README.md (1)
421-421: Consider simplifying timestamp description for consistency.The phrase "originally created" could be simplified to "created" as the word "originally" is somewhat redundant in this context. However, this phrase appears consistently throughout the documentation, so if changed, update all occurrences for consistency.
| ### org.hypercerts.claim.collection.project | ||
|
|
||
| **Lexicon ID:** `org.hypercerts.claim.collection.project` | ||
|
|
||
| **Description:** Project-specific metadata for a collection. Uses the sidecar pattern with the same record key (TID) as the collection record. This allows collections to represent projects by adding rich-text descriptions and visual assets. | ||
|
|
||
| **Key:** `tid` (same as the collection record) | ||
|
|
||
| #### Properties | ||
|
|
||
| | Property | Type | Required | Description | Comments | | ||
| | ------------------------- | -------- | -------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | ||
| | `projectTitle` | `string` | ❌ | The title of this project | maxLength: 800, maxGraphemes: 80 | | ||
| | `shortProjectDescription` | `string` | ❌ | Short summary of this project, suitable for previews and list views | maxLength: 3000, maxGraphemes: 300 | | ||
| | `projectDescription` | `ref` | ✅ | Rich-text description of this project, represented as a Leaflet linear document | References must conform to `pub.leaflet.pages.linearDocument#main` | | ||
| | `avatar` | `blob` | ❌ | Primary avatar image representing this project across apps and views | Typically a square logo or project identity image; image/png or image/jpeg, maxSize: 1000000 | | ||
| | `coverPhoto` | `blob` | ❌ | The cover photo of this project | image/png or image/jpeg, maxSize: 1000000 | | ||
| | `createdAt` | `string` | ✅ | Client-declared timestamp when this project metadata was created | | | ||
|
|
||
| #### Example: Creating a Project (Collection + Project Sidecar) | ||
|
|
||
| ```typescript | ||
| import { TID } from "@atproto/common"; | ||
|
|
||
| const tid = TID.nextStr(); // Same TID for both records | ||
|
|
||
| // Base collection record | ||
| const collectionRecord = { | ||
| $type: "org.hypercerts.claim.collection", | ||
| collectionTitle: "Carbon Offset Initiative", | ||
| items: [ | ||
| { | ||
| uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc", | ||
| cid: "...", | ||
| }, | ||
| { | ||
| uri: "at://did:plc:bob/org.hypercerts.claim.activity/7x9def", | ||
| cid: "...", | ||
| }, | ||
| ], | ||
| createdAt: new Date().toISOString(), | ||
| }; | ||
|
|
||
| // Project sidecar with rich-text description and assets | ||
| const projectSidecar = { | ||
| $type: "org.hypercerts.claim.collection.project", | ||
| projectTitle: "Carbon Offset Initiative", | ||
| shortProjectDescription: "A project focused on carbon reduction", | ||
| projectDescription: { | ||
| uri: "at://did:plc:alice/pub.leaflet.pages.linearDocument/abc123", | ||
| cid: "...", | ||
| }, | ||
| avatar: avatarBlob, | ||
| coverPhoto: coverPhotoBlob, | ||
| createdAt: new Date().toISOString(), | ||
| }; | ||
|
|
||
| // Create both with same TID | ||
| await createRecord({ | ||
| collection: "org.hypercerts.claim.collection", | ||
| rkey: tid, | ||
| record: collectionRecord, | ||
| }); | ||
| await createRecord({ | ||
| collection: "org.hypercerts.claim.collection.project", | ||
| rkey: tid, | ||
| record: projectSidecar, | ||
| }); | ||
| ``` | ||
|
|
||
| **Note**: The project sidecar is optional. Collections without this sidecar are simple groupings; collections with it are "projects" with rich documentation. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the project sidecar lexicon file exists and has the documented properties
echo "=== Searching for project sidecar lexicon file ==="
fd -e json "project" lexicons/org/hypercerts/claim/
echo ""
if [ -f "lexicons/org/hypercerts/claim/collection/project.json" ]; then
echo "✓ Project sidecar lexicon found at lexicons/org/hypercerts/claim/collection/project.json"
echo ""
echo "=== Verifying properties in project.json ==="
jq -r '.defs.main.record.properties | keys[]' lexicons/org/hypercerts/claim/collection/project.json | sort
echo ""
echo "=== Checking required fields ==="
jq -r '.defs.main.record.required[]?' lexicons/org/hypercerts/claim/collection/project.json 2>/dev/null | sort || echo "No required fields array found"
echo ""
echo "=== Full lexicon structure ==="
cat lexicons/org/hypercerts/claim/collection/project.json
else
echo "✗ Project sidecar lexicon file NOT found at expected path"
echo ""
echo "=== Checking all lexicon files in lexicons/org/hypercerts/claim/ ==="
find lexicons/org/hypercerts/claim/ -name "*.json" -type f | sort
fi
echo ""
echo "=== Checking if ERD.puml has been updated for sidecar pattern ==="
if [ -f "ERD.puml" ]; then
echo "Searching for collection.project references in ERD.puml:"
rg -n -C2 "collection\.project|sidecar" ERD.puml || echo "No sidecar references found"
else
echo "ERD.puml file not found"
fiRepository: hypercerts-org/hypercerts-lexicon
Length of output: 1032
The project sidecar lexicon file is missing from the codebase.
The README.md documents org.hypercerts.claim.collection.project with full properties and example code (lines 454-524), but the corresponding lexicon file does not exist at lexicons/org/hypercerts/claim/collection/project.json. The directory lexicons/org/hypercerts/claim/ contains only: activity, collection, contribution, evaluation, evidence, measurement, and rights.
Create the missing lexicons/org/hypercerts/claim/collection/project.json file with all documented properties (projectTitle, shortProjectDescription, projectDescription, avatar, coverPhoto, createdAt) and their types/constraints, ensuring it matches the README.md specification. Note that ERD.puml already contains partial project entity references (lines 289, 291) which should be updated to reflect the complete lexicon definition once the JSON file is created.
🤖 Prompt for AI Agents
In `@README.md` around lines 454 - 524, The README documents a missing lexicon for
org.hypercerts.claim.collection.project; add a new lexicon JSON for the lexicon
id "org.hypercerts.claim.collection.project" that defines the properties
projectTitle (string, maxLength 800, maxGraphemes 80), shortProjectDescription
(string, maxLength 3000, maxGraphemes 300), projectDescription (ref to
pub.leaflet.pages.linearDocument#main, required), avatar (blob,
image/png|image/jpeg, maxSize 1000000), coverPhoto (blob, image/png|image/jpeg,
maxSize 1000000), and createdAt (string, required) with appropriate types,
required flags and validation constraints matching README.md; ensure the
lexicon's $id/$defs mirror project semantics and then update the ERD.puml
project entity references to reflect the new complete lexicon definition.
There was a problem hiding this comment.
Was this lexicon deliberately excluded, or accidentally omitted from the commit? I don't see how it would make sense to document a lexicon but not define it, but the PR title does suggest the intention was only to document, not implement.
However I'm pretty sure you'd find that after defining it, it wouldn't compile.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
echo "=== 1. Check what changed in collection.json ==="
cat lexicons/org/hypercerts/claim/collection.json
echo ""
echo "=== 2. Search for any references to collection.project in the codebase ==="
rg -n "collection\.project|collection/project" --type-add 'lexicon:*.json' --type lexicon
echo ""
echo "=== 3. Check if there are any build/validation scripts ==="
fd -e json -e js -e ts "validate|build|compile" . --max-depth 2
echo ""
echo "=== 4. Check package.json for build scripts ==="
if [ -f "package.json" ]; then
jq -r '.scripts' package.json
fi
echo ""
echo "=== 5. Look for any schema validation or lexicon compilation tools ==="
rg -n "lexicon.*compile|lexicon.*validate|LexiconDoc" --type ts --type js -g '!node_modules' -C2 | head -50
echo ""
echo "=== 6. Check the PR diff to understand what was actually intended ==="
echo "Files changed in this PR:"
git diff --name-only develop...HEAD 2>/dev/null || echo "Git diff not available in sandbox"
Length of output: 5719
🏁 Script executed:
#!/bin/bash
echo "=== Check git log for this PR to see what was actually changed ==="
git log --oneline --all --graph -20 2>/dev/null || echo "Git log not available"
echo ""
echo "=== Check the changeset file for what was intended ==="
cat .changeset/document-location-sidecar-pattern.md
echo ""
echo "=== Look at ERD.puml to see sidecar references ==="
rg -n "sidecar|location|project" ERD.puml -C3
echo ""
echo "=== Check if pub.leaflet.pages.linearDocument is referenced elsewhere ==="
rg -n "pub\.leaflet|leaflet" lexicons/ --type json
echo ""
echo "=== Check what the lex command is and if it validates lexicons ==="
which lex 2>/dev/null || echo "lex command location not found in PATH"
npm list `@atproto/lex-cli` 2>/dev/null || echo "No `@atproto/lex-cli` in package.json"
echo ""
echo "=== Check package.json dependencies ==="
jq -r '.devDependencies, .dependencies' package.json | grep -i lex || echo "No lex-related packages found"
Length of output: 5278
🏁 Script executed:
#!/bin/bash
echo "=== Check if pub.leaflet lexicons exist in the codebase ==="
find lexicons/ -name "*.json" | xargs grep -l "pub\.leaflet" || echo "No pub.leaflet lexicons found"
echo ""
echo "=== Check if there are any external lexicon references ==="
find lexicons/ -name "*.json" -exec sh -c 'echo "File: $1"; jq -r "..|.ref? | select(. != null)" "$1" 2>/dev/null | grep -v "^org.hypercerts\|^com.atproto" | sort -u || true' _ {} \;
echo ""
echo "=== Check the actual git diff for collection.json ==="
git diff develop HEAD -- lexicons/org/hypercerts/claim/collection.json 2>/dev/null || echo "Cannot get git diff"
echo ""
echo "=== Verify the current state vs what README says ==="
echo "README says collection has these properties:"
grep "| \`collectionTitle\`" README.md || echo "collectionTitle not found in README"
grep "| \`items\`" README.md | head -1 || echo "items not found in README"
echo ""
echo "collection.json actually has these properties:"
jq -r '.defs.main.record.properties | keys[]' lexicons/org/hypercerts/claim/collection.json
echo ""
echo "=== Check if there's documentation about external lexicons ==="
rg -n "leaflet|external.*lexicon|import.*lexicon" README.md -i | head -20
Length of output: 2800
🏁 Script executed:
#!/bin/bash
echo "=== Check if collection.json has location property ==="
jq '.defs.main.record.properties.location' lexicons/org/hypercerts/claim/collection.json
echo ""
echo "=== Show the full diff between what README documents and what collection.json defines ==="
echo "Properties in README for collection:"
grep -A 100 "### org.hypercerts.claim.collection" README.md | grep "^| \`" | head -10
echo ""
echo "Properties in collection.json:"
jq -r '.defs.main.record.properties | to_entries[] | "| `\(.key)` |"' lexicons/org/hypercerts/claim/collection.json
echo ""
echo "=== Check the AI summary for what was supposed to change ==="
echo "According to AI summary, collection.json changes:"
echo "Removed the location property from the main record"
echo ""
echo "=== Search for other PRs or commits that might have changed collection schema ==="
git log --all --oneline --grep="collection\|project" -20 2>/dev/null | head -20
echo ""
echo "=== Check PR `#75` mentioned in git log about unifying projects and collections ==="
git show 95e2ba1 --stat 2>/dev/null | head -30
Length of output: 5659
@aspiers Thank you for catching this critical issue. After investigating the codebase, I found multiple significant problems:
The Documentation/Implementation Mismatch
You're absolutely right that this wouldn't compile. There's a major disconnect between what the README documents and what actually exists:
1. Collection Schema Mismatch
README.md documents (lines 407-421):
collectionTitle,shortCollectionDescription,collectionDescription,items
collection.json actually has:
type,title,shortDescription,description,activities
The collection lexicon was NOT updated to match the documented schema.
2. Missing Project Sidecar Lexicon
The README extensively documents org.hypercerts.claim.collection.project (lines 454-524) with properties like projectTitle, projectDescription, avatar, etc., but this lexicon file does not exist.
3. Historical Context
From commit 95e2ba1 (PR #75, merged Jan 20), org.hypercerts.claim.project.json was deliberately deleted and merged into collection.json with a type field approach. However, this PR's README now documents a completely different pattern (the sidecar approach) without implementing it.
4. External Lexicon Reference
collection.json references pub.leaflet.pages.linearDocument#main which doesn't exist in this repository, though this may be intentional if it's an external dependency.
Why It Won't Compile
The gen-api script (find ./lexicons -name '*.json' | xargs lex gen-api) will generate TypeScript types from the JSON lexicons, creating a mismatch with what the README suggests developers should use.
Conclusion
Based on the PR title "Document location sidecar pattern" and the changeset, this PR was only intended to document the location sidecar pattern. However, the README changes document an entirely redesigned collection schema AND a new project sidecar pattern that were never implemented.
@bitbeckers Could you clarify:
- Was the collection schema redesign (collectionTitle, items, etc.) intended to be part of this PR?
- Should the project sidecar lexicon be created, or should that documentation be removed?
- Should we revert the collection documentation to match the current schema?
🧠 Learnings used
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 README.md : Ensure all properties documented in README.md match the actual JSON schema definitions in lexicons/**/*.json
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)
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 README.md : Ensure that all lexicons documented in README.md exist as JSON files in the lexicons/ directory
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 : Verify that lexicon IDs in JSON files match what's documented in README.md
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-12T14:44:03.427Z
Learning: Applies to lexicons/**/*.json : When adding or modifying a lexicon, update `README.md` as appropriate
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 ERD.puml : Ensure that all entities referenced in ERD.puml correspond to lexicons defined in lexicons/**/*.json
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-12T14:44:03.427Z
Learning: Applies to lexicons/**/*.json : When adding or modifying a lexicon, update `ERD.puml` as appropriate to reflect entity relationship changes
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 ERD.puml if entity relationships changed (add new entities, modify relationships, remove deleted entities)
Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 37
File: lexicons/org/hypercerts/funding/receipt.json:1-71
Timestamp: 2025-12-15T15:33:27.052Z
Learning: For the hypercerts-org/hypercerts-lexicon repository, do not comment on Prettier formatting issues in code reviews because they are already reported by the lint workflow, and duplicating the report adds noise to the review.
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 ERD.puml : Ensure all relationships shown in ERD.puml are valid based on the JSON lexicon schemas in lexicons/**/*.json
Learnt from: CR
Repo: hypercerts-org/hypercerts-lexicon PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-12T14:44:03.427Z
Learning: Applies to .changeset/*.md : Changeset files should use the format with frontmatter containing package name `hypercerts-org/lexicon` and version bump type (`major`, `minor`, or `patch`), followed by a description of changes
| collection ..|> location : "sidecar\n(same TID)" | ||
|
|
||
| project::activities --> activity | ||
| project::location --> location |
There was a problem hiding this comment.
Nitpick, not a big deal: not sure it makes sense to include project any more. At least this was deliberately removed when we removed the project lexicon. If there was a reason to bring it back, then I think that could have been done in a separate commit.
| **Lexicon ID:** `org.hypercerts.claim.collection` | ||
|
|
||
| **Description:** A group of hypercerts that have a specific property. Can be a project or a collection. | ||
| **Description:** A collection/group of items (activities and/or other collections). Collections support recursive nesting. Use `org.hypercerts.claim.collection.project` as a sidecar (same TID) for project-specific metadata. |
There was a problem hiding this comment.
No, this is prohibited by ATProto. You can't have a sub-lexicon whose prefix is already a lexicon. That's why we had to previously drop the org.hypercerts.claim lexicon.
|
@bitbeckers There are several issues introduced here, one of which seems pretty critical. I'm happy to fix them if you don't have time, but it would have been nice to have the chance to catch them in a review prior to merging. Also the PR is more than just documentation, it's a breaking change (removal of |
| // Project sidecar with rich-text description and assets | ||
| const projectSidecar = { | ||
| $type: "org.hypercerts.claim.collection.project", | ||
| projectTitle: "Carbon Offset Initiative", |
There was a problem hiding this comment.
Do we really need a collection title and a project title?
2 participants
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.