@hypercerts-org/lexicon 0.10.0-beta.9 → 0.11.0

package/lexicons/app/certified/badge/definition.json

@@ -8,15 +8,25 @@
       "key": "tid",
       "record": {
         "type": "object",
-        "required": ["title", "badgeType", "icon", "createdAt"],
+        "required": ["title", "badgeType", "createdAt"],
         "properties": {
           "badgeType": {
             "type": "string",
-            "description": "Category of the badge (e.g. endorsement, participation, affiliation)."
+            "description": "Category of the badge. Values beyond the known set are permitted.",
+            "knownValues": [
+              "endorsement",
+              "verification",
+              "participation",
+              "certification",
+              "affiliation",
+              "recognition"
+            ],
+            "maxLength": 100
           },
           "title": {
             "type": "string",
-            "description": "Human-readable title of the badge."
+            "description": "Human-readable title of the badge.",
+            "maxLength": 256
           },
           "icon": {
             "type": "blob",
@@ -31,11 +41,14 @@
           },
           "description": {
             "type": "string",
-            "description": "Optional short statement describing what the badge represents."
+            "description": "Optional short statement describing what the badge represents.",
+            "maxLength": 5000,
+            "maxGraphemes": 500
           },
           "allowedIssuers": {
             "type": "array",
             "description": "Optional allowlist of DIDs allowed to issue this badge. If omitted, anyone may issue it.",
+            "maxLength": 100,
             "items": {
               "type": "ref",
               "ref": "app.certified.defs#did"

package/lexicons/app/certified/badge/response.json

@@ -12,17 +12,18 @@
         "properties": {
           "badgeAward": {
             "type": "ref",
-            "ref": "app.certified.badge.award",
-            "description": "Reference to the badge award."
+            "ref": "com.atproto.repo.strongRef",
+            "description": "Strong reference to the badge award being responded to. The record referenced must conform with the lexicon app.certified.badge.award."
           },
           "response": {
             "type": "string",
-            "enum": ["accepted", "rejected"],
+            "knownValues": ["accepted", "rejected"],
             "description": "The recipient’s response for the badge (accepted or rejected)."
           },
           "weight": {
             "type": "string",
-            "description": "Optional relative weight for accepted badges, assigned by the recipient."
+            "description": "Optional relative weight for accepted badges, assigned by the recipient.",
+            "maxLength": 50
           },
           "createdAt": {
             "type": "string",

package/lexicons/app/certified/defs.json

@@ -4,9 +4,17 @@
   "description": "Common type definitions used across certified protocols.",
   "defs": {
     "did": {
-      "type": "string",
-      "format": "did",
-      "description": "A Decentralized Identifier (DID) string."
+      "type": "object",
+      "description": "A Decentralized Identifier (DID) string.",
+      "required": ["did"],
+      "properties": {
+        "did": {
+          "type": "string",
+          "format": "did",
+          "description": "The DID string value.",
+          "maxLength": 256
+        }
+      }
     }
   }
 }

package/lexicons/app/certified/link/evm.json

@@ -0,0 +1,88 @@
+{
+  "lexicon": 1,
+  "id": "app.certified.link.evm",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "A verifiable link between an ATProto DID and an EVM wallet address, proven via a cryptographic signature. Currently supports EOA wallets via EIP-712 typed data signatures; the proof field is an open union to allow future signature methods.",
+      "key": "any",
+      "record": {
+        "type": "object",
+        "required": ["address", "proof", "createdAt"],
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "EVM wallet address (0x-prefixed, with EIP-55 checksum recommended).",
+            "minLength": 42,
+            "maxLength": 42
+          },
+          "proof": {
+            "type": "union",
+            "refs": ["#eip712Proof"],
+            "description": "Cryptographic proof of wallet ownership. The union is open to allow future proof methods (e.g. ERC-1271, ERC-6492). Each variant bundles its signature with the corresponding message format."
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "Client-declared timestamp when this record was originally created."
+          }
+        }
+      }
+    },
+    "eip712Proof": {
+      "type": "object",
+      "description": "EOA wallet ownership proof via EIP-712 typed data signature. Contains both the structured message that was signed and the resulting signature.",
+      "required": ["signature", "message"],
+      "properties": {
+        "signature": {
+          "type": "string",
+          "description": "ECDSA signature over the EIP-712 hash (hex-encoded with 0x prefix, 64 or 65 bytes).",
+          "minLength": 130,
+          "maxLength": 132
+        },
+        "message": {
+          "type": "ref",
+          "ref": "#eip712Message",
+          "description": "The EIP-712 structured message fields that were signed."
+        }
+      }
+    },
+    "eip712Message": {
+      "type": "object",
+      "description": "The EIP-712 typed data message that was signed by the wallet. Contains the fields binding an ATProto DID to an EVM address on a specific chain.",
+      "required": ["did", "evmAddress", "chainId", "timestamp", "nonce"],
+      "properties": {
+        "did": {
+          "type": "string",
+          "format": "did",
+          "description": "The ATProto DID being linked to the EVM address.",
+          "maxLength": 256
+        },
+        "evmAddress": {
+          "type": "string",
+          "description": "The EVM wallet address (must match the top-level address field).",
+          "minLength": 42,
+          "maxLength": 42
+        },
+        "chainId": {
+          "type": "string",
+          "description": "EVM chain ID as string (bigint serialized). Identifies which chain was used for signing; for EOA wallets the identity link applies across all EVM-compatible chains.",
+          "minLength": 1,
+          "maxLength": 78
+        },
+        "timestamp": {
+          "type": "string",
+          "description": "Unix timestamp when the attestation was created (bigint serialized).",
+          "minLength": 1,
+          "maxLength": 78
+        },
+        "nonce": {
+          "type": "string",
+          "description": "Replay-protection nonce (bigint serialized).",
+          "minLength": 1,
+          "maxLength": 78
+        }
+      }
+    }
+  }
+}

package/lexicons/app/certified/location.json

@@ -29,27 +29,37 @@
           },
           "locationType": {
             "type": "string",
-            "description": "An identifier for the format of the location data (e.g., coordinate-decimal, geojson-point)",
-            "knownValues": ["coordinate-decimal", "geojson-point"],
+            "description": "An identifier for the format of the location data (e.g., coordinate-decimal, geojson-point). See the Location Protocol spec for the full registry: https://spec.decentralizedgeo.org/specification/location-types/#location-type-registry",
+            "knownValues": [
+              "coordinate-decimal",
+              "geojson-point",
+              "geojson",
+              "h3",
+              "geohash",
+              "wkt",
+              "address",
+              "scaledCoordinates"
+            ],
             "maxLength": 20
           },
           "location": {
             "type": "union",
             "refs": [
               "org.hypercerts.defs#uri",
-              "org.hypercerts.defs#smallBlob"
+              "org.hypercerts.defs#smallBlob",
+              "#string"
             ],
-            "description": "The location of where the work was performed as a URI or blob."
+            "description": "The location of where the work was performed as a URI, blob, or inline string."
           },
           "name": {
             "type": "string",
-            "description": "Optional name for this location",
+            "description": "Human-readable name for this location (e.g. 'Golden Gate Park', 'San Francisco Bay Area')",
             "maxLength": 1000,
             "maxGraphemes": 100
           },
           "description": {
             "type": "string",
-            "description": "Optional description for this location",
+            "description": "Additional context about this location, such as its significance to the work or specific boundaries",
             "maxLength": 2000,
             "maxGraphemes": 500
           },
