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

package/SCHEMAS.md

@@ -15,152 +15,243 @@ Hypercerts-specific lexicons for tracking impact work and claims.
 
 #### Properties
 
-| Property                 | Type     | Required | Description                                                                                                                                             | Comments                             |
-| ------------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| `title`                  | `string` | ✅       | Title of the hypercert.                                                                                                                                 | maxLength: 256                       |
-| `shortDescription`       | `string` | ✅       | Short summary of this activity claim, suitable for previews and list views. Rich text annotations may be provided via `shortDescriptionFacets`.         | maxLength: 3000, maxGraphemes: 300   |
-| `shortDescriptionFacets` | `ref`    | ❌       | Rich text annotations for `shortDescription` (mentions, URLs, hashtags, etc).                                                                           |                                      |
-| `description`            | `string` | ❌       | Optional longer description of this activity claim, including context or interpretation. Rich text annotations may be provided via `descriptionFacets`. | maxLength: 30000, maxGraphemes: 3000 |
-| `descriptionFacets`      | `ref`    | ❌       | Rich text annotations for `description` (mentions, URLs, hashtags, etc).                                                                                |                                      |
-| `image`                  | `union`  | ❌       | The hypercert visual representation as a URI or image blob.                                                                                             |                                      |
-| `workScope`              | `union`  | ❌       | Work scope logic expression using boolean operators (all/any/not) and atomic scope references.                                                          |                                      |
-| `startDate`              | `string` | ❌       | When the work began                                                                                                                                     |                                      |
-| `endDate`                | `string` | ❌       | When the work ended                                                                                                                                     |                                      |
-| `contributors`           | `ref`    | ❌       | An array of contributor objects, each containing contributor information, weight, and contribution details.                                             |                                      |
-| `rights`                 | `ref`    | ❌       | A strong reference to the rights that this hypercert has. The record referenced must conform with the lexicon org.hypercerts.claim.rights.              |                                      |
-| `locations`              | `ref`    | ❌       | An array of strong references to the location where activity was performed. The record referenced must conform with the lexicon app.certified.location. |                                      |
-| `createdAt`              | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                                       |                                      |
+| Property                 | Type     | Required | Description                                                                                                                                                                                   | Comments                           |
+| ------------------------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| `title`                  | `string` | ✅       | Display title summarizing the impact work (e.g. 'Reforestation in Amazon Basin 2024')                                                                                                         | maxLength: 256                     |
+| `shortDescription`       | `string` | ✅       | Short summary of this activity claim, suitable for previews and list views. Rich text annotations may be provided via `shortDescriptionFacets`.                                               | maxLength: 3000, maxGraphemes: 300 |
+| `shortDescriptionFacets` | `ref[]`  | ❌       | Rich text annotations for `shortDescription` (mentions, URLs, hashtags, etc).                                                                                                                 |                                    |
+| `description`            | `union`  | ❌       | 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`                  | `union`  | ❌       | The hypercert visual representation as a URI or image blob.                                                                                                                                   |                                    |
+| `contributors`           | `ref[]`  | ❌       | An array of contributor objects, each containing contributor information, weight, and contribution details.                                                                                   |                                    |
+| `workScope`              | `union`  | ❌       | Work scope definition. A CEL expression for structured, machine-evaluable scopes or a free-form string for simple and legacy scopes.                                                          |                                    |
+| `startDate`              | `string` | ❌       | When the work began                                                                                                                                                                           |                                    |
+| `endDate`                | `string` | ❌       | When the work ended                                                                                                                                                                           |                                    |
+| `locations`              | `ref[]`  | ❌       | 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                    |
+| `rights`                 | `ref`    | ❌       | A strong reference to the rights that this hypercert has. The record referenced must conform with the lexicon org.hypercerts.claim.rights.                                                    |                                    |
+| `createdAt`              | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                                                                             |                                    |
 
 #### Defs
 
-##### contributor
+##### `org.hypercerts.claim.activity#contributor`
 
-| Property              | Type     | Required | Description                                                                                                                                                                                                                                                        |
-| --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `contributorIdentity` | `union`  | ✅       | Contributor identity as a string (DID or identifier) via org.hypercerts.claim.activity#contributorIdentity, or a strong reference to a contributor information record.                                                                                             |
-| `contributionWeight`  | `string` | ❌       | 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. |
-| `contributionDetails` | `union`  | ❌       | Contribution details as a string via org.hypercerts.claim.activity#contributorRole, or a strong reference to a contribution details record.                                                                                                                        |
+A contributor to the activity, with identity, weight, and contribution details.
+
+| Property              | Type     | Required | Description                                                                                                                                                                                                                                                                                       |
+| --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contributorIdentity` | `union`  | ✅       | 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`  | `string` | ❌       | 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.                                |
+| `contributionDetails` | `union`  | ❌       | 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.                                              |
+
+##### `org.hypercerts.claim.activity#contributorIdentity`
+
+Contributor information as a string (DID or identifier).
+
+| Property   | Type     | Required | Description                                          |
+| ---------- | -------- | -------- | ---------------------------------------------------- |
+| `identity` | `string` | ✅       | The contributor identity string (DID or identifier). |
+
+##### `org.hypercerts.claim.activity#contributorRole`
+
+Contribution details as a string.
+
+| Property | Type     | Required | Description                       |
+| -------- | -------- | -------- | --------------------------------- |
+| `role`   | `string` | ✅       | The contribution role or details. |
+
+##### `org.hypercerts.claim.activity#workScopeString`
+
+A free-form string describing the work scope for simple or legacy scopes.
+
+| Property | Type     | Required | Description                        |
+| -------- | -------- | -------- | ---------------------------------- |
+| `scope`  | `string` | ✅       | The work scope description string. |
 
 ---
 
-### `org.hypercerts.claim.evaluation`
+### `org.hypercerts.claim.contribution`
 
-**Description:** An evaluation of a hypercert record (e.g. an activity and its impact).
+**Description:** Details about a specific contribution including role, description, and timeframe.
+
+**Key:** `tid`
+
+#### Properties
+
+| Property                  | Type     | Required | Description                                                                           | Comments                             |
+| ------------------------- | -------- | -------- | ------------------------------------------------------------------------------------- | ------------------------------------ |
+| `role`                    | `string` | ❌       | Role or title of the contributor.                                                     | maxLength: 100                       |
+| `contributionDescription` | `string` | ❌       | Description of what the contribution concretely involved.                             | maxLength: 10000, maxGraphemes: 1000 |
+| `startDate`               | `string` | ❌       | When this contribution started. Should fall within the parent hypercert's timeframe.  |                                      |
+| `endDate`                 | `string` | ❌       | When this contribution finished. Should fall within the parent hypercert's timeframe. |                                      |
+| `createdAt`               | `string` | ✅       | Client-declared timestamp when this record was originally created.                    |                                      |
+
+---
+
+### `org.hypercerts.claim.contributorInformation`
+
+**Description:** Contributor information including identifier, display name, and image.
+
+**Key:** `tid`
+
+#### Properties
+
+| Property      | Type     | Required | Description                                                        | Comments        |
+| ------------- | -------- | -------- | ------------------------------------------------------------------ | --------------- |
+| `identifier`  | `string` | ❌       | DID (did:plc:...) or URI to a social profile of the contributor.   | maxLength: 2048 |
+| `displayName` | `string` | ❌       | Human-readable name for the contributor as it should appear in UI. | maxLength: 100  |
+| `image`       | `union`  | ❌       | The contributor visual representation as a URI or image blob.      |                 |
+| `createdAt`   | `string` | ✅       | Client-declared timestamp when this record was originally created. |                 |
+
+---
+
+### `org.hypercerts.claim.rights`
+
+**Description:** Describes the rights that a contributor and/or an owner has, such as whether the hypercert can be sold, transferred, and under what conditions.
 
 **Key:** `tid`
 
 #### Properties
 
