-
Notifications
You must be signed in to change notification settings - Fork 3
docs: add plan to sync SDK up to lexicons beta.13 #117
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,266 @@ | ||
| # Lexicon Sync Plan: v0.10.0-beta.11 → v0.10.0-beta.13 | ||
|
|
||
| This document outlines the step-by-step plan for syncing the SDK with the latest lexicon changes, following on from | ||
| `v0.10.0-beta.4-v0.10.0-beta.11.md`. | ||
|
|
||
| Each change must be implemented, validated, and reviewed before proceeding to the next. | ||
|
|
||
| ## Current Status | ||
|
|
||
| - **Old version**: 0.10.0-beta.11 | ||
| - **New version**: 0.10.0-beta.13 | ||
| - **Dependency updated**: ⏳ Not yet | ||
| - **Build status**: ⏳ Not yet tested | ||
| - **Test status**: ⏳ Not yet tested | ||
|
|
||
| ## Changes to Implement | ||
|
|
||
| ### Change 1: Simplify workScope to union of strongRef and string (beta.12) | ||
|
|
||
| **CHANGELOG Reference**: PR #125 - Simplify workScope to union of strongRef and string | ||
|
|
||
| **What Changed**: | ||
|
|
||
| - 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. | ||
|
|
||
| **SDK Tasks**: | ||
|
|
||
| - [ ] Remove type exports that were added for work scope expression types: | ||
| - Remove `HypercertWorkScopeAll` type (if it exists) | ||
| - Remove `HypercertWorkScopeAny` type (if it exists) | ||
| - Remove `HypercertWorkScopeNot` type (if it exists) | ||
| - Remove `HypercertWorkScopeAtom` type (if it exists) | ||
| - Remove `HypercertWorkScopeExpression` union type (if it exists) | ||
| - [ ] Remove type exports for work scope tag (if they exist): | ||
| - Remove `CreateWorkScopeTagParams` (if it exists) | ||
| - Remove `UpdateWorkScopeTagParams` (if it exists) | ||
| - Remove `WorkScopeTagParams` (if it exists) | ||
| - [ ] Verify `CreateHypercertParams.workScope` supports the new union type (string | StrongRef) | ||
| - [ ] Update documentation about work scope to reflect the simplified approach | ||
| - [ ] Update usage examples to show: | ||
| - Simple string-based work scope | ||
| - StrongRef to a work scope logic record | ||
| - [ ] Update/remove tests for work scope expressions (they should now reference external records) | ||
| - [ ] Build and test | ||
| - [ ] Create changeset (major - breaking change, removed types) | ||
|
|
||
| **Validation**: | ||
|
|
||
| - [ ] Format check passes (`pnpm format:check`) | ||
| - [ ] Lint passes (`pnpm lint`) | ||
| - [ ] Typecheck passes (`pnpm typecheck`) | ||
| - [ ] Build passes (`pnpm build`) | ||
| - [ ] Tests pass (`pnpm test`) | ||
| - [ ] Types export correctly | ||
| - [ ] Work scope types are correct (string | StrongRef) | ||
|
|
||
| **Status**: ⏳ Pending | ||
|
|
||
| --- | ||
|
|
||
| ### Change 2: Refactor measurement lexicon schema (beta.12) | ||
|
|
||
| **CHANGELOG Reference**: PR #120 - Refactor measurement lexicon schema: add unit field, date ranges, and locations array | ||
|
|
||
| **What Changed**: | ||
|
|
||
| - 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 | ||
|
|
||
| **SDK Tasks**: | ||
|
|
||
| - [ ] Update `CreateMeasurementParams` type to reflect: | ||
| - `unit` is now required | ||
| - `measurers` is now optional | ||
| - `location` renamed to `locations` (array of StrongRef/LocationParams) | ||
| - Add `startDate` (optional datetime) | ||
| - Add `endDate` (optional datetime) | ||
| - Add `comment` (optional string) | ||
| - Add `commentFacets` (optional array of RichTextFacet) | ||
| - [ ] Update `UpdateMeasurementParams` accordingly | ||
| - [ ] Update `createMeasurement()` method to handle new required `unit` field | ||
| - [ ] Update `createMeasurement()` and `updateMeasurement()` methods to handle `locations` array | ||
| - [ ] Add JSDoc documentation about the new fields (unit, startDate, endDate, comment, commentFacets) | ||
| - [ ] Add usage examples showing: | ||
| - Creating measurements with unit (required) | ||
| - Adding date ranges (startDate/endDate) | ||
| - Using locations array | ||
| - Adding comments with facets | ||
| - [ ] Add/update tests for measurements with new fields | ||
| - [ ] Build and test | ||
| - [ ] Create changeset (major - breaking change, required field added, location → locations) | ||
|
|
||
| **Validation**: | ||
|
|
||
| - [ ] Format check passes (`pnpm format:check`) | ||
| - [ ] Lint passes (`pnpm lint`) | ||
| - [ ] Typecheck passes (`pnpm typecheck`) | ||
| - [ ] Build passes (`pnpm build`) | ||
| - [ ] Tests pass (`pnpm test`) | ||
| - [ ] Types export correctly | ||
|
|
||
| **Status**: ⏳ Pending | ||
|
|
||
| --- | ||
|
|
||
| ### Change 3: Rename evidence lexicon to attachment (beta.13) | ||
|
|
||
| **CHANGELOG Reference**: PR #118 - Rename evidence lexicon to attachment and refactor schema structure | ||
|
|
||
| **What Changed**: | ||
|
|
||
| - **Lexicon ID change:** | ||
| - `org.hypercerts.claim.evidence` → `org.hypercerts.claim.attachment` | ||
| - **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 | ||
| - Added `location` field (optional strongRef) to associate location metadata | ||
| - 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 | ||
|
|
||
| **SDK Tasks**: | ||
|
|
||
| - [ ] Rename all SDK references from "evidence" to "attachment": | ||
| - Type exports: `HypercertEvidence` → `HypercertAttachment` | ||
| - Type exports: `CreateEvidenceParams` → `CreateAttachmentParams` | ||
| - Type exports: `UpdateEvidenceParams` → `UpdateAttachmentParams` | ||
| - Type exports: `EvidenceParams` → `AttachmentParams` | ||
| - Interface methods (if they exist): `createEvidence` → `createAttachment` | ||
| - Interface methods (if they exist): `updateEvidence` → `updateAttachment` | ||
| - Interface methods (if they exist): `deleteEvidence` → `deleteAttachment` | ||
| - Interface methods (if they exist): `listEvidence` → `listAttachments` | ||
| - [ ] Update `CreateAttachmentParams` type to reflect: | ||
| - `subject` → `subjects` (array of StrongRef/ActivityParams/CollectionParams) | ||
| - `content` is now array of unions (uri/blob) and required | ||
| - Add `contentType` (optional string) | ||
| - Add `location` (optional StrongRef/LocationParams) | ||
| - Remove `relationType` | ||
| - Remove `contributors` | ||
| - Remove `locations` (note: there's a new singular `location` field) | ||
| - Add `shortDescriptionFacets` (optional array) | ||
| - Add `descriptionFacets` (optional array) | ||
| - [ ] Update `UpdateAttachmentParams` accordingly | ||
| - [ ] Add type exports for new common definitions: | ||
| - `HypercertWeightedContributor` = `OrgHypercertsDefs.WeightedContributor` | ||
| - `HypercertContributorIdentity` = `OrgHypercertsDefs.ContributorIdentity` | ||
| - [ ] Update CRUD methods to handle schema changes | ||
| - [ ] Add JSDoc documentation about attachment fields and migration from evidence | ||
| - [ ] Add usage examples showing: | ||
| - Creating attachments with subjects array | ||
| - Using content array with contentType | ||
| - Adding location to attachments | ||
| - Using weighted contributors | ||
| - [ ] Add/update tests for attachments | ||
| - [ ] Build and test | ||
| - [ ] Create changeset (major - breaking change, renamed lexicon and schema changes) | ||
|
|
||
| **Validation**: | ||
|
|
||
| - [ ] Format check passes (`pnpm format:check`) | ||
| - [ ] Lint passes (`pnpm lint`) | ||
| - [ ] Typecheck passes (`pnpm typecheck`) | ||
| - [ ] Build passes (`pnpm build`) | ||
| - [ ] Tests pass (`pnpm test`) | ||
| - [ ] Types export correctly | ||
|
|
||
| **Status**: ⏳ Pending | ||
|
|
||
| --- | ||
|
|
||
| ### Change 4: Add inline string format to app.certified.location (beta.13) | ||
|
|
||
| **CHANGELOG Reference**: PR #131 - Add inline string format to app.certified.location schema with documentation and | ||
| examples | ||
|
|
||
| **What Changed**: | ||
|
|
||
| - `app.certified.location` now supports inline string format in addition to the structured object format | ||
| - This allows locations to be specified as simple strings for convenience | ||
|
|
||
| **SDK Tasks**: | ||
|
|
||
| - [ ] Verify `CreateLocationParams` supports both string and structured object format | ||
| - [ ] Update `createLocation()` method to handle string format | ||
| - [ ] Update documentation to show both formats: | ||
| - Simple string format: `"New York, NY, USA"` | ||
| - Structured object format: `{ country: "USA", city: "New York", ... }` | ||
| - [ ] Add usage examples for both formats | ||
| - [ ] Add tests for location string format | ||
| - [ ] Build and test | ||
| - [ ] Create changeset (minor - new feature, backward compatible) | ||
|
|
||
| **Validation**: | ||
|
|
||
| - [ ] Format check passes (`pnpm format:check`) | ||
| - [ ] Lint passes (`pnpm lint`) | ||
| - [ ] Typecheck passes (`pnpm typecheck`) | ||
| - [ ] Build passes (`pnpm build`) | ||
| - [ ] Tests pass (`pnpm test`) | ||
| - [ ] Types export correctly | ||
|
|
||
| **Status**: ⏳ Pending | ||
|
|
||
| --- | ||
|
|
||
| ### Change 5: Update dependency and final validation | ||
|
|
||
| **Tasks**: | ||
|
|
||
| - [ ] Update `@hypercerts-org/lexicon` dependency from `0.10.0-beta.11` to `0.10.0-beta.13` in | ||
| `packages/sdk-core/package.json` | ||
| - [ ] Run `pnpm install` to update the dependency | ||
| - [ ] Review all individual changesets created in steps 1-4 | ||
| - [ ] Consider whether they should be combined into a single changeset or kept separate | ||
| - [ ] Update any top-level documentation if needed | ||
| - [ ] Final build and test of entire SDK | ||
| - [ ] Prepare summary of all changes for user review | ||
|
|
||
| **Validation**: | ||
|
|
||
| - [ ] Format check passes (`pnpm format:check`) | ||
| - [ ] Lint passes (`pnpm lint`) | ||
| - [ ] Typecheck passes (`pnpm typecheck`) | ||
| - [ ] All builds pass (`pnpm build` - sdk-core and sdk-react) | ||
| - [ ] All tests pass (`pnpm test`) | ||
| - [ ] Changesets are properly formatted | ||
| - [ ] Documentation is complete | ||
|
|
||
| **Status**: ⏳ Pending | ||
|
|
||
| --- | ||
|
|
||
| ## Notes | ||
|
|
||
| - **Breaking changes**: This sync includes several major breaking changes: | ||
| 1. WorkScope simplified to union of string | StrongRef (removes complex expression types) | ||
| 2. Measurement `unit` field now required, `location` → `locations` array | ||
| 3. Evidence lexicon renamed to Attachment with schema changes | ||
| - Each change will be implemented, validated, and reviewed before proceeding to the next | ||
| - The evidence → attachment rename is particularly significant and will require careful migration | ||
| - Work scope simplification reverses the complexity added in beta.8, so we may need to remove code that was added in the | ||
| previous sync | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The PR title states "add plan to sync SDK up to lexicons beta.13" but should use "lexicon" (singular) not "lexicons" (plural) to match the consistent terminology used throughout the codebase and this document. The dependency package is "@hypercerts-org/lexicon" and all references in the document use "lexicon" in singular form.