@hypercerts-org/lexicon 0.10.0-beta.12 → 0.10.0-beta.14

package/CHANGELOG.md

@@ -1,5 +1,141 @@
 # @hypercerts-org/lexicon
 
+## 0.10.0-beta.14
+
+### Minor Changes
+
+- [#133](https://github.com/hypercerts-org/hypercerts-lexicon/pull/133) [`6752cad`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/6752cad3c9e58b9a8e1a3ca17f2ea7a4a68dba81) Thanks [@Kzoeps](https://github.com/Kzoeps)! - Add profile lexicon for Hypercert account profiles with support for display name, description, pronouns, website, avatar, banner.
+
+- [#132](https://github.com/hypercerts-org/hypercerts-lexicon/pull/132) [`da481e0`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/da481e09f5bd1a8e62e388f2c6001896d76b1fbf) Thanks [@aspiers](https://github.com/aspiers)! - Convert app.certified.defs#did to object type
+
+  The did definition in app.certified.defs has been converted from a primitive
+  string type to an object type to comply with the ATProto specification
+  requirement that all union variants must be object or record types.
+
+  This change was necessary because app.certified.badge.award uses this
+  definition in a union for the subject property.
+
+  Breaking changes:
+  - `app.certified.defs#did`: Now an object with `did` string property (maxLength 256)
+  - Code using this type must now access the `.did` property instead of using the value directly
+
+- [#132](https://github.com/hypercerts-org/hypercerts-lexicon/pull/132) [`e134b26`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/e134b26c43a70c0a9ae04cc12b8a3bd05990c470) Thanks [@aspiers](https://github.com/aspiers)! - Convert union string definitions to object types in activity lexicon
+
+  The contributorIdentity, contributorRole, and workScopeString definitions
+  in org.hypercerts.claim.activity have been converted from primitive string
+  types to object types to comply with the ATProto specification requirement
+  that all union variants must be object or record types.
+
+  Additionally, maximum length constraints have been reduced to more reasonable
+  values:
+  - `contributorIdentity.identity`: maxLength 1000, maxGraphemes 100 (previously no limits)
+  - `contributorRole.role`: maxLength 1000, maxGraphemes 100 (previously maxLength 10000, maxGraphemes 1000)
+  - `workScopeString.scope`: maxLength 1000, maxGraphemes 100 (previously maxLength 10000, maxGraphemes 1000)
+
+  Breaking changes:
+  - `contributorIdentity`: Now an object with `identity` string property
+  - `contributorRole`: Now an object with `role` string property
+  - `workScopeString`: Now an object with `scope` string property
+  - Reduced maximum lengths may affect existing records with longer values
+
+  This requires updating code that uses these union types to access the nested
+  property instead of using the value directly.
+
+- [#135](https://github.com/hypercerts-org/hypercerts-lexicon/pull/135) [`806cfbc`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/806cfbca7cbcd3674a5f8e97a6b6dd87ba806c08) Thanks [@Kzoeps](https://github.com/Kzoeps)! - Move profile lexicon from app.certified.profile to app.certified.actor.profile namespace, requiring migration of existing profile records
+
+## 0.10.0-beta.13
+
+### Minor Changes
+
+- [#131](https://github.com/hypercerts-org/hypercerts-lexicon/pull/131) [`7f42fad`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/7f42fad517e191dad6db22fc67ec8346ec167f5c) Thanks [@aspiers](https://github.com/aspiers)! - Add inline string format to app.certified.location schema with documentation and examples
+
+- [#118](https://github.com/hypercerts-org/hypercerts-lexicon/pull/118) [`8427780`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/8427780888759ee749a683528f49e6b0da2b97c2) Thanks [@holkexyz](https://github.com/holkexyz)! - Rename evidence lexicon to attachment and refactor schema structure
+
+  **Breaking Changes:**
+  - **Lexicon ID change:**
+    - `org.hypercerts.claim.evidence` → `org.hypercerts.claim.attachment`
+    - All existing evidence records must be migrated to use the new lexicon ID
+  - **Schema structure changes (`org.hypercerts.claim.attachment`):**
+    - Changed `subject` (single strongRef) to `subjects` (array of strongRefs, maxLength: 100)
+    - Changed `content` from single union (uri/blob) to array of unions (maxLength: 100)
+    - Added `contentType` field (string, maxLength: 64) to specify attachment type
+    - Removed `relationType` field (previously used to indicate supports/challenges/clarifies)
+    - Removed `contributors` field
+    - Removed `locations` field
+    - Added rich text support: `shortDescriptionFacets` and `descriptionFacets` (arrays of `app.bsky.richtext.facet`)
+    - Updated required fields: `["title", "content", "createdAt"]` (content is now required)
+  - **Common definitions (`org.hypercerts.defs`):**
+    - Added `weightedContributor` def for contributor references with optional weights
+    - Added `contributorIdentity` def for string-based contributor identification
+
+  **Migration:**
+
+  **Lexicon ID:** Update all references from `org.hypercerts.claim.evidence` to `org.hypercerts.claim.attachment`.
+
+  **Schema migration:**
+
+  ```json
+  // Before (org.hypercerts.claim.evidence)
+  {
+    "$type": "org.hypercerts.claim.evidence",
+    "subject": { "uri": "...", "cid": "..." },
+    "content": { "uri": "https://..." },
+    "title": "Evidence Title",
+    "relationType": "supports",
+    "createdAt": "..."
+  }
+
+  // After (org.hypercerts.claim.attachment)
+  {
+    "$type": "org.hypercerts.claim.attachment",
+    "subjects": [{ "uri": "...", "cid": "..." }],
+    "content": [{ "uri": "https://..." }],
+    "contentType": "evidence",
+    "title": "Evidence Title",
+    "createdAt": "..."
+  }
+  ```
+
+  **Field mapping:**
+  - `subject` → `subjects` (wrap in array)
+  - `content` (single) → `content` (array, wrap existing value)
+  - `relationType` → remove (no direct replacement)
+  - `contributors` → remove (no direct replacement)
+  - `locations` → remove (no direct replacement)
+
+### Patch Changes
+
+- [#118](https://github.com/hypercerts-org/hypercerts-lexicon/pull/118) [`8427780`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/8427780888759ee749a683528f49e6b0da2b97c2) Thanks [@holkexyz](https://github.com/holkexyz)! - Add location property to attachment schema
+
+  **New Feature:**
+  - **`location` field** (`org.hypercerts.claim.attachment`):
+    - Added optional `location` property as a strong reference (`com.atproto.repo.strongRef`)
+    - Allows attachments to associate location metadata directly without using the sidecar pattern
+    - The referenced record must conform to the `app.certified.location` lexicon
+
+  **Usage:**
+
+  ```json
+  {
+    "$type": "org.hypercerts.claim.attachment",
+    "subjects": [
+      {
+        "uri": "at://did:plc:.../org.hypercerts.claim.activity/...",
+        "cid": "..."
+      }
+    ],
+    "content": [{ "uri": "https://..." }],
+    "title": "Field Report",
+    "location": {
+      "uri": "at://did:plc:.../app.certified.location/abc123",
+      "cid": "..."
+    },
+    "createdAt": "..."
+  }
+  ```
+
+  This change aligns with the location property addition to collections (PR #123), providing a consistent pattern for associating location metadata across record types.
+
 ## 0.10.0-beta.12
 
 ### Minor Changes

package/README.md

@@ -89,6 +89,95 @@ await agent.api.com.atproto.repo.createRecord({
 });
 ```
 
+### Creating Location Records
+
+Location records (`app.certified.location`) specify where work was performed
+using geographic coordinates or other location formats. They can be referenced
+by activities, collections, attachments, measurements, and evaluations.
+
+```typescript
+import { LOCATION_NSID } from "@hypercerts-org/lexicon";
+
+const locationRecord = {
+  $type: LOCATION_NSID,
+  lpVersion: "1.0", // Location Protocol version
+  srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84", // Spatial Reference System
+  locationType: "coordinate-decimal", // or "geojson-point"
+  location: {
+    uri: "https://example.com/location-data.geojson",
+  },
+  // Optional fields
+  name: "Project Site A",
+  description: "Primary research facility in the Amazon rainforest",
+  createdAt: new Date().toISOString(),
+};
+```
+
+- `lpVersion` (required): Version of the Location Protocol specification
+- `srs` (required): Spatial Reference System URI defining the coordinate system
+- `locationType` (required): Format identifier (e.g., "coordinate-decimal", "geojson-point")
+- `location` (required): Location data as URI, blob, or string
+- `name` (optional): Human-readable name for the location
+- `description` (optional): Additional context about the location
+- `createdAt` (required): Timestamp when the record was created
+
+**Location data formats:**
+
+The `location` field accepts three formats:
+
+1. **URI reference**: `{ uri: "https://..." }` - Link to external location data
+2. **Small blob**: Embedded location data (up to 10MB)
+3. **Location string**: Inline string wrapped in an object, containing coordinates or GeoJSON
+
+```typescript
+// Example with embedded blob
+const locationWithBlob = {
+  $type: LOCATION_NSID,
+  lpVersion: "1.0",
+  srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
+  locationType: "geojson-point",
+  location: {
+    blob: {
+      $type: "blob",
+      ref: {
+        $link: "bafyrei...", // CID of the uploaded blob
+      },
+      mimeType: "application/geo+json",
+      size: 123,
+    },
+  },
+  name: "Amazon Research Station",
+  createdAt: new Date().toISOString(),
+};
+
+// Example with inline string (coordinates)
+const locationWithCoordinates = {
+  $type: LOCATION_NSID,
+  lpVersion: "1.0",
+  srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
+  locationType: "coordinate-decimal",
+  location: {
+    string: "-3.4653, -62.2159", // lat, lon
+  },
+  name: "Amazon Research Site",
+  description: "Field station coordinates",
+  createdAt: new Date().toISOString(),
+};
+
+// Example with inline GeoJSON string
+const locationWithGeoJSON = {
+  $type: LOCATION_NSID,
+  lpVersion: "1.0",
+  srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
+  locationType: "geojson-point",
+  location: {
+    string: '{"type":"Point","coordinates":[-62.2159,-3.4653]}',
+  },
+  name: "Research Station Alpha",
+  createdAt: new Date().toISOString(),
+};
+```
+
 ### Accessing NSIDs (Lexicon IDs)
 
 **Recommended**: Use individual NSID constants for cleaner, more readable code:
@@ -322,3 +411,56 @@ const collectionRecord = {
 ```
 
 The `location` field is a strong reference to an `app.certified.location` record containing the same `uri` and `cid` fields as described above for activities.
+
+### Creating Attachments
+
+Attachments provide commentary, context, evidence, or documentary material
+related to hypercert records. They can be linked to activities, evaluations,
+measurements, or even other attachments:
+
+```typescript
+import { ATTACHMENT_NSID } from "@hypercerts-org/lexicon";
+
+const attachmentRecord = {
+  $type: ATTACHMENT_NSID,
+  title: "Field Survey Report",
+  subjects: [
+    {
+      uri: "at://did:plc:alice/org.hypercerts.claim.activity/abc123",
+      cid: "...",
+    },
+  ],
+  contentType: "report",
+  content: [
+    { uri: "https://example.com/reports/survey-2024.pdf" },
+    { uri: "ipfs://Qm..." },
+  ],
+  shortDescription: "Quarterly field survey documenting project progress",
+  createdAt: new Date().toISOString(),
+};
+```
+
+**Key fields:**
+
+- `title` (required): String title for the attachment
+- `shortDescription`/`description`: Support rich text via facet annotations
+- `subjects` (optional): Array of strong references to records this attachment relates to
+- `contentType` (optional): Type descriptor (e.g., "report", "audit", "evidence", "testimonial")
+- `content` (required): Array of URIs or blobs containing the attachment files
+- `location` (optional): Strong reference to an `app.certified.location` record
+- `createdAt` (required): Timestamp when the attachment was created
+
+**Adding Location to Attachments:**
+
+```typescript
+const attachmentWithLocation = {
+  $type: ATTACHMENT_NSID,
+  title: "Site Inspection Photos",
+  content: [{ uri: "https://..." }],
+  location: {
+    uri: "at://did:plc:alice/app.certified.location/loc123",
+    cid: "...",
+  },
+  createdAt: new Date().toISOString(),
+};
+```

package/SCHEMAS.md

@@ -33,7 +33,7 @@ Hypercerts-specific lexicons for tracking impact work and claims.
 
 #### Defs
 
-##### contributor
+##### `org.hypercerts.claim.activity#contributor`
 
 | Property              | Type     | Required | Description                                                                                                                                                                                                                                                        |
 | --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -41,6 +41,113 @@ Hypercerts-specific lexicons for tracking impact work and claims.
 | `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.                                                                                                                        |
 
+##### `org.hypercerts.claim.activity#contributorIdentity`
+
+| Property   | Type     | Required | Description                                          |
+| ---------- | -------- | -------- | ---------------------------------------------------- |
+| `identity` | `string` | ✅       | The contributor identity string (DID or identifier). |
+
+##### `org.hypercerts.claim.activity#contributorRole`
+
+| Property | Type     | Required | Description                       |
+| -------- | -------- | -------- | --------------------------------- |
+| `role`   | `string` | ✅       | The contribution role or details. |
+
+##### `org.hypercerts.claim.activity#workScopeString`
+
+| Property | Type     | Required | Description                        |
+| -------- | -------- | -------- | ---------------------------------- |
+| `scope`  | `string` | ✅       | The work scope description string. |
+
+---
+
+### `org.hypercerts.claim.attachment`
+
+**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                             |
+| ------------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `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, e.g. report, audit, evidence, testimonial, methodology, etc.                                                                                                                                                      | maxLength: 64                        |
+| `content`                | `union`  | ✅       | The files, documents, or external references included in this attachment record.                                                                                                                                                          | maxLength: 100                       |
+| `title`                  | `string` | ✅       | Title of this attachment.                                                                                                                                                                                                                 | 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`            | `string` | ❌       | Optional longer description of this attachment, 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).                                                                                                                                                                  |                                      |
+| `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`
+
+**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. 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.                                                                                                          |                                    |
+| `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
+
+##### `org.hypercerts.claim.collection#item`
+
+| 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. |
+
+---
+
+### `org.hypercerts.claim.contributionDetails`
+
+**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` | ❌       | What the contribution concretely was.                                                | maxLength: 10000, maxGraphemes: 1000 |
+| `startDate`               | `string` | ❌       | When this contribution started. This should be a subset of the hypercert timeframe.  |                                      |
+| `endDate`                 | `string` | ❌       | When this contribution finished. This should be a subset of the hypercert 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 or a URI to a social profile of the contributor.               |                |
+| `displayName` | `string` | ❌       | Display name of the contributor.                                   | 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.evaluation`
@@ -64,7 +171,7 @@ Hypercerts-specific lexicons for tracking impact work and claims.
 
 #### Defs
 
-##### score
+##### `org.hypercerts.claim.evaluation#score`
 
 | Property | Type      | Required | Description                                  |
 | -------- | --------- | -------- | -------------------------------------------- |
@@ -74,26 +181,6 @@ Hypercerts-specific lexicons for tracking impact work and claims.
 
 ---
 
-### `org.hypercerts.claim.evidence`
-
-**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.
-
-**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                                                         |                                                     |
-
----
-
 ### `org.hypercerts.claim.measurement`
 
 **Description:** Measurement data related to a hypercert record (e.g. an activity and its impact).
@@ -121,37 +208,6 @@ Hypercerts-specific lexicons for tracking impact work and claims.
 
 ---
 
-### `org.hypercerts.claim.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. 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.                                                                                                          |                                    |
-| `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
-
-##### item
-
-| 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. |
-
----
-
 ### `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.
@@ -194,26 +250,31 @@ Hypercerts-specific lexicons for tracking impact work and claims.
 
 ---
 
-## Certified Lexicons
-
-Certified lexicons are common/shared lexicons that can be used across multiple protocols.
+### `org.hypercerts.helper.workScopeTag`
 
-### `org.hypercerts.defs`
+**Description:** A reusable scope atom for work scope logic expressions. Scopes can represent topics, languages, domains, deliverables, methods, regions, tags, or other categorical labels.
 
-**Description:** Common type definitions used across all certified protocols.
+**Key:** `tid`
 
-#### Defs
+#### Properties
 
-| 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) |
+| Property            | Type     | Required | Description                                                                                      | Comments                             |
+| ------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------ |
+| `createdAt`         | `string` | ✅       | Client-declared timestamp when this record was originally created                                |                                      |
+| `key`               | `string` | ✅       | Lowercase, hyphenated machine-readable key for this scope (e.g., 'ipfs', 'go-lang', 'filecoin'). | maxLength: 120                       |
+| `label`             | `string` | ✅       | Human-readable label for this scope.                                                             | maxLength: 200                       |
+| `kind`              | `string` | ❌       | Category type of this scope. Recommended values: topic, language, domain, method, tag.           | maxLength: 50                        |
+| `description`       | `string` | ❌       | Optional longer description of this scope.                                                       | maxLength: 10000, maxGraphemes: 1000 |
+| `parent`            | `ref`    | ❌       | Optional strong reference to a parent scope record for taxonomy/hierarchy support.               |                                      |
+| `aliases`           | `string` | ❌       | Optional array of alternative names or identifiers for this scope.                               | maxLength: 50                        |
+| `externalReference` | `union`  | ❌       | Optional external reference for this scope as a URI or blob.                                     |                                      |
 
 ---
 
+## Certified Lexicons
+
+Certified lexicons are common/shared lexicons that can be used across multiple protocols.
+
 ### `app.certified.location`
 
 **Description:** A location reference
@@ -227,11 +288,19 @@ Certified lexicons are common/shared lexicons that can be used across multiple p
 | `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.                                                            |                                                                    |
+| `location`     | `union`  | ✅       | The location of where the work was performed as a URI, blob, or inline string.                                            |                                                                    |
 | `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                                                         |                                                                    |
 
+#### Defs
+
+##### `app.certified.location#string`
+
+| Property | Type     | Required | Description               |
+| -------- | -------- | -------- | ------------------------- |
+| `string` | `string` | ✅       | The location string value |
+
 ---
 
 ### `app.certified.badge.definition`
@@ -287,6 +356,90 @@ Certified lexicons are common/shared lexicons that can be used across multiple p
 
 ---
 
+### `app.certified.actor.profile`
+
+**Description:** A declaration of a Hypercert account profile.
+
+**Key:** `literal:self`
+
+#### Properties
+
+| Property      | Type     | Required | Description                                                                    | Comments                           |
+| ------------- | -------- | -------- | ------------------------------------------------------------------------------ | ---------------------------------- |
+| `displayName` | `string` | ❌       |                                                                                | 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` | ❌       |                                                                                |                                    |
+| `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` | ❌       |                                                                                |                                    |
+
+---
+
+### `app.certified.defs`
+
+**Description:** Common type definitions used across certified protocols.
+
+#### Defs
+
+##### `app.certified.defs#did`
+
+| Property | Type     | Required | Description           |
+| -------- | -------- | -------- | --------------------- |
+| `did`    | `string` | ✅       | The DID string value. |
+
+---
+
+## Type Definitions
+
+Common type definitions used across all protocols.
+
+### `org.hypercerts.defs`
+
+#### Defs
+
+##### `org.hypercerts.defs#uri`
+
+| Property | Type     | Required | Description          |
+| -------- | -------- | -------- | -------------------- |
+| `uri`    | `string` | ✅       | URI to external data |
+
+##### `org.hypercerts.defs#smallBlob`
+
+| Property | Type   | Required | Description                        |
+| -------- | ------ | -------- | ---------------------------------- |
+| `blob`   | `blob` | ✅       | Blob to external data (up to 10MB) |
+
+##### `org.hypercerts.defs#largeBlob`
+
+| Property | Type   | Required | Description                         |
+| -------- | ------ | -------- | ----------------------------------- |
+| `blob`   | `blob` | ✅       | Blob to external data (up to 100MB) |
+
+##### `org.hypercerts.defs#smallImage`
+
+| Property | Type   | Required | Description       |
+| -------- | ------ | -------- | ----------------- |
+| `image`  | `blob` | ✅       | Image (up to 5MB) |
+
+##### `org.hypercerts.defs#largeImage`
+
+| Property | Type   | Required | Description        |
+| -------- | ------ | -------- | ------------------ |
+| `image`  | `blob` | ✅       | Image (up to 10MB) |
+
+---
+
+## External Lexicons
+
+External lexicons from other protocols and systems.
+
+### `com.atproto.repo.strongRef`
+
+**Key:** `tid`
+
+---
+
 ## Notes
 
 - All timestamps use the `datetime` format (ISO 8601)