-| Property       | Type     | Required | Description                                                                                                                                                          | Comments                            |
-| -------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `subject`      | `ref`    | ❌       | A strong reference to what is being evaluated. (e.g activity, measurement, contribution, etc.)                                                                       |                                     |
-| `evaluators`   | `ref`    | ✅       | DIDs of the evaluators                                                                                                                                               | maxLength: 1000                     |
-| `content`      | `union`  | ❌       | Evaluation data (URIs or blobs) containing detailed reports or methodology                                                                                           | maxLength: 100                      |
-| `measurements` | `ref`    | ❌       | Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.claim.measurement | maxLength: 100                      |
-| `summary`      | `string` | ✅       | Brief evaluation summary                                                                                                                                             | maxLength: 5000, maxGraphemes: 1000 |
-| `score`        | `ref`    | ❌       | Overall score for an evaluation on a numeric scale.                                                                                                                  |                                     |
-| `location`     | `ref`    | ❌       | An optional reference for georeferenced evaluations. The record referenced must conform with the lexicon app.certified.location.                                     |                                     |
-| `createdAt`    | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                                                    |                                     |
+| Property            | Type     | Required | Description                                                                                            | Comments                             |
+| ------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------ |
+| `rightsName`        | `string` | ✅       | Human-readable name for these rights (e.g. 'All Rights Reserved', 'CC BY-SA 4.0')                      | maxLength: 100                       |
+| `rightsType`        | `string` | ✅       | Short identifier code for this rights type (e.g. 'ARR', 'CC-BY-SA') to facilitate filtering and search | maxLength: 10                        |
+| `rightsDescription` | `string` | ✅       | Detailed explanation of the rights holders' permissions, restrictions, and conditions                  | maxLength: 10000, maxGraphemes: 1000 |
+| `attachment`        | `union`  | ❌       | An attachment to define the rights further, e.g. a legal document.                                     |                                      |
+| `createdAt`         | `string` | ✅       | Client-declared timestamp when this record was originally created                                      |                                      |
+
+---
+
+### `org.hypercerts.collection`
+
+**Description:** A collection/group of items (activities and/or other collections). Collections support recursive nesting.
+
+**Key:** `tid`
+
+#### Properties
+
+| Property                 | Type     | Required | Description                                                                                                                                                                                     | Comments                                                                    |
+| ------------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `type`                   | `string` | ❌       | The type of this collection. Values beyond the known set are permitted.                                                                                                                         | maxLength: 64, Known values: `favorites`, `project`, `portfolio`, `program` |
+| `title`                  | `string` | ✅       | Display name for this collection (e.g. 'Q1 2025 Impact Projects')                                                                                                                               | maxLength: 800, maxGraphemes: 80                                            |
+| `shortDescription`       | `string` | ❌       | Short summary of this collection, suitable for previews and list views. Rich text annotations may be provided via `shortDescriptionFacets`.                                                     | maxLength: 3000, maxGraphemes: 300                                          |
+| `shortDescriptionFacets` | `ref[]`  | ❌       | Rich text annotations for `shortDescription` (mentions, URLs, hashtags, etc).                                                                                                                   |                                                                             |
+| `description`            | `union`  | ❌       | 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`                 | `union`  | ❌       | The collection's avatar/profile image as a URI or image blob.                                                                                                                                   |                                                                             |
+| `banner`                 | `union`  | ❌       | Larger horizontal image to display behind the collection view.                                                                                                                                  |                                                                             |
+| `items`                  | `ref[]`  | ❌       | Array of items in this collection with optional weights.                                                                                                                                        | maxLength: 1000                                                             |
+| `location`               | `ref`    | ❌       | A strong reference to the location where this collection's activities were performed. The record referenced must conform with the lexicon app.certified.location.                               |                                                                             |
+| `createdAt`              | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                                                                               |                                                                             |
 
 #### Defs
 
-##### score
+##### `org.hypercerts.collection#item`
 
-| Property | Type      | Required | Description                                  |
-| -------- | --------- | -------- | -------------------------------------------- |
-| `min`    | `integer` | ✅       | Minimum value of the scale, e.g. 0 or 1.     |
-| `max`    | `integer` | ✅       | Maximum value of the scale, e.g. 5 or 10.    |
-| `value`  | `integer` | ✅       | Score within the inclusive range [min, max]. |
+An item in a collection, with an identifier and optional weight.
+
+| Property         | Type     | Required | Description                                                                                                                                                                                     |
+| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `itemIdentifier` | `ref`    | ✅       | Strong reference to an item in this collection. Items can be activities (org.hypercerts.claim.activity) and/or other collections (org.hypercerts.collection).                                   |
+| `itemWeight`     | `string` | ❌       | Optional weight for this item (positive numeric value stored as string). Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed. |
 
 ---
 
-### `org.hypercerts.claim.evidence`
+### `org.hypercerts.context.acknowledgement`
 
-**Description:** A piece of evidence related to a hypercert record (e.g. an activity, project, claim, or evaluation). Evidence may support, clarify, or challenge the referenced subject.
+**Description:** Acknowledges a record (subject) or its relationship in a context. Created in the acknowledging actor's repo to form a bidirectional link. Examples: a contributor acknowledging inclusion in an activity, an activity owner acknowledging inclusion in a collection, or a record owner acknowledging an evaluation.
 
 **Key:** `tid`
 
 #### Properties
 
-| Property           | Type     | Required | Description                                                                                                               | Comments                                            |
-| ------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
-| `subject`          | `ref`    | ❌       | A strong reference to the record this evidence relates to (e.g. an activity, project, claim, or evaluation).              |                                                     |
-| `content`          | `union`  | ✅       | A piece of evidence (URI or blob) related to the subject record; it may support, clarify, or challenge a hypercert claim. |                                                     |
-| `title`            | `string` | ✅       | Title to describe the nature of the evidence.                                                                             | maxLength: 256                                      |
-| `shortDescription` | `string` | ❌       | Short description explaining what this evidence shows.                                                                    | maxLength: 3000, maxGraphemes: 300                  |
-| `description`      | `string` | ❌       | Longer description describing the evidence in more detail.                                                                | maxLength: 30000, maxGraphemes: 3000                |
-| `relationType`     | `string` | ❌       | How this evidence relates to the subject.                                                                                 | Known values: `supports`, `challenges`, `clarifies` |
-| `createdAt`        | `string` | ✅       | Client-declared timestamp when this record was originally created                                                         |                                                     |
+| Property       | Type      | Required | Description                                                                                                                                                                                                          | Comments                             |
+| -------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `subject`      | `ref`     | ✅       | The record being acknowledged (e.g. an activity, a contributor information record, an evaluation).                                                                                                                   |                                      |
+| `context`      | `union`   | ❌       | Context for the acknowledgement (e.g. the collection that includes an activity, or the activity that includes a contributor). A URI for a lightweight reference or a strong reference for content-hash verification. |                                      |
+| `acknowledged` | `boolean` | ✅       | Whether the relationship is acknowledged (true) or rejected (false).                                                                                                                                                 |                                      |
+| `comment`      | `string`  | ❌       | Optional plain-text comment providing additional context or reasoning.                                                                                                                                               | maxLength: 10000, maxGraphemes: 1000 |
+| `createdAt`    | `string`  | ✅       | Client-declared timestamp when this record was originally created.                                                                                                                                                   |                                      |
 
 ---
 
-### `org.hypercerts.claim.measurement`
+### `org.hypercerts.context.attachment`
 
-**Description:** Measurement data related to a hypercert record (e.g. an activity and its impact).
+**Description:** An attachment providing commentary, context, evidence, or documentary material related to a hypercert record (e.g. an activity, project, claim, or evaluation).
 
 **Key:** `tid`
 
 #### Properties
 