@@ -60,6 +70,19 @@
           }
         }
       }
+    },
+    "string": {
+      "type": "object",
+      "required": ["string"],
+      "description": "A location represented as a string, e.g. coordinates or a small GeoJSON string.",
+      "properties": {
+        "string": {
+          "type": "string",
+          "description": "The location string value",
+          "maxLength": 10000,
+          "maxGraphemes": 1000
+        }
+      }
     }
   }
 }

package/lexicons/org/hyperboards/board.json

@@ -0,0 +1,152 @@
+{
+  "lexicon": 1,
+  "id": "org.hyperboards.board",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "Configuration record for a hyperboard, wrapping an underlying activity or collection with visual presentation settings. Stored in the creator's PDS.",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["subject", "createdAt"],
+        "properties": {
+          "subject": {
+            "type": "ref",
+            "ref": "com.atproto.repo.strongRef",
+            "description": "Reference to the org.hypercerts.claim.activity or org.hypercerts.claim.collection this board visualizes."
+          },
+          "config": {
+            "type": "ref",
+            "ref": "#boardConfig",
+            "description": "Board-level visual configuration (background, colors, aspect ratio)."
+          },
+          "contributorConfigs": {
+            "type": "array",
+            "description": "Per-contributor configuration entries for this board.",
+            "maxLength": 1000,
+            "items": {
+              "type": "ref",
+              "ref": "#contributorConfig"
+            }
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "Client-declared timestamp when this record was originally created."
+          }
+        }
+      }
+    },
+    "boardConfig": {
+      "type": "object",
+      "description": "Visual configuration for a hyperboard's background, colors, and layout.",
+      "properties": {
+        "backgroundType": {
+          "type": "string",
+          "description": "Type of background content.",
+          "knownValues": ["image", "iframe"],
+          "maxLength": 10
+        },
+        "backgroundImage": {
+          "type": "union",
+          "refs": ["org.hypercerts.defs#uri", "org.hypercerts.defs#smallImage"],
+          "description": "Background image as a URI or image blob."
+        },
+        "backgroundIframeUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "URI of the background iframe.",
+          "maxLength": 2048
+        },
+        "backgroundGrayscale": {
+          "type": "boolean",
+          "description": "Whether the background is rendered in grayscale. Default: true."
+        },
+        "backgroundOpacity": {
+          "type": "integer",
+          "description": "Background opacity as a percentage (0–100).",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "backgroundColor": {
+          "type": "string",
+          "description": "Background color as a hex string (e.g. '#ffffff').",
+          "maxLength": 20
+        },
+        "borderColor": {
+          "type": "string",
+          "description": "Border color as a hex string (e.g. '#000000').",
+          "maxLength": 20
+        },
+        "grayscaleImages": {
+          "type": "boolean",
+          "description": "Whether contributor images are rendered in grayscale. Default: false."
+        },
+        "imageShape": {
+          "type": "string",
+          "description": "Shape used to crop contributor images on this board.",
+          "knownValues": ["circular", "square"],
+          "maxLength": 20
+        },
+        "aspectRatio": {
+          "type": "string",
+          "description": "Display aspect ratio of the board.",
+          "knownValues": ["16:9", "4:3", "1:1"],
+          "maxLength": 10
+        }
+      }
+    },
+    "contributorConfig": {
+      "type": "object",
+      "description": "Configuration for a specific contributor within a board. Values serve as fallbacks when the contributor has not defined them on their profile. It can also be used to override contributor settings on this board without changing their global profile.",
+      "required": ["contributor"],
+      "properties": {
+        "contributor": {
+          "type": "union",
+          "refs": [
+            "com.atproto.repo.strongRef",
+            "org.hypercerts.claim.activity#contributorIdentity"
+          ],
+          "description": "Identifies the contributor being styled. A strong reference to an org.hypercerts.claim.contributorInformation record, or a contributorIdentity (DID or identifier string) for contributors without a dedicated record."
+        },
+        "override": {
+          "type": "boolean",
+          "description": "When true, these values take precedence over the contributor's own profile and display settings. When false or omitted, they are only used as fallbacks if the contributor has not set their own settings."
+        },
+        "displayName": {
+          "type": "string",
+          "description": "Display name for this contributor on this board.",
+          "maxLength": 640,
+          "maxGraphemes": 64
+        },
+        "image": {
+          "type": "union",
+          "refs": ["org.hypercerts.defs#uri", "org.hypercerts.defs#smallImage"],
+          "description": "Avatar or face image for this contributor on this board, as a URI or image blob."
+        },
+        "video": {
+          "type": "union",
+          "refs": ["org.hypercerts.defs#uri", "org.hypercerts.defs#smallVideo"],
+          "description": "Video for this contributor, as a URI (embed/direct link) or uploaded video blob."
+        },
+        "hoverImage": {
+          "type": "union",
+          "refs": ["org.hypercerts.defs#uri", "org.hypercerts.defs#smallImage"],
+          "description": "Image overlay shown when hovering over this contributor, as a URI or image blob."
+        },
+        "hoverIframeUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "Iframe overlay shown when hovering over this contributor.",
+          "maxLength": 2048
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Click-through link URL for this contributor.",
+          "maxLength": 2048
+        }
+      }
+    }
+  }
+}

