@hypercerts-org/lexicon 0.10.0-beta.11 → 0.10.0-beta.13

package/CHANGELOG.md

@@ -1,5 +1,171 @@
 # @hypercerts-org/lexicon
 
+## 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
+
+- [#120](https://github.com/hypercerts-org/hypercerts-lexicon/pull/120) [`b2f7b68`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/b2f7b683ac17f07a891a59ee8289d26717197ba3) Thanks [@holkexyz](https://github.com/holkexyz)! - Refactor measurement lexicon schema: add unit field, date ranges, and locations array
+
+  **Breaking Changes:**
+  - **Measurement lexicon (`org.hypercerts.claim.measurement`):**
+    - Changed required fields: removed `measurers` from required, added `unit` as required
+    - Added `unit` field (required, string, maxLength: 50): The unit of the measured value (e.g. kg CO₂e, hectares, %, index score)
+    - Added `startDate` field (optional, datetime): The start date and time when the measurement began
+    - Added `endDate` field (optional, datetime): The end date and time when the measurement ended
+    - Changed `location` (single strongRef) to `locations` (array of strongRefs, maxLength: 100)
+    - Moved `measurers` from required to optional field
+    - Added `comment` field (optional, string): Short comment suitable for previews and list views
+    - Added `commentFacets` field (optional, array): Rich text annotations for `comment` (mentions, URLs, hashtags, etc.)
+    - Updated field descriptions for `metric` and `value` with more detailed examples
+
+  **Migration:**
+
+  **Required fields:** Update measurement records to include the new required `unit` field:
+
+  ```json
+  // Before
+  {
+    "$type": "org.hypercerts.claim.measurement",
+    "measurers": [...],
+    "metric": "CO₂ sequestered",
+    "value": "1000",
+    "createdAt": "..."
+  }
+
+  // After
+  {
+    "$type": "org.hypercerts.claim.measurement",
+    "metric": "CO₂ sequestered",
+    "unit": "kg CO₂e",
+    "value": "1000",
+    "measurers": [...],  // Now optional
+    "createdAt": "..."
+  }
+  ```
+
+  **Location field:** Convert from single location to locations array:
+
+  ```json
+  // Before
+  {
+    "location": { "uri": "...", "cid": "..." }
+  }
+
+  // After
+  {
+    "locations": [{ "uri": "...", "cid": "..." }]
+  }
+  ```
+
+  **Date ranges:** Optionally add `startDate` and `endDate` to specify when measurements were taken.
+
+- [#125](https://github.com/hypercerts-org/hypercerts-lexicon/pull/125) [`771d142`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/771d14269ced86ea686cb6dac3414a7a283c482a) Thanks [@s-adamantine](https://github.com/s-adamantine)! - Simplify workScope to union of strongRef and string
+
+  **Breaking Changes:**
+  - The `workScope` field in `org.hypercerts.claim.activity` is now a union of:
+    - `com.atproto.repo.strongRef`: A reference to a work-scope logic record for structured, nested work scope definitions
+    - `org.hypercerts.claim.activity#workScopeString`: A free-form string for simple or legacy scopes
+  - **Removed** from `org.hypercerts.defs`:
+    - `workScopeAll` (logical AND operator)
+    - `workScopeAny` (logical OR operator)
+    - `workScopeNot` (logical NOT operator)
+    - `workScopeAtom` (atomic scope reference)
+
+  This simplification allows work scope complexity to be managed via referenced records while still supporting simple string-based scopes for straightforward use cases.
+
 ## 0.10.0-beta.11
 
 ### Minor Changes

package/README.md

@@ -65,10 +65,12 @@ const activityRecord = {
   $type: ACTIVITY_NSID,
   title: "My Impact Work",
   shortDescription: "Description here",
+  // workScope can be a strongRef to a work-scope record:
   workScope: {
-    uri: "at://did:plc:alice/org.hypercerts.claim.workscope/abc123",
+    uri: "at://did:plc:alice/org.hypercerts.helper.workScopeTag/abc123",
     cid: "...",
   },
+  // OR a simple string: workScope: "Environmental conservation",
   startDate: "2023-01-01T00:00:00Z",
   endDate: "2023-12-31T23:59:59Z",
   createdAt: new Date().toISOString(),
@@ -87,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:
@@ -320,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(),
+};
+```