-| Property      | Type     | Required | Description                                                                                                                                    | Comments       |
-| ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `subject`     | `ref`    | ❌       | A strong reference to the record this measurement refers to (e.g. an activity, project, or claim).                                             |                |
-| `measurers`   | `ref`    | ✅       | DIDs of the entity (or entities) that measured this data                                                                                       | maxLength: 100 |
-| `metric`      | `string` | ✅       | The metric being measured                                                                                                                      | maxLength: 500 |
-| `value`       | `string` | ✅       | The measured value                                                                                                                             | maxLength: 500 |
-| `methodType`  | `string` | ❌       | Short identifier for the measurement methodology                                                                                               | maxLength: 30  |
-| `methodURI`   | `string` | ❌       | URI to methodology documentation, standard protocol, or measurement procedure                                                                  |                |
-| `evidenceURI` | `string` | ❌       | URIs to related evidence or underlying data (e.g. org.hypercerts.claim.evidence records or raw datasets)                                       | maxLength: 50  |
-| `location`    | `ref`    | ❌       | A strong reference to the location where the measurement was taken. The record referenced must conform with the lexicon app.certified.location |                |
-| `createdAt`   | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                              |                |
+| Property                 | Type      | Required | Description                                                                                                                                                                                                                               | Comments                                                                                 |
+| ------------------------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `subjects`               | `ref[]`   | ❌       | References to the subject(s) the attachment is connected to—this may be an activity claim, outcome claim, measurement, evaluation, or even another attachment. This is optional as the attachment can exist before the claim is recorded. | maxLength: 100                                                                           |
+| `contentType`            | `string`  | ❌       | The type of attachment. Values beyond the known set are permitted.                                                                                                                                                                        | maxLength: 64, Known values: `report`, `audit`, `evidence`, `testimonial`, `methodology` |
+| `content`                | `union[]` | ❌       | The files, documents, or external references included in this attachment record.                                                                                                                                                          | maxLength: 100                                                                           |
+| `title`                  | `string`  | ✅       | Display title for this attachment (e.g. 'Impact Assessment Report', 'Audit Findings')                                                                                                                                                     | maxLength: 256                                                                           |
+| `shortDescription`       | `string`  | ❌       | Short summary of this attachment, suitable for previews and list views. Rich text annotations may be provided via `shortDescriptionFacets`.                                                                                               | maxLength: 3000, maxGraphemes: 300                                                       |
+| `shortDescriptionFacets` | `ref[]`   | ❌       | Rich text annotations for `shortDescription` (mentions, URLs, hashtags, etc).                                                                                                                                                             |                                                                                          |
+| `description`            | `union`   | ❌       | 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`               | `ref`     | ❌       | A strong reference to the location where this attachment's subject matter occurred. The record referenced must conform with the lexicon app.certified.location.                                                                           |                                                                                          |
+| `createdAt`              | `string`  | ✅       | Client-declared timestamp when this record was originally created.                                                                                                                                                                        |                                                                                          |
 
 ---
 
-### `org.hypercerts.claim.collection`
+### `org.hypercerts.context.evaluation`
 
-**Description:** A collection/group of items (activities and/or other collections). Collections support recursive nesting. Use app.certified.location as a sidecar (same TID) for location metadata.
+**Description:** An evaluation of a hypercert record (e.g. an activity and its impact).
 
 **Key:** `tid`
 
 #### Properties
 
-| Property           | Type     | Required | Description                                                                                                  | Comments                           |
-| ------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
-| `type`             | `string` | ❌       | The type of this collection. Possible fields can be 'favorites', 'project', or any other type of collection. |                                    |
-| `title`            | `string` | ✅       | The title of this collection                                                                                 | maxLength: 800, maxGraphemes: 80   |
-| `shortDescription` | `string` | ❌       | Short summary of this collection, suitable for previews and list views                                       | maxLength: 3000, maxGraphemes: 300 |
-| `description`      | `ref`    | ❌       | Rich-text description, represented as a Leaflet linear document.                                             |                                    |
-| `avatar`           | `union`  | ❌       | The collection's avatar/profile image as a URI or image blob.                                                |                                    |
-| `banner`           | `union`  | ❌       | Larger horizontal image to display behind the collection view.                                               |                                    |
-| `items`            | `ref`    | ✅       | Array of items in this collection with optional weights.                                                     |                                    |
-| `createdAt`        | `string` | ✅       | Client-declared timestamp when this record was originally created                                            |                                    |
+| Property       | Type      | Required | Description                                                                                                                                                            | Comments                            |
+| -------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `subject`      | `ref`     | ❌       | A strong reference to what is being evaluated (e.g. activity, measurement, contribution, etc.)                                                                         |                                     |
+| `evaluators`   | `ref[]`   | ✅       | DIDs of the evaluators                                                                                                                                                 | maxLength: 1000                     |
+| `content`      | `union[]` | ❌       | Evaluation data (URIs or blobs) containing detailed reports or methodology                                                                                             | maxLength: 100                      |
+| `measurements` | `ref[]`   | ❌       | Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.context.measurement | maxLength: 100                      |
+| `summary`      | `string`  | ✅       | Brief evaluation summary                                                                                                                                               | maxLength: 5000, maxGraphemes: 1000 |
+| `score`        | `ref`     | ❌       | Overall score for an evaluation on a numeric scale.                                                                                                                    |                                     |
+| `location`     | `ref`     | ❌       | An optional reference for georeferenced evaluations. The record referenced must conform with the lexicon app.certified.location.                                       |                                     |
+| `createdAt`    | `string`  | ✅       | Client-declared timestamp when this record was originally created                                                                                                      |                                     |
 
 #### Defs
 
-##### item
+##### `org.hypercerts.context.evaluation#score`
 
-| Property         | Type     | Required | Description                                                                                                                                                                                     |
-| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `itemIdentifier` | `ref`    | ✅       | Strong reference to an item in this collection. Items can be activities (org.hypercerts.claim.activity) and/or other collections (org.hypercerts.claim.collection).                             |
-| `itemWeight`     | `string` | ❌       | Optional weight for this item (positive numeric value stored as string). Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed. |
+Overall score for an evaluation on a numeric scale.
+
+| Property | Type     | Required | Description                                                                   |
+| -------- | -------- | -------- | ----------------------------------------------------------------------------- |
+| `min`    | `string` | ✅       | Minimum value of the scale as a numeric string (e.g. '0', '1').               |
+| `max`    | `string` | ✅       | Maximum value of the scale as a numeric string (e.g. '5', '10').              |
+| `value`  | `string` | ✅       | Score within the inclusive range [min, max] as a numeric string (e.g. '3.7'). |
 
 ---
 
-### `org.hypercerts.claim.rights`
+### `org.hypercerts.context.measurement`
 
-**Description:** Describes the rights that a contributor and/or an owner has, such as whether the hypercert can be sold, transferred, and under what conditions.
+**Description:** Measurement data related to one or more records (e.g. activities, projects, etc.).
 
 **Key:** `tid`
 
 #### Properties
 