package/lexicons/org/hyperboards/displayProfile.json

@@ -0,0 +1,64 @@
+{
+  "lexicon": 1,
+  "id": "org.hyperboards.displayProfile",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "User-declared visual presentation defaults for how a contributor appears on hyperboards. Stored in the contributor's own PDS and reusable across multiple boards.",
+      "key": "literal:self",
+      "record": {
+        "type": "object",
+        "required": ["createdAt"],
+        "properties": {
+          "displayName": {
+            "type": "string",
+            "description": "Display name override for this user on hyperboards.",
+            "maxLength": 640,
+            "maxGraphemes": 64
+          },
+          "image": {
+            "type": "union",
+            "refs": [
+              "org.hypercerts.defs#uri",
+              "org.hypercerts.defs#smallImage"
+            ],
+            "description": "Avatar or face image override for this user on hyperboards, as a URI or image blob."
+          },
+          "video": {
+            "type": "union",
+            "refs": [
+              "org.hypercerts.defs#uri",
+              "org.hypercerts.defs#smallVideo"
+            ],
+            "description": "Default video for this user across boards, as a URI (embed/direct link) or uploaded video blob."
+          },
+          "hoverImage": {
+            "type": "union",
+            "refs": [
+              "org.hypercerts.defs#uri",
+              "org.hypercerts.defs#smallImage"
+            ],
+            "description": "Default hover image for this user across boards, as a URI or image blob."
+          },
+          "hoverIframeUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "Default hover iframe URL for this user across boards.",
+            "maxLength": 2048
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Default click-through link URL for this user across boards.",
+            "maxLength": 2048
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "Client-declared timestamp when this record was originally created."
+          }
+        }
+      }
+    }
+  }
+}

