@hypercerts-org/lexicon 0.10.0-beta.4 → 0.10.0-beta.5

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @hypercerts-org/lexicon
 
+## 0.10.0-beta.5
+
+### Minor Changes
+
+- [#78](https://github.com/hypercerts-org/hypercerts-lexicon/pull/78) [`c55d8a7`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/c55d8a77ff2949136bab0c6680b7e458712404f1) Thanks [@bitbeckers](https://github.com/bitbeckers)! - Remove org.hypercerts.claim.project lexicon and replace with org.hypercerts.claim.collection.project sidecar. Projects are now represented as collections with an optional project sidecar (same TID) that provides rich-text descriptions, avatars, and cover photos. Avatar and coverPhoto fields moved from base collection to project sidecar. Collections without the project sidecar are simple groupings; collections with it are "projects" with rich documentation.
+
+- [#93](https://github.com/hypercerts-org/hypercerts-lexicon/pull/93) [`3276d6e`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/3276d6e59975ac8cfdd9a8eed09ddfd57fdddf41) Thanks [@bitbeckers](https://github.com/bitbeckers)! - Change workScope from inline object definition to strongRef in activity lexicon. This breaking change removes the workScope definition (withinAllOf, withinAnyOf, withinNoneOf properties) and changes the workScope property to reference an external record via strongRef, allowing for more flexible work scope definitions.
+
+- [#97](https://github.com/hypercerts-org/hypercerts-lexicon/pull/97) [`ceddab9`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/ceddab9e829d8ade3868eac4d10dd906e12a153c) Thanks [@aspiers](https://github.com/aspiers)! - Move schema documentation tables from README.md to auto-generated SCHEMAS.md to reduce git merge conflicts. The SCHEMAS.md file is now auto-generated from lexicon definitions and included in the distributed package.
+
+- [#78](https://github.com/hypercerts-org/hypercerts-lexicon/pull/78) [`cc9d7bf`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/cc9d7bff3dc63f155ce8e11204fc1506ca687711) Thanks [@bitbeckers](https://github.com/bitbeckers)! - Refactor collection lexicon to use items array instead of activities. The items array contains plain strongRefs (com.atproto.repo.strongRef) that can reference activities (org.hypercerts.claim.activity) and/or other collections (org.hypercerts.claim.collection), enabling recursive collection nesting. This change removes the activityWeight object structure from the base collection lexicon.
+
+- [#67](https://github.com/hypercerts-org/hypercerts-lexicon/pull/67) [`b51dd76`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/b51dd7652b73c5ae6bba103f07eca9f5195809f0) Thanks [@bitbeckers](https://github.com/bitbeckers)! - Remove bidirectional project-activity link. Activities no longer include a `project` field reference. Projects continue to reference activities via the `activities` array, making the relationship unidirectional (project → activities only).
+
+- [#98](https://github.com/hypercerts-org/hypercerts-lexicon/pull/98) [`43b0431`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/43b04316d8cb11066d61d79e70f262f0d2426cde) Thanks [@aspiers](https://github.com/aspiers)! - Remove org.hypercerts.claim.collection.project lexicon
+
+- [#75](https://github.com/hypercerts-org/hypercerts-lexicon/pull/75) [`95e2ba1`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/95e2ba174ea348746ce64507bf94b73c3d3d3954) Thanks [@s-adamantine](https://github.com/s-adamantine)! - Unify project and collection schemas into a single
+  `org.hypercerts.claim.collection` lexicon with `type` discriminator
+  field to allow collections to be designated as projects. Custom
+  strings are also allowed in `type`.
+
+  Also make `shortDescription` field optional in
+  `org.hypercerts.claim.collection` to match
+  `org.hypercerts.claim.project`.
+
+  This unification removes `org.hypercerts.claim.project`, so existing
+  projects should be migrated to collections with `type` set to
+  `project`.
+
+- [#80](https://github.com/hypercerts-org/hypercerts-lexicon/pull/80) [`e8d5a7c`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/e8d5a7cd080e4f8d4e6b96ce5762678deaeb2902) Thanks [@s-adamantine](https://github.com/s-adamantine)! - Updated `org.hypercerts.claim.collection` lexicon:
+  - Added optional `type` field to specify collection type (e.g., 'favorites', 'project')
+  - Renamed fields for consistency:
+    - `collectionTitle` → `title`
+    - `shortCollectionDescription` → `shortDescription`
+    - `collectionDescription` → `description`
+  - Changed `description` from string to Leaflet linear document reference (`pub.leaflet.pages.linearDocument#main`) to support rich-text descriptions
+
+  **Breaking changes**:
+  - Field names have been renamed (e.g., `collectionTitle` → `title`)
+  - The `description` field now expects a reference object instead of a plain string
+
+- [#92](https://github.com/hypercerts-org/hypercerts-lexicon/pull/92) [`bec8e63`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/bec8e63195fb73734b68f3d5201864b9bede0904) Thanks [@s-adamantine](https://github.com/s-adamantine)! - Update `org.hypercerts.claim.contributor` lexicon to support individual contributor profiles and roles.
+
+  Breaking Changes:
+  - Removed `contributors` array.
+  - Added `identifier`, `displayName`, and `image` fields for individual profiles.
+  - Renamed `description` to `contributionDescription`.
+  - Updated `required` fields to only include `createdAt`.
+
+  Also corrected incorrect references to `org.hypercerts.claim.contribution` across the codebase to use the correct ID `org.hypercerts.claim.contributor`.
+
+### Patch Changes
+
+- [#77](https://github.com/hypercerts-org/hypercerts-lexicon/pull/77) [`0d61ff7`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/0d61ff7e030a25682cd71877ae603b8782b09c3b) Thanks [@bitbeckers](https://github.com/bitbeckers)! - 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.
+
+- [#74](https://github.com/hypercerts-org/hypercerts-lexicon/pull/74) [`f845f92`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/f845f924907f62c8b96afa6a18ac203c4bd4cad5) Thanks [@aspiers](https://github.com/aspiers)! - Make startDate and endDate optional in activity lexicon
+
 ## 0.10.0-beta.4
 
 ### Minor Changes

package/README.md

@@ -65,7 +65,10 @@ const activityRecord = {
   $type: ACTIVITY_NSID,
   title: "My Impact Work",
   shortDescription: "Description here",
-  workScope: "Scope of work",
+  workScope: {
+    uri: "at://did:plc:alice/org.hypercerts.claim.workscope/abc123",
+    cid: "...",
+  },
   startDate: "2023-01-01T00:00:00Z",
   endDate: "2023-12-31T23:59:59Z",
   createdAt: new Date().toISOString(),
@@ -181,321 +184,73 @@ const rightsJSON = HYPERCERTS_LEXICON_JSON.RIGHTS;
 const rightsDoc = HYPERCERTS_LEXICON_DOC.RIGHTS;
 ```
 
-## Certified Lexicons
+## Schema Documentation
 
-Certified lexicons are common/shared lexicons that can be used across multiple protocols.
+For complete schema documentation with all lexicon definitions and
+property tables, see [SCHEMAS.md](SCHEMAS.md).
 
-### Common Definitions
+## Examples
 
-**Lexicon ID:** `org.hypercerts.defs`
+### Creating a Collection with Nested Items
 
-**Description:** Common type definitions used across all certified protocols.
-
-#### Defs
-
-| Def          | Type     | Description                               | Comments                                |
-| ------------ | -------- | ----------------------------------------- | --------------------------------------- |
-| `uri`        | `object` | Object containing a URI to external data  | Has `uri` property (string, format uri) |
-| `smallBlob`  | `object` | Object containing a blob to external data | Has `blob` property (blob, up to 10MB)  |
-| `largeBlob`  | `object` | Object containing a blob to external data | Has `blob` property (blob, up to 100MB) |
-| `smallImage` | `object` | Object containing a small image           | Has `image` property (blob, up to 5MB)  |
-| `largeImage` | `object` | Object containing a large image           | Has `image` property (blob, up to 10MB) |
-
----
-
-### Location Lexicon
-
-**Lexicon ID:** `app.certified.location`
-
-**Description:** A location reference for use across certified protocols. For more information about
-
-**Key:** `tid`
-
-#### Properties
-
-| Property       | Type     | Required | Description                                                                                                               |
-| -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `lpVersion`    | `string` | ✅       | The version of the Location Protocol                                                                                      |
-| `srs`          | `string` | ✅       | The Spatial Reference System URI (e.g., http://www.opengis.net/def/crs/OGC/1.3/CRS84) that defines the coordinate system. |
-| `locationType` | `string` | ✅       | An identifier for the format of the location data (e.g., coordinate-decimal, geojson-point)                               |
-| `location`     | `union`  | ✅       | The location of where the work was performed as a URI or blob.                                                            |
-| `name`         | `string` | ❌       | Optional name for this location                                                                                           |
-| `description`  | `string` | ❌       | Optional description for this location                                                                                    |
-| `createdAt`    | `string` | ✅       | Client-declared timestamp when this record was originally created                                                         |
-
-### Badges Lexicon
-
-**Lexicon IDs:** `app.certified.badge.definition`, `app.certified.badge.award`, `app.certified.badge.response`
-
-**Description:** Defines badge metadata, award records, and recipient responses for certified badges that can be used across protocols.
-
-#### Badge Definition
-
-**Lexicon ID:** `app.certified.badge.definition`
-
-**Key:** `tid`
-
-| Property         | Type     | Required | Description                                                            |
-| ---------------- | -------- | -------- | ---------------------------------------------------------------------- |
-| `badgeType`      | `string` | ✅       | Category of the badge (e.g., endorsement, participation, affiliation). |
-| `title`          | `string` | ✅       | Human-readable title of the badge.                                     |
-| `icon`           | `blob`   | ✅       | Icon representing the badge (accepted `image/*` types, maxSize 1MB).   |
-| `description`    | `string` | ❌       | Optional short statement describing the badge.                         |
-| `allowedIssuers` | `array`  | ❌       | Optional allowlist of DIDs allowed to issue this badge.                |
-| `createdAt`      | `string` | ✅       | Client-declared timestamp when this record was originally created.     |
-
-#### Badge Award
-
-**Lexicon ID:** `app.certified.badge.award`
-
-**Key:** `tid`
-
-| Property    | Type     | Required | Description                                                                          |
-| ----------- | -------- | -------- | ------------------------------------------------------------------------------------ |
-| `badge`     | `ref`    | ✅       | Reference to the badge definition for this award (`app.certified.badge.definition`). |
-| `subject`   | `union`  | ✅       | Entity the badge award is for (either a DID or a specific AT Protocol record).       |
-| `note`      | `string` | ❌       | Optional explanation for the award.                                                  |
-| `createdAt` | `string` | ✅       | Client-declared timestamp when this record was originally created.                   |
-
-#### Badge Response
-
-**Lexicon ID:** `app.certified.badge.response`
-
-**Key:** `tid`
-
-| Property     | Type     | Required | Description                                                            |
-| ------------ | -------- | -------- | ---------------------------------------------------------------------- |
-| `badgeAward` | `ref`    | ✅       | Reference to the badge award (`app.certified.badge.award`).            |
-| `response`   | `string` | ✅       | Enum: `accepted` or `rejected`.                                        |
-| `weight`     | `string` | ❌       | Optional relative weight assigned by the recipient (stored as string). |
-| `createdAt`  | `string` | ✅       | Client-declared timestamp when this record was originally created.     |
-
----
-
-## Hypercerts Lexicons
-
-Hypercerts-specific lexicons for tracking impact work and claims.
-
-### Hypercerts Activity Claim
-
-**Lexicon ID:** `org.hypercerts.claim.activity`
-
-**Description:** The main lexicon where everything is connected to. This is the hypercert record that tracks impact work.
-
-**Key:** `any`
-
-#### Properties
-
-| Property           | Type     | Required | Description                                                                                  | Comments                                                                  |
-| ------------------ | -------- | -------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `title`            | `string` | ✅       | Title of the hypercert                                                                       |                                                                           |
-| `shortDescription` | `string` | ✅       | Short blurb of the impact work done.                                                         |                                                                           |
-| `description`      | `string` | ❌       | Optional longer description of the impact work done.                                         |                                                                           |
-| `image`            | `union`  | ❌       | The hypercert visual representation as a URI or image blob                                   |                                                                           |
-| `workScope`        | `object` | ❌       | Logical scope of the work using label-based conditions                                       | Object with `withinAllOf`, `withinAnyOf`, `withinNoneOf` arrays of labels |
-| `startDate`        | `string` | ✅       | When the work began                                                                          |                                                                           |
-| `endDate`          | `string` | ✅       | When the work ended                                                                          |                                                                           |
-| `contributions`    | `array`  | ❌       | A strong reference to the contributions done to create the impact in the hypercerts          | References must conform to `org.hypercerts.claim.contribution`            |
-| `rights`           | `ref`    | ❌       | A strong reference to the rights that this hypercert has                                     | References must conform to `org.hypercerts.claim.rights`                  |
-| `locations`        | `ref`    | ❌       | An array of strong references to the locations where the work for done hypercert was located | References must conform to `app.certified.location`                       |
-| `project`          | `string` | ❌       | A reference (AT-URI) to the project record that this activity is part of                     | References must conform to `org.hypercerts.claim.project`                 |
-| `createdAt`        | `string` | ✅       | Client-declared timestamp when this record was originally created                            |                                                                           |
-
-#### Defs
-
-##### activityWeight
-
-| Property   | Type     | Required | Description                                                                                                                                                                                                                                                                   |
-| ---------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `activity` | `ref`    | ✅       | A strong reference to a hypercert activity record. This activity must conform to the lexicon org.hypercerts.claim.activity                                                                                                                                                    |
-| `weight`   | `string` | ✅       | The relative weight/importance of this hypercert activity (stored as a string to avoid float precision issues). Weights can be any positive numeric values and do not need to sum to a specific total; normalization can be performed by the consuming application as needed. |
-
----
-
-### Hypercerts Contribution
-
-**Lexicon ID:** `org.hypercerts.claim.contribution`
-
-**Description:** A contribution made toward a hypercert's impact.
-
-**Key:** `tid`
-
-#### Properties
-
-| Property       | Type     | Required | Description                                                                                                                                                             |
-| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `role`         | `string` | ❌       | Role or title of the contributor(s).                                                                                                                                    |
-| `contributors` | `array`  | ✅       | List of the contributors (names, pseudonyms, or DIDs). If multiple contributors are stored in the same hypercertContribution, then they would have the exact same role. |
-| `description`  | `string` | ❌       | What the contribution concretely achieved                                                                                                                               |
-| `startDate`    | `string` | ❌       | When this contribution started. This should be a subset of the hypercert timeframe.                                                                                     |
-| `endDate`      | `string` | ❌       | When this contribution finished. This should be a subset of the hypercert timeframe.                                                                                    |
-| `createdAt`    | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                                                       |
-
----
-
-### Hypercerts Evaluation
-
-**Lexicon ID:** `org.hypercerts.claim.evaluation`
-
-**Description:** An evaluation of a hypercert record (e.g. an activity and its impact).
-
-**Key:** `tid`
-
-#### Properties
-
-| Property       | Type     | Required | Description                                                                 | Comments                                                      |
-| -------------- | -------- | -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `subject`      | `ref`    | ❌       | A strong reference to what is being evaluated                               | (e.g activity, measurement, contribution, etc.)               |
-| `evaluators`   | `array`  | ✅       | DIDs of the evaluators                                                      |                                                               |
-| `content`      | `array`  | ❌       | Evaluation data (URIs or blobs) containing detailed reports or methodology  |                                                               |
-| `measurements` | `array`  | ❌       | Optional references to the measurements that contributed to this evaluation | References must conform to `org.hypercerts.claim.measurement` |
-| `summary`      | `string` | ✅       | Brief evaluation summary                                                    |                                                               |
-| `score`        | `object` | ❌       | Optional overall score for this evaluation on a numeric scale               | Object with `min`, `max`, and `value` (integers)              |
-| `location`     | `ref`    | ❌       | An optional reference for georeferenced evaluations                         | References must conform to `app.certified.location`           |
-| `createdAt`    | `string` | ✅       | Client-declared timestamp when this record was originally created           |                                                               |
-
----
-
-### Hypercerts Evidence
-
-**Lexicon ID:** `org.hypercerts.claim.evidence`
-
-**Description:** A piece of evidence related to a hypercert record (e.g. an activity, project, claim, or evaluation). Evidence may support, clarify, or challenge the referenced subject.
-
-**Key:** `tid`
-
-#### Properties
-
-| Property           | Type     | Required | Description                                                       | Comments                                             |
-| ------------------ | -------- | -------- | ----------------------------------------------------------------- | ---------------------------------------------------- |
-| `subject`          | `ref`    | ❌       | A strong reference to the record this evidence relates to         | (e.g. an activity, project, claim, or evaluation)    |
-| `content`          | `union`  | ✅       | A piece of evidence (URI or blob) related to the subject record   | May support, clarify, or challenge a hypercert claim |
-| `title`            | `string` | ✅       | Title to describe the nature of the evidence                      |                                                      |
-| `shortDescription` | `string` | ❌       | Short description explaining what this evidence shows             |                                                      |
-| `description`      | `string` | ❌       | Longer description describing the evidence in more detail         |                                                      |
-| `relationType`     | `string` | ❌       | How this evidence relates to the subject                          | Known values: `supports`, `challenges`, `clarifies`  |
-| `createdAt`        | `string` | ✅       | Client-declared timestamp when this record was originally created |                                                      |
-
----
-
-### org.hypercerts.claim.measurement
-
-**Lexicon ID:** `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)                        |
-| `measurers`   | `array`  | ✅       | DIDs of the entity (or entities) that measured this data                      |                                                              |
-| `metric`      | `string` | ✅       | The metric being measured                                                     |                                                              |
-| `value`       | `string` | ✅       | The measured value                                                            |                                                              |
-| `methodType`  | `string` | ❌       | Short identifier for the measurement methodology                              |                                                              |
-| `methodURI`   | `string` | ❌       | URI to methodology documentation, standard protocol, or measurement procedure |                                                              |
-| `evidenceURI` | `array`  | ❌       | URIs to related evidence or underlying data                                   | (e.g. org.hypercerts.claim.evidence records or raw datasets) |
-| `location`    | `ref`    | ❌       | A strong reference to the location where the measurement was taken            | References must conform to `app.certified.location`          |
-| `createdAt`   | `string` | ✅       | Client-declared timestamp when this record was originally created             |                                                              |
-
----
-
-### org.hypercerts.claim.collection
-
-**Lexicon ID:** `org.hypercerts.claim.collection`
-
-**Description:** A collection/group of hypercerts that have a specific property.
-
-**Key:** `tid`
-
-#### Properties
-
-| Property           | Type     | Required | Description                                                             | Comments                                                            |
-| ------------------ | -------- | -------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `title`            | `string` | ✅       | The title of this collection                                            |                                                                     |
-| `shortDescription` | `string` | ❌       | A short description of this collection                                  |                                                                     |
-| `avatar`           | `blob`   | ❌       | Primary avatar image representing this collection across apps and views | Typically a square image                                            |
-| `coverPhoto`       | `blob`   | ❌       | The cover photo of this collection                                      |                                                                     |
-| `activities`       | `array`  | ✅       | Array of activities with their associated weights in this collection    | Each item references `org.hypercerts.claim.activity#activityWeight` |
-| `createdAt`        | `string` | ✅       | Client-declared timestamp when this record was originally created       |                                                                     |
-
----
-
-### org.hypercerts.claim.project
-
-**Lexicon ID:** `org.hypercerts.claim.project`
-
-**Description:** A project that can include multiple activities, each of which may be linked to at most one project.
-
-**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               |                                                                     |
-
----
-
-### org.hypercerts.claim.rights
-
-**Lexicon ID:** `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.
-
-**Key:** `tid`
-
-#### Properties
-
-| Property            | Type     | Required | Description                                                       | Comments    |
-| ------------------- | -------- | -------- | ----------------------------------------------------------------- | ----------- |
-| `rightsName`        | `string` | ✅       | Full name of the rights                                           |             |
-| `rightsType`        | `string` | ✅       | Short rights identifier for easier search                         |             |
-| `rightsDescription` | `string` | ✅       | Description of the rights of this hypercert                       |             |
-| `attachment`        | `union`  | ❌       | An attachment to define the rights further, e.g. a legal document | URI or blob |
-| `createdAt`         | `string` | ✅       | Client-declared timestamp when this record was originally created |             |
-
----
-
-### org.hypercerts.funding.receipt
-
-**Lexicon ID:** `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.
-
-**Key:** `tid`
-
-#### Properties
+```typescript
+import { TID } from "@atproto/common";
+
+const collectionRecord = {
+  $type: "org.hypercerts.claim.collection",
+  title: "Climate Action Projects",
+  shortDescription:
+    "A collection of climate-related activities and sub-collections",
+  items: [
+    // Reference to an activity
+    {
+      uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc",
+      cid: "...",
+    },
+    // Reference to another activity
+    {
+      uri: "at://did:plc:bob/org.hypercerts.claim.activity/7x9def",
+      cid: "...",
+    },
+    // Reference to another collection (recursive!)
+    {
+      uri: "at://did:plc:carol/org.hypercerts.claim.collection/4m5ghi",
+      cid: "...",
+    },
+  ],
+  createdAt: new Date().toISOString(),
+};
+```
 
-| Property         | Type     | Required | Description                                                                                                                 | Comments                                                    |
-| ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `from`           | `string` | ✅       | DID of the sender who transferred the funds. If sender wants to stay anonymous, mark this explicitly.                       | Format: did                                                 |
-| `to`             | `string` | ✅       | The recipient of the funds, who can be identified by DID or a clear-text name.                                              |                                                             |
-| `amount`         | `string` | ✅       | Amount of funding received.                                                                                                 |                                                             |
-| `currency`       | `string` | ✅       | Currency of the payment (e.g. EUR, USD, ETH).                                                                               |                                                             |
-| `paymentRail`    | `string` | ❌       | How the funds were transferred (e.g. bank_transfer, credit_card, onchain, cash, check, payment_processor).                  |                                                             |
-| `paymentNetwork` | `string` | ❌       | Optional network within the payment rail (e.g. arbitrum, ethereum, sepa, visa, paypal).                                     |                                                             |
-| `transactionId`  | `string` | ❌       | Identifier of the underlying payment transaction (e.g. bank reference, onchain transaction hash, or processor-specific ID). | Use paymentNetwork to specify the network where applicable. |
-| `for`            | `string` | ❌       | Optional reference to the activity, project, or organization this funding relates to.                                       | Format: at-uri                                              |
-| `notes`          | `string` | ❌       | Optional notes or additional context for this funding receipt.                                                              | maxLength: 500                                              |
-| `occurredAt`     | `string` | ❌       | Timestamp when the payment occurred.                                                                                        | Format: datetime                                            |
-| `createdAt`      | `string` | ✅       | Client-declared timestamp when this receipt record was created.                                                             | Format: datetime                                            |
+### Creating a Project
 
----
+Projects are collections with a `type` field set to "project" and can
+include rich-text descriptions:
 
-## Notes
+```typescript
+const projectRecord = {
+  $type: "org.hypercerts.claim.collection",
+  type: "project",
+  title: "Carbon Offset Initiative",
+  shortDescription: "A project focused on carbon reduction and reforestation",
+  description: {
+    uri: "at://did:plc:alice/pub.leaflet.pages.linearDocument/abc123",
+    cid: "...",
+  },
+  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(),
+};
+```
 
-- All timestamps use the `datetime` format (ISO 8601)
-- Strong references (`com.atproto.repo.strongRef`) include both the URI and CID of the referenced record
-- Union types allow multiple possible formats (e.g., URI or blob)
-- Array items may have constraints like `maxLength` to limit the number of elements
-- String fields may have both `maxLength` (bytes) and `maxGraphemes` (Unicode grapheme clusters) constraints
+**Note**: The `type` field is optional and can be set to "project",
+"favorites", or any other collection type. The `description` field
+supports rich-text via Leaflet linear documents.