-| Property            | Type     | Required | Description                                                        | Comments       |
-| ------------------- | -------- | -------- | ------------------------------------------------------------------ | -------------- |
-| `rightsName`        | `string` | ✅       | Full name of the rights                                            | maxLength: 100 |
-| `rightsType`        | `string` | ✅       | Short rights identifier for easier search                          | maxLength: 10  |
-| `rightsDescription` | `string` | ✅       | Description of the rights of this hypercert                        |                |
-| `attachment`        | `union`  | ❌       | An attachment to define the rights further, e.g. a legal document. |                |
-| `createdAt`         | `string` | ✅       | Client-declared timestamp when this record was originally created  |                |
+| Property        | Type       | Required | Description                                                                                                                                             | Comments                           |
+| --------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| `subjects`      | `ref[]`    | ❌       | Strong references to the records this measurement refers to (e.g. activities, projects, or claims).                                                     | maxLength: 100                     |
+| `metric`        | `string`   | ✅       | The metric being measured, e.g. forest area restored, number of users, etc.                                                                             | maxLength: 500                     |
+| `unit`          | `string`   | ✅       | The unit of the measured value (e.g. kg CO₂e, hectares, %, index score).                                                                                | maxLength: 50                      |
+| `value`         | `string`   | ✅       | The measured value as a numeric string (e.g. '1234.56')                                                                                                 | maxLength: 500                     |
+| `startDate`     | `string`   | ❌       | The start date and time when the measurement began.                                                                                                     |                                    |
+| `endDate`       | `string`   | ❌       | The end date and time when the measurement ended. For one-time measurements, this should equal the start date.                                          |                                    |
+| `locations`     | `ref[]`    | ❌       | Optional geographic references related to where the measurement was taken. Each referenced record must conform with the app.certified.location lexicon. | maxLength: 100                     |
+| `methodType`    | `string`   | ❌       | Short identifier for the measurement methodology                                                                                                        | maxLength: 30                      |
+| `methodURI`     | `string`   | ❌       | URI to methodology documentation, standard protocol, or measurement procedure                                                                           |                                    |
+| `evidenceURI`   | `string[]` | ❌       | URIs to related evidence or underlying data (e.g. org.hypercerts.claim.evidence records or raw datasets)                                                | maxLength: 50                      |
+| `measurers`     | `ref[]`    | ❌       | DIDs of the entities that performed this measurement                                                                                                    | maxLength: 100                     |
+| `comment`       | `string`   | ❌       | Short comment of this measurement, suitable for previews and list views. Rich text annotations may be provided via `commentFacets`.                     | maxLength: 3000, maxGraphemes: 300 |
+| `commentFacets` | `ref[]`    | ❌       | Rich text annotations for `comment` (mentions, URLs, hashtags, etc).                                                                                    |                                    |
+| `createdAt`     | `string`   | ✅       | Client-declared timestamp when this record was originally created                                                                                       |                                    |
 
 ---
 
@@ -174,44 +265,73 @@ Hypercerts-specific lexicons for tracking impact work and claims.
 
 | Property         | Type     | Required | Description                                                                                                                                                                             | Comments       |
 | ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `from`           | `ref`    | ✅       | DID of the sender who transferred the funds. Leave empty if sender wants to stay anonymous.                                                                                             |                |
-| `to`             | `string` | ✅       | The recipient of the funds. Can be identified by DID or a clear-text name.                                                                                                              |                |
-| `amount`         | `string` | ✅       | Amount of funding received.                                                                                                                                                             |                |
-| `currency`       | `string` | ✅       | Currency of the payment (e.g. EUR, USD, ETH).                                                                                                                                           |                |
-| `paymentRail`    | `string` | ❌       | How the funds were transferred (e.g. bank_transfer, credit_card, onchain, cash, check, payment_processor).                                                                              |                |
-| `paymentNetwork` | `string` | ❌       | Optional network within the payment rail (e.g. arbitrum, ethereum, sepa, visa, paypal).                                                                                                 |                |
-| `transactionId`  | `string` | ❌       | Identifier of the underlying payment transaction (e.g. bank reference, onchain transaction hash, or processor-specific ID). Use paymentNetwork to specify the network where applicable. |                |
-| `for`            | `string` | ❌       | Optional reference to the activity, project, or organization this funding relates to.                                                                                                   |                |
+| `from`           | `union`  | ❌       | The sender of the funds (a free-text string, an account DID, or a strong reference to a record). Optional — omit to represent anonymity.                                                |                |
+| `to`             | `union`  | ✅       | The recipient of the funds (a free-text string, an account DID, or a strong reference to a record).                                                                                     |                |
+| `amount`         | `string` | ✅       | Amount of funding received as a numeric string (e.g. '1000.50').                                                                                                                        | maxLength: 50  |
+| `currency`       | `string` | ✅       | Currency of the payment (e.g. EUR, USD, ETH).                                                                                                                                           | maxLength: 10  |
+| `paymentRail`    | `string` | ❌       | How the funds were transferred (e.g. bank_transfer, credit_card, onchain, cash, check, payment_processor).                                                                              | maxLength: 50  |
+| `paymentNetwork` | `string` | ❌       | Optional network within the payment rail (e.g. arbitrum, ethereum, sepa, visa, paypal).                                                                                                 | maxLength: 50  |
+| `transactionId`  | `string` | ❌       | Identifier of the underlying payment transaction (e.g. bank reference, onchain transaction hash, or processor-specific ID). Use paymentNetwork to specify the network where applicable. | maxLength: 256 |
+| `for`            | `ref`    | ❌       | Optional strong reference to the activity, project, or organization this funding relates to.                                                                                            |                |
 | `notes`          | `string` | ❌       | Optional notes or additional context for this funding receipt.                                                                                                                          | maxLength: 500 |
 | `occurredAt`     | `string` | ❌       | Timestamp when the payment occurred.                                                                                                                                                    |                |
 | `createdAt`      | `string` | ✅       | Client-declared timestamp when this receipt record was created.                                                                                                                         |                |
 
+#### Defs
+
+##### `org.hypercerts.funding.receipt#text`
+
+A free-text string value (e.g. a display name, wallet address, or other identifier).
+
+| Property | Type     | Required | Description       |
+| -------- | -------- | -------- | ----------------- |
+| `value`  | `string` | ✅       | The string value. |
+
 ---
 
-## Certified Lexicons
+### `org.hypercerts.workscope.cel`
 
-Certified lexicons are common/shared lexicons that can be used across multiple protocols.
+**Description:** A structured, machine-evaluable work scope definition using CEL (Common Expression Language). Tags referenced in the expression correspond to org.hypercerts.workscope.tag keys. See https://github.com/google/cel-spec. Note: this is intentionally type 'object' (not 'record') so it can be directly embedded inline in union types (e.g., activity.workScope) without requiring a separate collection or strongRef indirection.
 
-### `org.hypercerts.defs`
+#### Properties
 
-**Description:** Common type definitions used across all certified protocols.
+| Property     | Type     | Required | Description                                                                                                                                                                         | Comments                             |
+| ------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `expression` | `string` | ✅       | A CEL expression encoding the work scope conditions. Example: scope.hasAll(['mangrove_restoration', 'environmental_education']) && location.country == 'KE'                         | maxLength: 10000, maxGraphemes: 5000 |
+| `usedTags`   | `ref[]`  | ✅       | Strong references to org.hypercerts.workscope.tag records used in the expression. Enables fast indexing by AT-URI and provides referential integrity to the underlying tag records. | maxLength: 100                       |
+| `version`    | `string` | ✅       | CEL context schema version.                                                                                                                                                         | maxLength: 16, Known values: `v1`    |
+| `createdAt`  | `string` | ✅       | Client-declared timestamp when this expression was originally created.                                                                                                              |                                      |
 
-#### Defs
+---
+
+### `org.hypercerts.workscope.tag`
 