package/lexicons/org/hypercerts/claim/activity.json

@@ -12,7 +12,7 @@
         "properties": {
           "title": {
             "type": "string",
-            "description": "Title of the hypercert.",
+            "description": "Display title summarizing the impact work (e.g. 'Reforestation in Amazon Basin 2024')",
             "maxLength": 256
           },
           "shortDescription": {
@@ -30,18 +30,13 @@
             }
           },
           "description": {
-            "type": "string",
-            "description": "Optional longer description of this activity claim, including context or interpretation. Rich text annotations may be provided via `descriptionFacets`.",
-            "maxLength": 30000,
-            "maxGraphemes": 3000
-          },
-          "descriptionFacets": {
-            "type": "array",
-            "description": "Rich text annotations for `description` (mentions, URLs, hashtags, etc).",
-            "items": {
-              "type": "ref",
-              "ref": "app.bsky.richtext.facet"
-            }
+            "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",
@@ -51,15 +46,18 @@
             ],
             "description": "The hypercert visual representation as a URI or image blob."
           },
+          "contributors": {
+            "type": "array",
+            "description": "An array of contributor objects, each containing contributor information, weight, and contribution details.",
+            "items": {
+              "type": "ref",
+              "ref": "#contributor"
+            }
+          },
           "workScope": {
             "type": "union",
-            "refs": [
-              "org.hypercerts.defs#workScopeAll",
-              "org.hypercerts.defs#workScopeAny",
-              "org.hypercerts.defs#workScopeNot",
-              "org.hypercerts.defs#workScopeAtom"
-            ],
-            "description": "Work scope logic expression using boolean operators (all/any/not) and atomic scope references."
+            "refs": ["org.hypercerts.workscope.cel", "#workScopeString"],
+            "description": "Work scope definition. A CEL expression for structured, machine-evaluable scopes or a free-form string for simple and legacy scopes."
           },
           "startDate": {
             "type": "string",
@@ -71,12 +69,13 @@
             "format": "datetime",
             "description": "When the work ended"
           },
