diff --git a/.changeset/add-acknowledgement-lexicon.md b/.changeset/add-acknowledgement-lexicon.md new file mode 100644 index 0000000..78f43cd --- /dev/null +++ b/.changeset/add-acknowledgement-lexicon.md @@ -0,0 +1,5 @@ +--- +"@hypercerts-org/lexicon": minor +--- + +Add org.hypercerts.acknowledgement lexicon for tracking acknowledgements or consents. diff --git a/ERD.puml b/ERD.puml index b7bb0ba..9bdc301 100644 --- a/ERD.puml +++ b/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 diff --git a/README.md b/README.md index 93fa016..c9a5261 100644 --- a/README.md +++ b/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(), +}; +``` diff --git a/lexicons/org/hypercerts/acknowledgement.json b/lexicons/org/hypercerts/acknowledgement.json new file mode 100644 index 0000000..aab6045 --- /dev/null +++ b/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." + } + } + } + } + } +}