-| Def             | Type     | Description                                                    | Comments                                |
-| --------------- | -------- | -------------------------------------------------------------- | --------------------------------------- |
-| `uri`           | `object` | Object containing a URI to external data                       | Has `uri` property (string, format uri) |
-| `smallBlob`     | `object` | Object containing a blob to external data                      | Has `blob` property (blob, up to 10MB)  |
-| `largeBlob`     | `object` | Object containing a blob to external data                      | Has `blob` property (blob, up to 100MB) |
-| `smallImage`    | `object` | Object containing a small image                                | Has `image` property (blob, up to 5MB)  |
-| `largeImage`    | `object` | Object containing a large image                                | Has `image` property (blob, up to 10MB) |
-| `workScopeAll`  | `object` | Logical AND operation: all arguments must be satisfied.        |                                         |
-| `workScopeAny`  | `object` | Logical OR operation: at least one argument must be satisfied. |                                         |
-| `workScopeNot`  | `object` | Logical NOT operation: the argument must not be satisfied.     |                                         |
-| `workScopeAtom` | `object` | Atomic scope reference: a strong reference to a scope record.  |                                         |
+**Description:** A reusable scope atom for work scope logic expressions. Scopes can represent topics, languages, domains, deliverables, methods, regions, tags, or other categorical labels. Tags are composed into structured expressions via CEL (Common Expression Language) on activity records.
+
+**Key:** `tid`
+
+#### Properties
+
+| Property            | Type       | Required | Description                                                                                                                                                                            | Comments                                                             |
+| ------------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `key`               | `string`   | ✅       | Lowercase, underscore-separated machine-readable key for this scope (e.g., 'mangrove_restoration', 'biodiversity_monitoring'). Used as the canonical identifier in CEL expressions.    | maxLength: 120                                                       |
+| `name`              | `string`   | ✅       | Human-readable name for this scope.                                                                                                                                                    | maxLength: 200                                                       |
+| `category`          | `string`   | ❌       | Category type of this scope.                                                                                                                                                           | maxLength: 50, Known values: `topic`, `language`, `domain`, `method` |
+| `description`       | `string`   | ❌       | Optional longer description of this scope.                                                                                                                                             | maxLength: 10000, maxGraphemes: 1000                                 |
+| `parent`            | `ref`      | ❌       | Optional strong reference to a parent work scope tag record for taxonomy/hierarchy support. The record referenced must conform with the lexicon org.hypercerts.workscope.tag.          |                                                                      |
+| `status`            | `string`   | ❌       | Lifecycle status of this tag. Communities propose tags, curators accept them, deprecated tags point to replacements via supersededBy.                                                  | maxLength: 20, Known values: `proposed`, `accepted`, `deprecated`    |
+| `supersededBy`      | `ref`      | ❌       | When status is 'deprecated', points to the replacement work scope tag record. The record referenced must conform with the lexicon org.hypercerts.workscope.tag.                        |                                                                      |
+| `aliases`           | `string[]` | ❌       | Alternative human-readable names for this scope (e.g., translations, abbreviations, or common synonyms). Unlike sameAs, these are plain-text labels, not links to external ontologies. | maxLength: 50                                                        |
+| `sameAs`            | `string[]` | ❌       | URIs to semantically equivalent concepts in external ontologies or taxonomies (e.g., Wikidata QIDs, ENVO terms, SDG targets). Used for interoperability, not as documentation.         | maxLength: 20                                                        |
+| `referenceDocument` | `union`    | ❌       | Link to a governance or reference document where this work scope tag is defined and further explained.                                                                                 |                                                                      |
+| `createdAt`         | `string`   | ✅       | Client-declared timestamp when this record was originally created.                                                                                                                     |                                                                      |
 
 ---
 
+## Certified Lexicons
+
+Certified lexicons are common/shared lexicons that can be used across multiple protocols.
+
 ### `app.certified.location`
 
 **Description:** A location reference
@@ -220,15 +340,25 @@ Certified lexicons are common/shared lexicons that can be used across multiple p
 
 #### Properties
 
