@hypercerts-org/lexicon 0.10.0-beta.14 → 0.10.0-beta.16

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @hypercerts-org/lexicon
 
+## 0.10.0-beta.16
+
+### Minor Changes
+
+- [#141](https://github.com/hypercerts-org/hypercerts-lexicon/pull/141) [`06fb6b5`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/06fb6b54542fe6311d55cb26a1c468c1374b0ab1) Thanks [@holkexyz](https://github.com/holkexyz)! - Add CEL expression support for structured work scopes (`org.hypercerts.workscope.cel`, `org.hypercerts.workscope.tag`)
+
+- [#149](https://github.com/hypercerts-org/hypercerts-lexicon/pull/149) [`9f124eb`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/9f124eb404e30a30ac90a6c4be934ece84556c08) Thanks [@daviddao](https://github.com/daviddao)! - Add `org.hyperboards.board` and `org.hyperboards.displayProfile` lexicons for hyperboard visual presentation records.
+
+- [#140](https://github.com/hypercerts-org/hypercerts-lexicon/pull/140) [`20eb414`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/20eb414bd75cb100bebe16cfb41286377c18d5e7) Thanks [@holkexyz](https://github.com/holkexyz)! - Add app.certified.actor.organization sidecar record for organization actor profiles with fields for organization type, labeled URLs, location (strongRef), and founded date
+
+- [#144](https://github.com/hypercerts-org/hypercerts-lexicon/pull/144) [`fb90134`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/fb90134e5df32e955e5f9fba748f4ca46d00e90e) Thanks [@holkexyz](https://github.com/holkexyz)! - Make items optional in collection schema to allow creating empty collections
+
+- [#151](https://github.com/hypercerts-org/hypercerts-lexicon/pull/151) [`4d5f42f`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/4d5f42fa4f9ae2c74a6703f3af50e9acfd09ae95) Thanks [@holkexyz](https://github.com/holkexyz)! - Add optional `url` field to `app.certified.badge.award` for linking to an external page associated with the badge
+
+- [#152](https://github.com/hypercerts-org/hypercerts-lexicon/pull/152) [`2afb6ed`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/2afb6edb89ffd186f2e0cf015bcc3557e13a7a6d) Thanks [@holkexyz](https://github.com/holkexyz)! - Use Leaflet linear documents for rich-text descriptions in activity and attachment lexicons, and make attachment content optional.
+
+- [#153](https://github.com/hypercerts-org/hypercerts-lexicon/pull/153) [`57dc44c`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/57dc44c163a6d62e4256e3de41ccf14617eb07e8) Thanks [@holkexyz](https://github.com/holkexyz)! - Improve acknowledgement schema: move to org.hypercerts.context.acknowledgement, generalize descriptions, make context optional, add maxGraphemes to comment.
+
+- [#158](https://github.com/hypercerts-org/hypercerts-lexicon/pull/158) [`7743aa6`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/7743aa6014faa35714d3e146cfa45b0e67501992) Thanks [@holkexyz](https://github.com/holkexyz)! - Move collection lexicon from `org.hypercerts.claim.collection` to `org.hypercerts.collection` to reflect that collections can contain more than just claims.
+
+- [#154](https://github.com/hypercerts-org/hypercerts-lexicon/pull/154) [`4c52b2c`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/4c52b2c9b2d449cbeb74eea9efa0a9eb2a0a39b7) Thanks [@holkexyz](https://github.com/holkexyz)! - Move evaluation and attachment lexicons to org.hypercerts.context namespace.
+
+- [#155](https://github.com/hypercerts-org/hypercerts-lexicon/pull/155) [`a59e541`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/a59e5418e242a2f6b2868cc46f5481d75a7bf0ca) Thanks [@holkexyz](https://github.com/holkexyz)! - Rename contributionDetails to contribution (org.hypercerts.claim.contribution).
+
+- [#156](https://github.com/hypercerts-org/hypercerts-lexicon/pull/156) [`86f252d`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/86f252da1f755bac6e323142a2ed11a8c6e37cba) Thanks [@holkexyz](https://github.com/holkexyz)! - Require createdAt in app.certified.actor.profile schema
+
+- [#103](https://github.com/hypercerts-org/hypercerts-lexicon/pull/103) [`b5d79da`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/b5d79da303ff7726c7a84b7568b18ee055ac0e81) Thanks [@s-adamantine](https://github.com/s-adamantine)! - Align all lexicons with the ATProto Lexicon Style Guide: change badge response `enum` to `knownValues`, add `maxLength`/`maxGraphemes` to unconstrained string and array fields, fix style checker to skip format-typed fields.
+
+## 0.10.0-beta.15
+
+### Minor Changes
+
+- [#76](https://github.com/hypercerts-org/hypercerts-lexicon/pull/76) [`3044e22`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/3044e22c1345b3cd5764e3c6c3714b21e6911663) Thanks [@s-adamantine](https://github.com/s-adamantine)! - Add org.hypercerts.acknowledgement lexicon for bidirectional inclusion links between records across PDS repos
+
+- [#136](https://github.com/hypercerts-org/hypercerts-lexicon/pull/136) [`062fbde`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/062fbde905dbd939f75c366760be1c02bb8a0412) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Expand locationType knownValues to include geojson, h3, geohash, wkt, address, and scaledCoordinates from the [Location Protocol spec](https://spec.decentralizedgeo.org/specification/location-types/#location-type-registry)
+
 ## 0.10.0-beta.14
 
 ### Minor Changes

package/README.md

@@ -65,12 +65,27 @@ const activityRecord = {
   $type: ACTIVITY_NSID,
   title: "My Impact Work",
   shortDescription: "Description here",
-  // workScope can be a strongRef to a work-scope record:
+  // workScope can be a CEL expression (structured, machine-evaluable):
   workScope: {
-    uri: "at://did:plc:alice/org.hypercerts.helper.workScopeTag/abc123",
-    cid: "...",
+    $type: "org.hypercerts.workscope.cel",
+    expression:
+      "scope.hasAll(['mangrove_restoration', 'environmental_education']) && location.country == 'KE'",
+    usedTags: [
+      {
+        uri: "at://did:plc:alice/org.hypercerts.workscope.tag/3k2abc",
+        cid: "...",
+      },
+      {
+        uri: "at://did:plc:alice/org.hypercerts.workscope.tag/7x9def",
+        cid: "...",
+      },
+    ],
+    version: "v1",
+    createdAt: new Date().toISOString(),
   },
-  // OR a simple string: workScope: "Environmental conservation",
+  // OR a strongRef to a single work scope tag:
+  // workScope: { uri: "at://did:plc:alice/org.hypercerts.workscope.tag/abc123", cid: "..." },
+  // OR a simple string: workScope: { $type: "org.hypercerts.claim.activity#workScopeString", scope: "Environmental conservation" },
   startDate: "2023-01-01T00:00:00Z",
   endDate: "2023-12-31T23:59:59Z",
   createdAt: new Date().toISOString(),
@@ -102,7 +117,7 @@ const locationRecord = {
   $type: LOCATION_NSID,
   lpVersion: "1.0", // Location Protocol version
   srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84", // Spatial Reference System
-  locationType: "coordinate-decimal", // or "geojson-point"
+  locationType: "coordinate-decimal", // or "geojson-point", "geojson", "h3", "geohash", "wkt", "address", etc.
   location: {
     uri: "https://example.com/location-data.geojson",
   },
@@ -115,7 +130,7 @@ const locationRecord = {
 
 - `lpVersion` (required): Version of the Location Protocol specification
 - `srs` (required): Spatial Reference System URI defining the coordinate system
-- `locationType` (required): Format identifier (e.g., "coordinate-decimal", "geojson-point")
+- `locationType` (required): Format identifier (e.g., "coordinate-decimal", "geojson-point", "geojson", "h3", "geohash", "wkt", "address", "scaledCoordinates"). See the [Location Protocol spec](https://spec.decentralizedgeo.org/specification/location-types/#location-type-registry) for the full registry.
 - `location` (required): Location data as URI, blob, or string
 - `name` (optional): Human-readable name for the location
 - `description` (optional): Additional context about the location
@@ -210,7 +225,7 @@ import { HYPERCERTS_NSIDS_BY_TYPE } from "@hypercerts-org/lexicon";
 
 // Access via type namespace names
 const activityId = HYPERCERTS_NSIDS_BY_TYPE.OrgHypercertsClaimActivity;
-const collectionId = HYPERCERTS_NSIDS_BY_TYPE.OrgHypercertsClaimCollection;
+const collectionId = HYPERCERTS_NSIDS_BY_TYPE.OrgHypercertsCollection;
 ```
 
 **Lightweight Bundle**: Import from `/lexicons` for runtime validation without TypeScript types (smaller bundle size):
@@ -282,13 +297,36 @@ property tables, see [SCHEMAS.md](SCHEMAS.md).
 
 ## Examples
 
-### Creating a Collection with Nested Items
+### Collections
+
+Collections (`org.hypercerts.collection`) are named sets of references to
+other records, for any purpose the creator chooses. They live at the
+top-level namespace (not under `claim`) because they can contain more than
+just claims.
+
+#### Use Cases
+
+- Defining which activity claims belong to a project
+- Collections of projects
+- Favourites lists
+- Items associated with a particular funding round or funder
+- Portfolios of work by a contributor or organization
+- Thematic groupings (by work scope/topic)
+- Curated showcases for display (e.g. a hyperboard)
+- Milestone groupings (activities in a sprint/cycle)
+- Geographic groupings (projects or locations in a region)
+- Collections for reporting (e.g. all claims in a grant report)
+
+**Note**: Hyperboards are a separate concern — they are visualisations
+built on top of collections, not collections themselves.
+
+#### Creating a Collection with Nested Items
 
 ```typescript
 import { TID } from "@atproto/common";
 
 const collectionRecord = {
-  $type: "org.hypercerts.claim.collection",
+  $type: "org.hypercerts.collection",
   title: "Climate Action Projects",
   shortDescription:
     "A collection of climate-related activities and sub-collections",
@@ -305,7 +343,7 @@ const collectionRecord = {
     },
     // Reference to another collection (recursive!)
     {
-      uri: "at://did:plc:carol/org.hypercerts.claim.collection/4m5ghi",
+      uri: "at://did:plc:carol/org.hypercerts.collection/4m5ghi",
       cid: "...",
     },
   ],
@@ -320,7 +358,7 @@ include rich-text descriptions:
 
 ```typescript
 const projectRecord = {
-  $type: "org.hypercerts.claim.collection",
+  $type: "org.hypercerts.collection",
   type: "project",
   title: "Carbon Offset Initiative",
   shortDescription: "A project focused on carbon reduction and reforestation",
@@ -373,6 +411,73 @@ const collectionRecord = {
 are optional and support either embedded image blobs or URI references to
 external images.
 
+### Acknowledging Inclusion
+
+The `org.hypercerts.context.acknowledgement` record enables bidirectional
+linking between records that live in different PDS repositories. When
+one user includes another user's record (e.g. adding an activity to a
+collection), the owner of the included record can create an
+acknowledgement to confirm or reject the inclusion. This forms a
+two-way link that an AppView can verify.
+
+Each acknowledgement uses `com.atproto.repo.strongRef` fields to
+reference both the **subject** (the record being included) and the
+**context** (the record it's being included in).
+
+See [SCHEMAS.md](SCHEMAS.md) for the full property reference.
+
+#### Use Case: Activity Included in a Collection
+
+A project organizer (Alice) creates a collection and adds Bob's
+activity to it via a `strongRef` in the collection's `items[]` array.
+Bob then creates an acknowledgement in his own repo to confirm:
+
+```typescript
+import { ACKNOWLEDGEMENT_NSID } from "@hypercerts-org/lexicon";
+
+// Bob acknowledges that his activity is included in Alice's collection
+const ack = {
+  $type: ACKNOWLEDGEMENT_NSID,
+  subject: {
+    uri: "at://did:plc:bob/org.hypercerts.claim.activity/3k2abc",
+    cid: "bafy...",
+  },
+  context: {
+    uri: "at://did:plc:alice/org.hypercerts.collection/7x9def",
+    cid: "bafy...",
+  },
+  acknowledged: true,
+  createdAt: new Date().toISOString(),
+};
+```
+
+#### Use Case: Contributor Included in an Activity
+
+Alice creates an activity that lists Bob as a contributor. Bob creates
+an acknowledgement in his own repo to confirm his participation:
+
+```typescript
+const ack = {
+  $type: ACKNOWLEDGEMENT_NSID,
+  subject: {
+    // Bob's contributor information record
+    uri: "at://did:plc:bob/org.hypercerts.claim.contributorInformation/abc123",
+    cid: "bafy...",
+  },
+  context: {
+    // Alice's activity that lists Bob as contributor
+    uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc",
+    cid: "bafy...",
+  },
+  acknowledged: true,
+  comment: "Confirming my contribution to this reforestation project",
+  createdAt: new Date().toISOString(),
+};
+```
+
+Setting `acknowledged: false` explicitly rejects inclusion, which an
+AppView can use to flag disputed associations.
+
 ### Adding Locations to Activities
 
 The `locations` field in activity records is an array of strong references
@@ -396,7 +501,7 @@ Collections can include an optional `location` field to specify where the collec
 
 ```typescript
 const collectionRecord = {
-  $type: "org.hypercerts.claim.collection",
+  $type: "org.hypercerts.collection",
   title: "Climate Action Projects",
   shortDescription: "A collection of climate-related activities",
   location: {