Merge pull request #181 from hypercerts-org/fix/description-union-type

fix: widen description fields from Leaflet ref to union type

Author: s-adamantine

.changeset/description-union-type.md

@@ -0,0 +1,7 @@
+---
+"@hypercerts-org/lexicon": minor
+---
+
+Widen description fields on activity, collection, and attachment from a bare Leaflet ref to a union of inline descriptionString and Leaflet linearDocument, with a shared def in org.hypercerts.defs.
+
+This is technically a breaking schema change (ref → union), but not breaking for most published records, as they already include a `$type` discriminator on the description object, so existing data validates against the union without modification.

ERD.puml

@@ -235,7 +235,7 @@ dataclass collection {
     type?
     title
     shortDescription?
-    description? (Leaflet ref)
+    description?
     items[]?
     location?
     createdAt

SCHEMAS.md

@@ -30,9 +30,13 @@
             }
           },
           "description": {
-            "type": "ref",
-            "ref": "pub.leaflet.pages.linearDocument#main",
-            "description": "Rich-text description, represented as a Leaflet linear document."
+            "type": "union",
+            "refs": [
+              "org.hypercerts.defs#descriptionString",
+              "pub.leaflet.pages.linearDocument",
+              "com.atproto.repo.strongRef"
+            ],
+            "description": "Long-form description of the activity. An inline string for plain text or markdown, a Leaflet linear document for rich-text content, or a strong reference to an external description record."
           },
           "image": {
             "type": "union",

lexicons/org/hypercerts/claim/activity.json

@@ -37,9 +37,13 @@
             }
           },
           "description": {
-            "type": "ref",
-            "ref": "pub.leaflet.pages.linearDocument#main",
-            "description": "Rich-text description, represented as a Leaflet linear document."
+            "type": "union",
+            "refs": [
+              "org.hypercerts.defs#descriptionString",
+              "pub.leaflet.pages.linearDocument",
+              "com.atproto.repo.strongRef"
+            ],
+            "description": "Long-form description of the collection. An inline string for plain text or markdown, a Leaflet linear document for rich-text content, or a strong reference to an external description record."
           },
           "avatar": {
             "type": "union",

lexicons/org/hypercerts/collection.json

@@ -63,9 +63,13 @@
             }
           },
           "description": {
-            "type": "ref",
-            "ref": "pub.leaflet.pages.linearDocument#main",
-            "description": "Rich-text description, represented as a Leaflet linear document."
+            "type": "union",
+            "refs": [
+              "org.hypercerts.defs#descriptionString",
+              "pub.leaflet.pages.linearDocument",
+              "com.atproto.repo.strongRef"
+            ],
+            "description": "Long-form description of the attachment. An inline string for plain text or markdown, a Leaflet linear document for rich-text content, or a strong reference to an external description record."
           },
           "location": {
             "type": "ref",

lexicons/org/hypercerts/context/attachment.json

@@ -3,6 +3,27 @@
   "id": "org.hypercerts.defs",
   "description": "Common type definitions used across all Hypercerts protocols.",
   "defs": {
+    "descriptionString": {
+      "type": "object",
+      "description": "An inline long-form description as plain text or markdown, with optional rich-text annotations.",
+      "required": ["value"],
+      "properties": {
+        "value": {
+          "type": "string",
+          "description": "The description text (plain text or markdown).",
+          "maxLength": 250000,
+          "maxGraphemes": 25000
+        },
+        "facets": {
+          "type": "array",
+          "description": "Rich text annotations for the description (mentions, URLs, hashtags, etc).",
+          "items": {
+            "type": "ref",
+            "ref": "app.bsky.richtext.facet"
+          }
+        }
+      }
+    },
     "uri": {
       "type": "object",
       "required": ["uri"],