-| Property       | Type     | Required | Description                                                                                                               | Comments                                                           |
-| -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `lpVersion`    | `string` | ✅       | The version of the Location Protocol                                                                                      | maxLength: 10                                                      |
-| `srs`          | `string` | ✅       | The Spatial Reference System URI (e.g., http://www.opengis.net/def/crs/OGC/1.3/CRS84) that defines the coordinate system. | maxLength: 100                                                     |
-| `locationType` | `string` | ✅       | An identifier for the format of the location data (e.g., coordinate-decimal, geojson-point)                               | maxLength: 20, Known values: `coordinate-decimal`, `geojson-point` |
-| `location`     | `union`  | ✅       | The location of where the work was performed as a URI or blob.                                                            |                                                                    |
-| `name`         | `string` | ❌       | Optional name for this location                                                                                           | maxLength: 1000, maxGraphemes: 100                                 |
-| `description`  | `string` | ❌       | Optional description for this location                                                                                    | maxLength: 2000, maxGraphemes: 500                                 |
-| `createdAt`    | `string` | ✅       | Client-declared timestamp when this record was originally created                                                         |                                                                    |
+| Property       | Type     | Required | Description                                                                                                                                                                                                                               | Comments                                                                                                                              |
+| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `lpVersion`    | `string` | ✅       | The version of the Location Protocol                                                                                                                                                                                                      | maxLength: 10                                                                                                                         |
+| `srs`          | `string` | ✅       | The Spatial Reference System URI (e.g., http://www.opengis.net/def/crs/OGC/1.3/CRS84) that defines the coordinate system.                                                                                                                 | maxLength: 100                                                                                                                        |
+| `locationType` | `string` | ✅       | 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 | maxLength: 20, Known values: `coordinate-decimal`, `geojson-point`, `geojson`, `h3`, `geohash`, `wkt`, `address`, `scaledCoordinates` |
+| `location`     | `union`  | ✅       | The location of where the work was performed as a URI, blob, or inline string.                                                                                                                                                            |                                                                                                                                       |
+| `name`         | `string` | ❌       | Human-readable name for this location (e.g. 'Golden Gate Park', 'San Francisco Bay Area')                                                                                                                                                 | maxLength: 1000, maxGraphemes: 100                                                                                                    |
+| `description`  | `string` | ❌       | Additional context about this location, such as its significance to the work or specific boundaries                                                                                                                                       | maxLength: 2000, maxGraphemes: 500                                                                                                    |
+| `createdAt`    | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                                                                                                                         |                                                                                                                                       |
+
+#### Defs
+
+##### `app.certified.location#string`
+
+A location represented as a string, e.g. coordinates or a small GeoJSON string.
+
+| Property | Type     | Required | Description               |
+| -------- | -------- | -------- | ------------------------- |
+| `string` | `string` | ✅       | The location string value |
 
 ---
 
@@ -240,14 +370,14 @@ Certified lexicons are common/shared lexicons that can be used across multiple p
 
 #### Properties
 
-| Property         | Type     | Required | Description                                                                              | Comments                                                                    |
-| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| `badgeType`      | `string` | ✅       | Category of the badge (e.g. endorsement, participation, affiliation).                    |                                                                             |
-| `title`          | `string` | ✅       | Human-readable title of the badge.                                                       |                                                                             |
-| `icon`           | `blob`   | ✅       | Icon representing the badge, stored as a blob for compact visual display.                | maxSize: 1048576, accepts: image/png, image/jpeg, image/webp, image/svg+xml |
-| `description`    | `string` | ❌       | Optional short statement describing what the badge represents.                           |                                                                             |
-| `allowedIssuers` | `ref`    | ❌       | Optional allowlist of DIDs allowed to issue this badge. If omitted, anyone may issue it. |                                                                             |
-| `createdAt`      | `string` | ✅       | Client-declared timestamp when this record was originally created                        |                                                                             |
+| Property         | Type     | Required | Description                                                                              | Comments                                                                                                                    |
+| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `badgeType`      | `string` | ✅       | Category of the badge. Values beyond the known set are permitted.                        | maxLength: 100, Known values: `endorsement`, `verification`, `participation`, `certification`, `affiliation`, `recognition` |
+| `title`          | `string` | ✅       | Human-readable title of the badge.                                                       | maxLength: 256                                                                                                              |
+| `icon`           | `blob`   | ❌       | Icon representing the badge, stored as a blob for compact visual display.                | maxSize: 1048576, accepts: `image/png`, `image/jpeg`, `image/webp`, `image/svg+xml`                                         |
+| `description`    | `string` | ❌       | Optional short statement describing what the badge represents.                           | maxLength: 5000, maxGraphemes: 500                                                                                          |
+| `allowedIssuers` | `ref[]`  | ❌       | Optional allowlist of DIDs allowed to issue this badge. If omitted, anyone may issue it. | maxLength: 100                                                                                                              |
+| `createdAt`      | `string` | ✅       | Client-declared timestamp when this record was originally created                        |                                                                                                                             |
 
 ---
 
@@ -259,12 +389,13 @@ Certified lexicons are common/shared lexicons that can be used across multiple p
 
 #### Properties
 
-| Property    | Type     | Required | Description                                                                                                                                     |
-| ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `badge`     | `ref`    | ✅       | Reference to the badge definition for this award.                                                                                               |
-| `subject`   | `union`  | ✅       | Entity the badge award is for (either an account DID or any specific AT Protocol record), e.g. a user, a project, or a specific activity claim. |
-| `note`      | `string` | ❌       | Optional statement explaining the reason for this badge award.                                                                                  |
-| `createdAt` | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                               |
+| Property    | Type     | Required | Description                                                                                                                                        | Comments        |
+| ----------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `badge`     | `ref`    | ✅       | Strong reference to the badge definition at the time of award. The record referenced must conform with the lexicon app.certified.badge.definition. |                 |
+| `subject`   | `union`  | ✅       | Entity the badge award is for (either an account DID or any specific AT Protocol record), e.g. a user, a project, or a specific activity claim.    |                 |
+| `note`      | `string` | ❌       | Optional statement explaining the reason for this badge award.                                                                                     | maxLength: 500  |
+| `url`       | `string` | ❌       | Optional URL the badge award links to.                                                                                                             | maxLength: 2048 |
+| `createdAt` | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                                  |                 |
 
 ---
 
@@ -276,12 +407,636 @@ Certified lexicons are common/shared lexicons that can be used across multiple p
 
 #### Properties
 
-| Property     | Type     | Required | Description                                                              |
-| ------------ | -------- | -------- | ------------------------------------------------------------------------ |
-| `badgeAward` | `ref`    | ✅       | Reference to the badge award.                                            |
-| `response`   | `string` | ✅       | The recipient’s response for the badge (accepted or rejected).           |
-| `weight`     | `string` | ❌       | Optional relative weight for accepted badges, assigned by the recipient. |
-| `createdAt`  | `string` | ✅       | Client-declared timestamp when this record was originally created        |
+| Property     | Type     | Required | Description                                                                                                                            | Comments                             |
+| ------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `badgeAward` | `ref`    | ✅       | Strong reference to the badge award being responded to. The record referenced must conform with the lexicon app.certified.badge.award. |                                      |
+| `response`   | `string` | ✅       | The recipient’s response for the badge (accepted or rejected).                                                                         | Known values: `accepted`, `rejected` |
+| `weight`     | `string` | ❌       | Optional relative weight for accepted badges, assigned by the recipient.                                                               | maxLength: 50                        |
+| `createdAt`  | `string` | ✅       | Client-declared timestamp when this record was originally created                                                                      |                                      |
+
+---
+
+### `app.certified.actor.organization`
+
+**Description:** Extended metadata for an organization actor. Complements the base actor profile with organization-specific fields like legal structure and reference links.
+
+**Key:** `literal:self`
+
+#### Properties
+
+| Property           | Type       | Required | Description                                                                                                                                                                                                                                    | Comments      |
+| ------------------ | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `organizationType` | `string[]` | ❌       | Legal or operational structures of the organization (e.g. 'nonprofit', 'ngo', 'government', 'social-enterprise', 'cooperative').                                                                                                               | maxLength: 10 |
+| `urls`             | `ref[]`    | ❌       | Additional reference URLs (social media profiles, contact pages, donation links, etc.) with a display label for each URL.                                                                                                                      |               |
+| `location`         | `ref`      | ❌       | A strong reference to the location where the organization is based. The record referenced must conform with the lexicon app.certified.location.                                                                                                |               |
+| `foundedDate`      | `string`   | ❌       | When the organization was established. Stored as datetime per ATProto conventions (no date-only format exists). Clients should use midnight UTC (e.g., '2005-01-01T00:00:00.000Z'); consumers should treat only the date portion as canonical. |               |
+| `createdAt`        | `string`   | ✅       | Client-declared timestamp when this record was originally created.                                                                                                                                                                             |               |
+
+#### Defs
+
+##### `app.certified.actor.organization#urlItem`
+
+A labeled URL reference.
+
+| Property | Type     | Required | Description                                                                        |
+| -------- | -------- | -------- | ---------------------------------------------------------------------------------- |
+| `url`    | `string` | ✅       | The URL.                                                                           |
+| `label`  | `string` | ❌       | Optional human-readable label for this URL (e.g. 'Support page', 'Donation page'). |
+
+---
+
+### `app.certified.actor.profile`
+
+**Description:** A declaration of a Certified account profile.
+
+**Key:** `literal:self`
+
+#### Properties
+
+| Property      | Type     | Required | Description                                                                    | Comments                           |
+| ------------- | -------- | -------- | ------------------------------------------------------------------------------ | ---------------------------------- |
+| `displayName` | `string` | ❌       | Display name for the account                                                   | maxLength: 640, maxGraphemes: 64   |
+| `description` | `string` | ❌       | Free-form profile description text.                                            | maxLength: 2560, maxGraphemes: 256 |
+| `pronouns`    | `string` | ❌       | Free-form pronouns text.                                                       | maxLength: 200, maxGraphemes: 20   |
+| `website`     | `string` | ❌       | Account website URL                                                            |                                    |
+| `avatar`      | `union`  | ❌       | Small image to be displayed next to posts from account. AKA, 'profile picture' |                                    |
+| `banner`      | `union`  | ❌       | Larger horizontal image to display behind profile view.                        |                                    |
+| `createdAt`   | `string` | ✅       | Client-declared timestamp when this record was originally created              |                                    |
+
+---
+
+### `app.certified.link.evm`
+
+**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`
+
+#### Properties
+
+| Property    | Type     | Required | Description                                                                                                                                                                                   | Comments      |
+| ----------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `address`   | `string` | ✅       | EVM wallet address (0x-prefixed, with EIP-55 checksum recommended).                                                                                                                           | maxLength: 42 |
+| `proof`     | `union`  | ✅       | 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` | `string` | ✅       | Client-declared timestamp when this record was originally created.                                                                                                                            |               |
+
+#### Defs
+
+##### `app.certified.link.evm#eip712Proof`
+
+EOA wallet ownership proof via EIP-712 typed data signature. Contains both the structured message that was signed and the resulting signature.
+
+| Property    | Type     | Required | Description                                                                                                                                     |
+| ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `signature` | `string` | ✅       | ECDSA signature over the EIP-712 hash (hex-encoded with 0x prefix, 64 or 65 bytes).                                                             |
+| `message`   | `ref`    | ✅       | 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. |
+
+##### `app.certified.link.evm#eip712Message`
+
+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.
+
+| Property     | Type     | Required | Description                                                                                                                                                          |
+| ------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `did`        | `string` | ✅       | The ATProto DID being linked to the EVM address.                                                                                                                     |
+| `evmAddress` | `string` | ✅       | The EVM wallet address (must match the top-level address field).                                                                                                     |
+| `chainId`    | `string` | ✅       | 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. |
+| `timestamp`  | `string` | ✅       | Unix timestamp when the attestation was created (bigint serialized).                                                                                                 |
+| `nonce`      | `string` | ✅       | Replay-protection nonce (bigint serialized).                                                                                                                         |
+
+---
+
+## Type Definitions
+
+Common type definitions used across all protocols.
+
+### `app.certified.defs`
+
+**Description:** Common type definitions used across certified protocols.
+
+#### Defs
+
+##### `app.certified.defs#did`
+
+A Decentralized Identifier (DID) string.
+
+| Property | Type     | Required | Description           |
+| -------- | -------- | -------- | --------------------- |
+| `did`    | `string` | ✅       | The DID string value. |
+
+---
+
+### `org.hypercerts.defs`
+
+**Description:** Common type definitions used across all Hypercerts protocols.
+
+#### Defs
+
+##### `org.hypercerts.defs#descriptionString`
+
+An inline long-form description as plain text or markdown, with optional rich-text annotations.
+
+| Property | Type     | Required | Description                                                                |
+| -------- | -------- | -------- | -------------------------------------------------------------------------- |
+| `value`  | `string` | ✅       | The description text (plain text or markdown).                             |
+| `facets` | `ref[]`  | ❌       | Rich text annotations for the description (mentions, URLs, hashtags, etc). |
+
+##### `org.hypercerts.defs#uri`
+
+Object containing a URI to external data
+
+| Property | Type     | Required | Description          |
+| -------- | -------- | -------- | -------------------- |
+| `uri`    | `string` | ✅       | URI to external data |
+
+##### `org.hypercerts.defs#smallBlob`
+
+Object containing a blob to external data
+
+| Property | Type   | Required | Description                        |
+| -------- | ------ | -------- | ---------------------------------- |
+| `blob`   | `blob` | ✅       | Blob to external data (up to 10MB) |
+
+##### `org.hypercerts.defs#largeBlob`
+
+Object containing a blob to external data
+
+| Property | Type   | Required | Description                         |
+| -------- | ------ | -------- | ----------------------------------- |
+| `blob`   | `blob` | ✅       | Blob to external data (up to 100MB) |
+
+##### `org.hypercerts.defs#smallImage`
+
+Object containing a small image
+
+| Property | Type   | Required | Description       |
+| -------- | ------ | -------- | ----------------- |
+| `image`  | `blob` | ✅       | Image (up to 5MB) |
+
+##### `org.hypercerts.defs#smallVideo`
+
+Object containing a small video
+
+| Property | Type   | Required | Description        |
+| -------- | ------ | -------- | ------------------ |
+| `video`  | `blob` | ✅       | Video (up to 20MB) |
+
+##### `org.hypercerts.defs#largeImage`
+
+Object containing a large image
+
+| Property | Type   | Required | Description        |
+| -------- | ------ | -------- | ------------------ |
+| `image`  | `blob` | ✅       | Image (up to 10MB) |
+
+---
+
+## External Lexicons
+
+External lexicons from other protocols and systems.
+
+### `app.bsky.richtext.facet`
+
+**Description:** Annotation of a sub-string within rich text.
+
+#### Properties
+
+| Property   | Type      | Required | Description                                                                                                                                                                                                                                                                                                                                                |
+| ---------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index`    | `ref`     | ✅       | Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets. |
+| `features` | `union[]` | ✅       |                                                                                                                                                                                                                                                                                                                                                            |
+
+#### Defs
+
+##### `app.bsky.richtext.facet#mention`
+
+Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID.
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `did`    | `string` | ✅       |             |
+
+##### `app.bsky.richtext.facet#link`
+
+Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `uri`    | `string` | ✅       |             |
+
+##### `app.bsky.richtext.facet#tag`
+
+Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `tag`    | `string` | ✅       |             |
+
+##### `app.bsky.richtext.facet#byteSlice`
+
+Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.
+
+| Property    | Type      | Required | Description |
+| ----------- | --------- | -------- | ----------- |
+| `byteStart` | `integer` | ✅       |             |
+| `byteEnd`   | `integer` | ✅       |             |
+
+---
+
+### `com.atproto.repo.strongRef`
+
+#### Properties
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `uri`    | `string` | ✅       |             |
+| `cid`    | `string` | ✅       |             |
+
+---
+
+### `org.hyperboards.board`
+
+**Description:** Configuration record for a hyperboard, wrapping an underlying activity or collection with visual presentation settings. Stored in the creator's PDS.
+
+**Key:** `tid`
+
+#### 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.                                       |                 |
+
+#### Defs
+
+##### `org.hyperboards.board#boardConfig`
+
+Visual configuration for a hyperboard's background, colors, and layout.
+
+| Property              | Type      | Required | Description                                                           |
+| --------------------- | --------- | -------- | --------------------------------------------------------------------- |
+| `backgroundType`      | `string`  | ❌       | Type of background content.                                           |
+| `backgroundImage`     | `union`   | ❌       | Background image as a URI or image blob.                              |
+| `backgroundIframeUrl` | `string`  | ❌       | URI of the background iframe.                                         |
+| `backgroundGrayscale` | `boolean` | ❌       | Whether the background is rendered in grayscale. Default: true.       |
+| `backgroundOpacity`   | `integer` | ❌       | Background opacity as a percentage (0–100).                           |
+| `backgroundColor`     | `string`  | ❌       | Background color as a hex string (e.g. '#ffffff').                    |
+| `borderColor`         | `string`  | ❌       | Border color as a hex string (e.g. '#000000').                        |
+| `grayscaleImages`     | `boolean` | ❌       | Whether contributor images are rendered in grayscale. Default: false. |
+| `imageShape`          | `string`  | ❌       | Shape used to crop contributor images on this board.                  |
+| `aspectRatio`         | `string`  | ❌       | Display aspect ratio of the board.                                    |
+
+##### `org.hyperboards.board#contributorConfig`
+
+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.
+
+| Property         | Type      | Required | Description                                                                                                                                                                                                            |
+| ---------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contributor`    | `union`   | ✅       | 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`       | `boolean` | ❌       | 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`    | `string`  | ❌       | Display name for this contributor on this board.                                                                                                                                                                       |
+| `image`          | `union`   | ❌       | Avatar or face image for this contributor on this board, as a URI or image blob.                                                                                                                                       |
+| `video`          | `union`   | ❌       | Video for this contributor, as a URI (embed/direct link) or uploaded video blob.                                                                                                                                       |
+| `hoverImage`     | `union`   | ❌       | Image overlay shown when hovering over this contributor, as a URI or image blob.                                                                                                                                       |
+| `hoverIframeUrl` | `string`  | ❌       | Iframe overlay shown when hovering over this contributor.                                                                                                                                                              |
+| `url`            | `string`  | ❌       | Click-through link URL for this contributor.                                                                                                                                                                           |
+
+---
+
+### `org.hyperboards.displayProfile`
+
+**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`
+
+#### Properties
+
+| Property         | Type     | Required | Description                                                                                     | Comments                         |
+| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------- | -------------------------------- |
+| `displayName`    | `string` | ❌       | Display name override for this user on hyperboards.                                             | maxLength: 640, maxGraphemes: 64 |
+| `image`          | `union`  | ❌       | Avatar or face image override for this user on hyperboards, as a URI or image blob.             |                                  |
+| `video`          | `union`  | ❌       | Default video for this user across boards, as a URI (embed/direct link) or uploaded video blob. |                                  |
+| `hoverImage`     | `union`  | ❌       | Default hover image for this user across boards, as a URI or image blob.                        |                                  |
+| `hoverIframeUrl` | `string` | ❌       | Default hover iframe URL for this user across boards.                                           | maxLength: 2048                  |
+| `url`            | `string` | ❌       | Default click-through link URL for this user across boards.                                     | maxLength: 2048                  |
+| `createdAt`      | `string` | ✅       | Client-declared timestamp when this record was originally created.                              |                                  |
+
+---
+
+### `pub.leaflet.blocks.blockquote`
+
+#### Properties
+
+| Property    | Type     | Required | Description |
+| ----------- | -------- | -------- | ----------- |
+| `plaintext` | `string` | ✅       |             |
+| `facets`    | `ref[]`  | ❌       |             |
+
+---
+
+### `pub.leaflet.blocks.bskyPost`
+
+#### Properties
+
+| Property     | Type     | Required | Description |
+| ------------ | -------- | -------- | ----------- |
+| `postRef`    | `ref`    | ✅       |             |
+| `clientHost` | `string` | ❌       |             |
+
+---
+
+### `pub.leaflet.blocks.button`
+
+#### Properties
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `text`   | `string` | ✅       |             |
+| `url`    | `string` | ✅       |             |
+
+---
+
+### `pub.leaflet.blocks.code`
+
+#### Properties
+
+| Property                  | Type     | Required | Description |
+| ------------------------- | -------- | -------- | ----------- |
+| `plaintext`               | `string` | ✅       |             |
+| `language`                | `string` | ❌       |             |
+| `syntaxHighlightingTheme` | `string` | ❌       |             |
+
+---
+
+### `pub.leaflet.blocks.header`
+
+#### Properties
+
+| Property    | Type      | Required | Description |
+| ----------- | --------- | -------- | ----------- |
+| `level`     | `integer` | ❌       |             |
+| `plaintext` | `string`  | ✅       |             |
+| `facets`    | `ref[]`   | ❌       |             |
+
+---
+
+### `pub.leaflet.blocks.horizontalRule`
+
+#### Properties
+
+---
+
+### `pub.leaflet.blocks.iframe`
+
+#### Properties
+
+| Property | Type      | Required | Description |
+| -------- | --------- | -------- | ----------- |
+| `url`    | `string`  | ✅       |             |
+| `height` | `integer` | ❌       |             |
+
+---
+
+### `pub.leaflet.blocks.image`
+
+#### Properties
+
+| Property      | Type     | Required | Description                                           | Comments                             |
+| ------------- | -------- | -------- | ----------------------------------------------------- | ------------------------------------ |
+| `image`       | `blob`   | ✅       |                                                       | maxSize: 1000000, accepts: `image/*` |
+| `alt`         | `string` | ❌       | Alt text description of the image, for accessibility. |                                      |
+| `aspectRatio` | `ref`    | ✅       |                                                       |                                      |
+
+#### Defs
+
+##### `pub.leaflet.blocks.image#aspectRatio`
+
+| Property | Type      | Required | Description |
+| -------- | --------- | -------- | ----------- |
+| `width`  | `integer` | ✅       |             |
+| `height` | `integer` | ✅       |             |
+
+---
+
+### `pub.leaflet.blocks.math`
+
+#### Properties
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `tex`    | `string` | ✅       |             |
+
+---
+
+### `pub.leaflet.blocks.orderedList`
+
+#### Properties
+
+| Property     | Type      | Required | Description                                                                |
+| ------------ | --------- | -------- | -------------------------------------------------------------------------- |
+| `startIndex` | `integer` | ❌       | The starting number for this ordered list. Defaults to 1 if not specified. |
+| `children`   | `ref[]`   | ✅       |                                                                            |
+
+#### Defs
+
+##### `pub.leaflet.blocks.orderedList#listItem`
+
+| Property                | Type      | Required | Description                                                                                                               |
+| ----------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `checked`               | `boolean` | ❌       | If present, this item is a checklist item. true = checked, false = unchecked. If absent, this is a normal list item.      |
+| `content`               | `union`   | ✅       |                                                                                                                           |
+| `children`              | `ref[]`   | ❌       | Nested ordered list items. Mutually exclusive with unorderedListChildren; if both are present, children takes precedence. |
+| `unorderedListChildren` | `ref`     | ❌       | A nested unordered list. Mutually exclusive with children; if both are present, children takes precedence.                |
+
+---
+
+### `pub.leaflet.blocks.page`
+
+#### Properties
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `id`     | `string` | ✅       |             |
+
+---
+
+### `pub.leaflet.blocks.poll`
+
+#### Properties
+
+| Property  | Type  | Required | Description |
+| --------- | ----- | -------- | ----------- |
+| `pollRef` | `ref` | ✅       |             |
+
+---
+
+### `pub.leaflet.blocks.text`
+
+#### Properties
+
+| Property    | Type     | Required | Description |
+| ----------- | -------- | -------- | ----------- |
+| `plaintext` | `string` | ✅       |             |
+| `textSize`  | `string` | ❌       |             |
+| `facets`    | `ref[]`  | ❌       |             |
+
+---
+
+### `pub.leaflet.blocks.unorderedList`
+
+#### Properties
+
+| Property   | Type    | Required | Description |
+| ---------- | ------- | -------- | ----------- |
+| `children` | `ref[]` | ✅       |             |
+
+#### Defs
+
+##### `pub.leaflet.blocks.unorderedList#listItem`
+
+| Property              | Type      | Required | Description                                                                                                               |
+| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `checked`             | `boolean` | ❌       | If present, this item is a checklist item. true = checked, false = unchecked. If absent, this is a normal list item.      |
+| `content`             | `union`   | ✅       |                                                                                                                           |
+| `children`            | `ref[]`   | ❌       | Nested unordered list items. Mutually exclusive with orderedListChildren; if both are present, children takes precedence. |
+| `orderedListChildren` | `ref`     | ❌       | Nested ordered list items. Mutually exclusive with children; if both are present, children takes precedence.              |
+
+---
+
+### `pub.leaflet.blocks.website`
+
+#### Properties
+
+| Property       | Type     | Required | Description | Comments                             |
+| -------------- | -------- | -------- | ----------- | ------------------------------------ |
+| `previewImage` | `blob`   | ❌       |             | maxSize: 1000000, accepts: `image/*` |
+| `title`        | `string` | ❌       |             |                                      |
+| `description`  | `string` | ❌       |             |                                      |
+| `src`          | `string` | ✅       |             |                                      |
+
+---
+
+### `pub.leaflet.pages.linearDocument`
+
+#### Properties
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `id`     | `string` | ❌       |             |
+| `blocks` | `ref[]`  | ✅       |             |
+
+#### Defs
+
+##### `pub.leaflet.pages.linearDocument#block`
+
+| Property    | Type     | Required | Description |
+| ----------- | -------- | -------- | ----------- |
+| `block`     | `union`  | ✅       |             |
+| `alignment` | `string` | ❌       |             |
+
+##### `pub.leaflet.pages.linearDocument#quote`
+
+| Property | Type  | Required | Description |
+| -------- | ----- | -------- | ----------- |
+| `start`  | `ref` | ✅       |             |
+| `end`    | `ref` | ✅       |             |
+
+##### `pub.leaflet.pages.linearDocument#position`
+
+| Property | Type        | Required | Description |
+| -------- | ----------- | -------- | ----------- |
+| `block`  | `integer[]` | ✅       |             |
+| `offset` | `integer`   | ✅       |             |
+
+---
+
+### `pub.leaflet.richtext.facet`
+
+**Description:** Annotation of a sub-string within rich text.
+
+#### Properties
+
+| Property   | Type      | Required | Description                                                                                                                                                                                                                                                                                                                                                |
+| ---------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index`    | `ref`     | ✅       | Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets. |
+| `features` | `union[]` | ✅       |                                                                                                                                                                                                                                                                                                                                                            |
+
+#### Defs
+
+##### `pub.leaflet.richtext.facet#byteSlice`
+
+Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.
+
+| Property    | Type      | Required | Description |
+| ----------- | --------- | -------- | ----------- |
+| `byteStart` | `integer` | ✅       |             |
+| `byteEnd`   | `integer` | ✅       |             |
+
+##### `pub.leaflet.richtext.facet#link`
+
+Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `uri`    | `string` | ✅       |             |
+
+##### `pub.leaflet.richtext.facet#didMention`
+
+Facet feature for mentioning a did.
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `did`    | `string` | ✅       |             |
+
+##### `pub.leaflet.richtext.facet#atMention`
+
+Facet feature for mentioning an AT URI.
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `atURI`  | `string` | ✅       |             |
+
+##### `pub.leaflet.richtext.facet#code`
+
+Facet feature for inline code.
+
+##### `pub.leaflet.richtext.facet#highlight`
+
+Facet feature for highlighted text.
+
+##### `pub.leaflet.richtext.facet#underline`
+
+Facet feature for underline markup
+
+##### `pub.leaflet.richtext.facet#strikethrough`
+
+Facet feature for strikethrough markup
+
+##### `pub.leaflet.richtext.facet#id`
+
+Facet feature for an identifier. Used for linking to a segment
+
+| Property | Type     | Required | Description |
+| -------- | -------- | -------- | ----------- |
+| `id`     | `string` | ❌       |             |
+
+##### `pub.leaflet.richtext.facet#bold`
+
+Facet feature for bold text
+
+##### `pub.leaflet.richtext.facet#italic`
+
+Facet feature for italic text
+
+##### `pub.leaflet.richtext.facet#footnote`
+
+Facet feature for a footnote reference
+
+| Property           | Type     | Required | Description |
+| ------------------ | -------- | -------- | ----------- |
+| `footnoteId`       | `string` | ✅       |             |
+| `contentPlaintext` | `string` | ✅       |             |
+| `contentFacets`    | `ref[]`  | ❌       |             |
 
 ---