Add org.hypercerts.claim.acknowledgement lexicon

.changeset/add-acknowledgement-lexicon.md

@@ -0,0 +1,5 @@
+---
+"@hypercerts-org/lexicon": minor
+---
+
+Add org.hypercerts.acknowledgement lexicon for tracking acknowledgements or consents.

ERD.puml

@@ -193,6 +193,18 @@ dataclass collection {
     !endif
 }
 
+
+' org.hypercerts.acknowledgement
+dataclass acknowledgement {
+    !if (SHOW_FIELDS == "true")
+    subjects[]
+    context
+    given
+    comment?
+    createdAt
+    !endif
+}
+
 ' org.hypercerts.claim.collection.project (sidecar)
 dataclass collectionProject {
     !if (SHOW_FIELDS == "true")
@@ -300,6 +312,11 @@ collection::items --> activity
 collection::items --> collection : "recursive\nnesting"
 collection ..|> collectionProject : "sidecar\n(same TID)"
 
+
+acknowledgement::subjects --> activity : "(subject)"
+acknowledgement::context --> collection : "(context)"
+note bottom of acknowledgement : "Subjects and context can reference\nany AT Protocol record type."
+
 activity::contributions -l--> contributor
 activity::rights --> rights
 activity::locations --> location

README.md

@@ -274,3 +274,26 @@ await createRecord({
 ```
 
 **Note**: The project sidecar is optional. Collections without this sidecar are simple groupings; collections with it are "projects" with rich documentation.
+
+### Example: Creating an Acknowledgement
+
+```typescript
+import { ACKNOWLEDGEMENT_NSID } from "@hypercerts-org/lexicon";
+
+const acknowledgementRecord = {
+  $type: ACKNOWLEDGEMENT_NSID,
+  subjects: [
+    {
+      uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc",
+      cid: "...",
+    },
+  ],
+  context: {
+    uri: "at://did:plc:bob/org.hypercerts.claim.collection/7x9def",
+    cid: "...",
+  },
+  given: true, // "consent granted"
+  comment: "Approved for inclusion in the Carbon Offset collection.",
+  createdAt: new Date().toISOString(),
+};
+```

lexicons/org/hypercerts/acknowledgement.json

@@ -0,0 +1,45 @@
+{
+  "lexicon": 1,
+  "id": "org.hypercerts.acknowledgement",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "Acknowledgement of inclusion/association between subjects and a context.",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["subjects", "context", "given", "createdAt"],
+        "properties": {
+          "subjects": {
+            "type": "array",
+            "description": "The records being acknowledged (e.g., activities).",
+            "items": {
+              "type": "ref",
+              "ref": "com.atproto.repo.strongRef"
+            },
+            "minLength": 1
+          },
+          "context": {
+            "type": "ref",
+            "ref": "com.atproto.repo.strongRef",
+            "description": "The target context (e.g. a collection) for the acknowledgement/consent."
+          },
+          "given": {
+            "type": "boolean",
+            "description": "Indicates whether acknowledgement is granted (true) or denied (false)."
+          },
+          "comment": {
+            "type": "string",
+            "description": "Optional comment providing additional details or reasoning.",
+            "maxLength": 1000
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "Client-declared timestamp when this record was originally created."
+          }
+        }
+      }
+    }
+  }
+}