-          "contributors": {
+          "locations": {
             "type": "array",
-            "description": "An array of contributor objects, each containing contributor information, weight, and contribution details.",
+            "description": "An array of strong references to the location where activity was performed. The record referenced must conform with the lexicon app.certified.location.",
+            "maxLength": 1000,
             "items": {
               "type": "ref",
-              "ref": "#contributor"
+              "ref": "com.atproto.repo.strongRef"
             }
           },
           "rights": {
@@ -84,14 +83,6 @@
             "ref": "com.atproto.repo.strongRef",
             "description": "A strong reference to the rights that this hypercert has. The record referenced must conform with the lexicon org.hypercerts.claim.rights."
           },
-          "locations": {
-            "type": "array",
-            "description": "An array of strong references to the location where activity was performed. The record referenced must conform with the lexicon app.certified.location.",
-            "items": {
-              "type": "ref",
-              "ref": "com.atproto.repo.strongRef"
-            }
-          },
           "createdAt": {
             "type": "string",
             "format": "datetime",
@@ -102,33 +93,64 @@
     },
     "contributor": {
       "type": "object",
+      "description": "A contributor to the activity, with identity, weight, and contribution details.",
       "required": ["contributorIdentity"],
       "properties": {
         "contributorIdentity": {
           "type": "union",
           "refs": ["#contributorIdentity", "com.atproto.repo.strongRef"],
-          "description": "Contributor identity as a string (DID or identifier) via org.hypercerts.claim.activity#contributorIdentity, or a strong reference to a contributor information record."
+          "description": "Inline contributor identity object with an identity string (DID or identifier) via org.hypercerts.claim.activity#contributorIdentity, or a strong reference to a contributor information record. The record referenced must conform with the lexicon org.hypercerts.claim.contributorInformation."
         },
         "contributionWeight": {
           "type": "string",
-          "description": "The relative weight/importance of this contribution (stored as a string to avoid float precision issues). Must be a positive numeric value. Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed."
+          "description": "The relative weight/importance of this contribution (stored as a string to avoid float precision issues). Must be a positive numeric value. Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed.",
+          "maxLength": 100
         },
         "contributionDetails": {
           "type": "union",
           "refs": ["#contributorRole", "com.atproto.repo.strongRef"],
-          "description": "Contribution details as a string via org.hypercerts.claim.activity#contributorRole, or a strong reference to a contribution details record."
+          "description": "Inline contribution role object with a role string via org.hypercerts.claim.activity#contributorRole, or a strong reference to a contribution details record. The record referenced must conform with the lexicon org.hypercerts.claim.contribution."
         }
       }
     },
     "contributorIdentity": {
-      "type": "string",
-      "description": "Contributor information as a string (DID or identifier)."
+      "type": "object",
+      "description": "Contributor information as a string (DID or identifier).",
+      "required": ["identity"],
+      "properties": {
+        "identity": {
+          "type": "string",
+          "description": "The contributor identity string (DID or identifier).",
+          "maxLength": 1000,
+          "maxGraphemes": 100
+        }
+      }
     },
     "contributorRole": {
-      "type": "string",
+      "type": "object",
       "description": "Contribution details as a string.",
-      "maxLength": 10000,
-      "maxGraphemes": 1000
+      "required": ["role"],
+      "properties": {
+        "role": {
+          "type": "string",
+          "description": "The contribution role or details.",
+          "maxLength": 1000,
+          "maxGraphemes": 100
+        }
+      }
+    },
+    "workScopeString": {
+      "type": "object",
+      "description": "A free-form string describing the work scope for simple or legacy scopes.",
+      "required": ["scope"],
+      "properties": {
+        "scope": {
+          "type": "string",
+          "description": "The work scope description string.",
+          "maxLength": 1000,
+          "maxGraphemes": 100
+        }
+      }
     }
   }
 }

package/lexicons/org/hypercerts/claim/{contributionDetails.json → contribution.json}

@@ -1,6 +1,6 @@
 {
   "lexicon": 1,
-  "id": "org.hypercerts.claim.contributionDetails",
+  "id": "org.hypercerts.claim.contribution",
   "defs": {
     "main": {
       "type": "record",
@@ -17,19 +17,19 @@
           },
           "contributionDescription": {
             "type": "string",
-            "description": "What the contribution concretely was.",
+            "description": "Description of what the contribution concretely involved.",
             "maxLength": 10000,
             "maxGraphemes": 1000
           },
           "startDate": {
             "type": "string",
             "format": "datetime",
-            "description": "When this contribution started. This should be a subset of the hypercert timeframe."
+            "description": "When this contribution started. Should fall within the parent hypercert's timeframe."
           },
           "endDate": {
             "type": "string",
             "format": "datetime",
-            "description": "When this contribution finished. This should be a subset of the hypercert timeframe."
+            "description": "When this contribution finished. Should fall within the parent hypercert's timeframe."
           },
           "createdAt": {
             "type": "string",