@hypercerts-org/lexicon 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @hypercerts-org/lexicon
 
+## 0.11.1
+
+### Patch Changes
+
+- [#196](https://github.com/hypercerts-org/hypercerts-lexicon/pull/196) [`e66a459`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/e66a4595e5df6640d082072284c96282acaa3faf) Thanks [@aspiers](https://github.com/aspiers)! - Fix incorrect NSID reference in `org.hyperboards.board` subject field description (`org.hypercerts.claim.collection` → `org.hypercerts.collection`).
+
+  Documentation fixes in `README.md` and `SCHEMAS.md`:
+  - Correct `validate()` call signature examples (parameter order and result shape)
+  - Fix relationship diagram arrow directions and missing entries (`link/evm`, `CERTIFIED` section)
+  - Fix contributor field name (`avatar` → `image`)
+  - Fix context target descriptions (generalized to `any record` since subjects use generic `strongRef`)
+  - Add missing `$type` discriminators to union member examples
+
 ## 0.11.0
 
 The v0.11.0 release introduces EVM identity linking, stronger type safety across badge and funding schemas, vendored Leaflet lexicons for runtime validation, and a set of schema refinements based on real-world usage from the first month of v0.10.0 adoption. All changes listed below are merged to `main` and will ship together as a single coordinated release.

package/README.md

@@ -14,19 +14,19 @@ CLAIMS ─ the core impact record and its parts
   (the hypercert)    │       │          │
                      │       ▼          │
                      ├──► contribution          (role, timeframe)
-                     ├──► contributorInformation (identity, avatar)
+                     ├──► contributorInformation (identity, image)
                      ├──► rights                (licensing terms)
                      └──► workScope
-                            ├── cel             (CEL expression)
-                            └── tag             (reusable scope atom)
+                            ├── cel ───► tag    (CEL expression referencing tags)
+                            └── string          (free-form scope)
 
 CONTEXT ─ evidence, data, and social verification
 ──────────────────────────────────────────────────────────────────────
-  attachment ─────────────► activity / evaluation / ...
-  measurement ────────────► activity / ...
-  evaluation ─────────────► activity / attachment
+  attachment ─────────────► any record (activity, evaluation, …)
+  measurement ────────────► any record (activity, …)
+  evaluation ─────────────► any record (activity, measurement, …)
                   └──────► measurement
-  acknowledgement ────────► activity / collection  (bidirectional link)
+  acknowledgement ────────► any record  (bidirectional link)
 
 FUNDING ─ payment records
 ──────────────────────────────────────────────────────────────────────
@@ -41,9 +41,10 @@ HYPERBOARDS ─ visual display layer (hyperboards.org)
 CERTIFIED ─ shared lexicons (certified.app)
 ──────────────────────────────────────────────────────────────────────
   location                  (geo coordinates, GeoJSON, H3, …)
+  link/evm                  (ATProto DID ↔ EVM wallet link)
   actor/profile             (user profile)
   actor/organization        (org metadata)
-  badge/definition ──► badge/award ──► badge/response
+  badge/response ──► badge/award ──► badge/definition
 ```
 
 Every arrow (`►`) is a `strongRef` or union reference stored on the
@@ -206,8 +207,8 @@ const record = {
 };
 
 // Validate before writing
-const result = validate(ACTIVITY_NSID, record);
-if (!result.valid) throw new Error(JSON.stringify(result.errors));
+const result = validate(record, ACTIVITY_NSID, "main");
+if (!result.success) throw new Error(String(result.error));
 
 // Write to the network
 await agent.api.com.atproto.repo.createRecord({
@@ -225,7 +226,7 @@ await agent.api.com.atproto.repo.createRecord({
 | --------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | **Activity**                | `org.hypercerts.claim.activity`               | The main hypercert record — describes impact work with title, description, contributors, work scope, timeframe, locations, and rights. |
 | **Contribution**            | `org.hypercerts.claim.contribution`           | Details about a specific contribution: role, description, and timeframe.                                                               |
-| **Contributor Information** | `org.hypercerts.claim.contributorInformation` | Identity record for a contributor: identifier (DID or URI), display name, and avatar.                                                  |
+| **Contributor Information** | `org.hypercerts.claim.contributorInformation` | Identity record for a contributor: identifier (DID or URI), display name, and image.                                                   |
 | **Rights**                  | `org.hypercerts.claim.rights`                 | Licensing and rights terms (e.g. "CC BY-SA 4.0") attached to an activity.                                                              |
 
 ### Collections (`org.hypercerts.*`)
@@ -270,7 +271,7 @@ await agent.api.com.atproto.repo.createRecord({
 | **Location**         | `app.certified.location`           | Geographic reference using the [Location Protocol](https://spec.decentralizedgeo.org) (coordinates, GeoJSON, H3, WKT, etc.).    |
 | **Profile**          | `app.certified.actor.profile`      | User account profile with display name, bio, avatar, and banner.                                                                |
 | **Organization**     | `app.certified.actor.organization` | Organization metadata: legal structure, URLs, location, founding date.                                                          |
-| **Badge Definition** | `app.certified.badge.definition`   | Defines a badge type with title, icon, and optional issuer allowlist.                                                           |
+| **Badge Definition** | `app.certified.badge.definition`   | Defines a badge with type, title, icon, and optional issuer allowlist.                                                          |
 | **Badge Award**      | `app.certified.badge.award`        | Awards a badge to a user, project, or activity.                                                                                 |
 | **Badge Response**   | `app.certified.badge.response`     | Recipient accepts or rejects a badge award.                                                                                     |
 | **EVM Link**         | `app.certified.link.evm`           | Verifiable ATProto DID ↔ EVM wallet link via EIP-712 signature. Extensible for future proof methods (e.g. ERC-1271, ERC-6492). |
@@ -295,7 +296,10 @@ await agent.api.com.atproto.repo.createRecord({
 Individual constants (recommended):
 
 ```typescript
-import { ACTIVITY_NSID, COLLECTION_NSID } from "@hypercerts-org/lexicon";
+import {
+  ACTIVITY_NSID,
+  HYPERCERTS_COLLECTION_NSID,
+} from "@hypercerts-org/lexicon";
 ```
 
 Semantic object:
@@ -387,10 +391,10 @@ const activity = {
 ### Creating Collections (Projects, Portfolios, etc.)
 
 ```typescript
-import { COLLECTION_NSID } from "@hypercerts-org/lexicon";
+import { HYPERCERTS_COLLECTION_NSID } from "@hypercerts-org/lexicon";
 
 const project = {
-  $type: COLLECTION_NSID,
+  $type: HYPERCERTS_COLLECTION_NSID,
   type: "project",
   title: "Carbon Offset Initiative",
   shortDescription: "Activities focused on carbon reduction and reforestation",
@@ -430,7 +434,10 @@ const location = {
   lpVersion: "1.0",
   srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
   locationType: "coordinate-decimal",
-  location: { string: "-3.4653, -62.2159" },
+  location: {
+    $type: "app.certified.location#string",
+    string: "-3.4653, -62.2159",
+  },
   name: "Amazon Research Station",
   createdAt: new Date().toISOString(),
 };
@@ -441,7 +448,10 @@ const geoLocation = {
   lpVersion: "1.0",
   srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
   locationType: "geojson-point",
-  location: { string: '{"type":"Point","coordinates":[-62.2159,-3.4653]}' },
+  location: {
+    $type: "app.certified.location#string",
+    string: '{"type":"Point","coordinates":[-62.2159,-3.4653]}',
+  },
   name: "Research Station Alpha",
   createdAt: new Date().toISOString(),
 };
@@ -453,15 +463,17 @@ When one user includes another's record (e.g. adding an activity to a
 collection), the owner can confirm or reject with an acknowledgement:
 
 ```typescript
-import { ACKNOWLEDGEMENT_NSID } from "@hypercerts-org/lexicon";
+import { CONTEXT_ACKNOWLEDGEMENT_NSID } from "@hypercerts-org/lexicon";
 
 const ack = {
-  $type: ACKNOWLEDGEMENT_NSID,
+  $type: CONTEXT_ACKNOWLEDGEMENT_NSID,
   subject: {
     uri: "at://did:plc:bob/org.hypercerts.claim.activity/3k2abc",
     cid: "bafy...",
   },
+  // context is a union — use $type to specify the variant
   context: {
+    $type: "com.atproto.repo.strongRef",
     uri: "at://did:plc:alice/org.hypercerts.collection/7x9def",
     cid: "bafy...",
   },
@@ -473,10 +485,10 @@ const ack = {
 ### Creating Attachments
 
 ```typescript
-import { ATTACHMENT_NSID } from "@hypercerts-org/lexicon";
+import { CONTEXT_ATTACHMENT_NSID } from "@hypercerts-org/lexicon";
 
 const attachment = {
-  $type: ATTACHMENT_NSID,
+  $type: CONTEXT_ATTACHMENT_NSID,
   title: "Field Survey Report",
   contentType: "report",
   subjects: [
@@ -485,9 +497,13 @@ const attachment = {
       cid: "...",
     },
   ],
+  // content items are a union — use $type to specify the variant
   content: [
-    { uri: "https://example.com/reports/survey-2024.pdf" },
-    { uri: "ipfs://Qm..." },
+    {
+      $type: "org.hypercerts.defs#uri",
+      uri: "https://example.com/reports/survey-2024.pdf",
+    },
+    { $type: "org.hypercerts.defs#uri", uri: "ipfs://Qm..." },
   ],
   shortDescription: "Quarterly field survey documenting project progress",
   createdAt: new Date().toISOString(),

package/SCHEMAS.md

@@ -660,12 +660,12 @@ Specifies the sub-string range a facet feature applies to. Start index is inclus
 
 #### Properties
 
-| Property             | Type     | Required | Description                                                                                              | Comments        |
-| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------- | --------------- |
-| `subject`            | `ref`    | ✅       | Reference to the org.hypercerts.claim.activity or org.hypercerts.claim.collection this board visualizes. |                 |
-| `config`             | `ref`    | ❌       | Visual configuration for a hyperboard's background, colors, and layout.                                  |                 |
-| `contributorConfigs` | `ref[]`  | ❌       | Per-contributor configuration entries for this board.                                                    | maxLength: 1000 |
-| `createdAt`          | `string` | ✅       | Client-declared timestamp when this record was originally created.                                       |                 |
+| Property             | Type     | Required | Description                                                                                        | Comments        |
+| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------- | --------------- |
+| `subject`            | `ref`    | ✅       | Reference to the org.hypercerts.claim.activity or org.hypercerts.collection this board visualizes. |                 |
+| `config`             | `ref`    | ❌       | Visual configuration for a hyperboard's background, colors, and layout.                            |                 |
+| `contributorConfigs` | `ref[]`  | ❌       | Per-contributor configuration entries for this board.                                              | maxLength: 1000 |
+| `createdAt`          | `string` | ✅       | Client-declared timestamp when this record was originally created.                                 |                 |
 
 #### Defs
 

package/dist/exports.d.ts

@@ -4,7 +4,7 @@
  * ⚠️  DO NOT EDIT THIS FILE MANUALLY ⚠️
  *
  * This file is automatically generated by scripts/generate-exports.js
- * Generated: 2026-04-07T22:27:48.251Z
+ * Generated: 2026-04-08T16:56:41.853Z
  *
  * To regenerate this file, run:
  *   npm run gen-api

package/dist/generated/exports.d.ts

@@ -4,7 +4,7 @@
  * ⚠️  DO NOT EDIT THIS FILE MANUALLY ⚠️
  *
  * This file is automatically generated by scripts/generate-exports.js
- * Generated: 2026-04-07T22:27:48.251Z
+ * Generated: 2026-04-08T16:56:41.853Z
  *
  * To regenerate this file, run:
  *   npm run gen-api

package/dist/generated/lexicons.d.ts

@@ -548,7 +548,7 @@ export declare const schemaDict: {
                         readonly subject: {
                             readonly type: "ref";
                             readonly ref: "lex:com.atproto.repo.strongRef";
-                            readonly description: "Reference to the org.hypercerts.claim.activity or org.hypercerts.claim.collection this board visualizes.";
+                            readonly description: "Reference to the org.hypercerts.claim.activity or org.hypercerts.collection this board visualizes.";
                         };
                         readonly config: {
                             readonly type: "ref";
@@ -2853,7 +2853,7 @@ export declare const schemas: ({
                     readonly subject: {
                         readonly type: "ref";
                         readonly ref: "lex:com.atproto.repo.strongRef";
-                        readonly description: "Reference to the org.hypercerts.claim.activity or org.hypercerts.claim.collection this board visualizes.";
+                        readonly description: "Reference to the org.hypercerts.claim.activity or org.hypercerts.collection this board visualizes.";
                     };
                     readonly config: {
                         readonly type: "ref";

package/dist/index.cjs

@@ -628,7 +628,7 @@ const schemaDict = {
                         subject: {
                             type: 'ref',
                             ref: 'lex:com.atproto.repo.strongRef',
-                            description: 'Reference to the org.hypercerts.claim.activity or org.hypercerts.claim.collection this board visualizes.',
+                            description: 'Reference to the org.hypercerts.claim.activity or org.hypercerts.collection this board visualizes.',
                         },
                         config: {
                             type: 'ref',
@@ -3273,7 +3273,7 @@ var defs$x = {
 				subject: {
 					type: "ref",
 					ref: "com.atproto.repo.strongRef",
-					description: "Reference to the org.hypercerts.claim.activity or org.hypercerts.claim.collection this board visualizes."
+					description: "Reference to the org.hypercerts.claim.activity or org.hypercerts.collection this board visualizes."
 				},
 				config: {
 					type: "ref",
@@ -6602,7 +6602,7 @@ var facet = /*#__PURE__*/Object.freeze({
  * ⚠️  DO NOT EDIT THIS FILE MANUALLY ⚠️
  *
  * This file is automatically generated by scripts/generate-exports.js
- * Generated: 2026-04-07T22:27:48.251Z
+ * Generated: 2026-04-08T16:56:41.853Z
  *
  * To regenerate this file, run:
  *   npm run gen-api