v0.10.0

hypercerts-release-bot released this 03 Mar 20:20

· 143 commits to main since this release

82ee279

Minor Changes

#76 3044e22 Thanks @s-adamantine! - Add org.hypercerts.acknowledgement lexicon for bidirectional inclusion links between records across PDS repos
#141 06fb6b5 Thanks @holkexyz! - Add CEL expression support for structured work scopes (org.hypercerts.workscope.cel, org.hypercerts.workscope.tag)
#106 b03a1f7 Thanks @copilot-swe-agent! - Add avatar and banner fields to collection lexicon for visual representation
#113 c3f9ca2 Thanks @holkexyz! - Refactor collection items structure to support optional weights and remove activityWeight from activity schema

Breaking Changes:
- Activity lexicon (org.hypercerts.claim.activity):
  - Removed org.hypercerts.claim.activity#activityWeight def
  - Activity records no longer include activity weight information
- Collection lexicon (org.hypercerts.claim.collection):
  - Changed org.hypercerts.claim.collection#items from array of strongRefs to array of item objects
  - Added org.hypercerts.claim.collection#item def with:
    - itemIdentifier (required): strongRef to an item (activity or collection)
    - itemWeight (optional): positive numeric value stored as string
  - Supports recursive collection nesting (items can reference activities or other collections)
Migration:

Collection items: Convert from array of strongRefs to array of item objects:
```
// Before
"items": [strongRef1, strongRef2]

// After
"items": [
  { "itemIdentifier": strongRef1, "itemWeight": "1.5" },
  { "itemIdentifier": strongRef2 }
]
```
Activity weights: Migrate existing org.hypercerts.claim.activity#activityWeight data to collection org.hypercerts.claim.collection#item.itemWeight:
```
// Old (removed from activity)
{ "activity": { "uri": "...", "cid": "..." }, "weight": "1.5" }

// New (in collection items)
{ "itemIdentifier": { "uri": "...", "cid": "..." }, "itemWeight": "1.5" }
```
Update collections that reference activities to include weights in org.hypercerts.claim.collection#item.itemWeight. Weights can be dropped if not needed.
#149 9f124eb Thanks @daviddao! - Add org.hyperboards.board and org.hyperboards.displayProfile lexicons for hyperboard visual presentation records.
#123 c623d32 Thanks @aspiers! - Add location property to collections. Collections can now reference a location record directly via strongRef. This replaces the sidecar pattern which was impractical since location records cannot be reused across multiple collections.
#140 20eb414 Thanks @holkexyz! - Add app.certified.actor.organization sidecar record for organization actor profiles with fields for organization type, labeled URLs, location (strongRef), and founded date
#133 6752cad Thanks @Kzoeps! - Add profile lexicon for Hypercert account profiles with support for display name, description, pronouns, website, avatar, banner.
#78 c55d8a7 Thanks @bitbeckers! - Remove org.hypercerts.claim.project lexicon and replace with org.hypercerts.claim.collection.project sidecar. Projects are now represented as collections with an optional project sidecar (same TID) that provides rich-text descriptions, avatars, and cover photos. Avatar and coverPhoto fields moved from base collection to project sidecar. Collections without the project sidecar are simple groupings; collections with it are "projects" with rich documentation.
#91 0c6da09 Thanks @holkexyz! - Add rich text facet support to activity claim descriptions

Add shortDescriptionFacets and descriptionFacets fields to the activity lexicon to support rich text annotations (mentions, URLs, hashtags, etc.) in activity claim descriptions.
#144 fb90134 Thanks @holkexyz! - Make items optional in collection schema to allow creating empty collections
#151 4d5f42f Thanks @holkexyz! - Add optional url field to app.certified.badge.award for linking to an external page associated with the badge
#122 3e3da41 Thanks @aspiers! - Drop HELPER_ prefix from workScopeTag constants. HELPER_WORK_SCOPE_TAG_NSID, HELPER_WORK_SCOPE_TAG_LEXICON_JSON, and HELPER_WORK_SCOPE_TAG_LEXICON_DOC are now WORK_SCOPE_TAG_NSID, WORK_SCOPE_TAG_LEXICON_JSON, and WORK_SCOPE_TAG_LEXICON_DOC.
#136 062fbde Thanks @copilot-swe-agent! - Expand locationType knownValues to include geojson, h3, geohash, wkt, address, and scaledCoordinates from the Location Protocol spec
#131 7f42fad Thanks @aspiers! - Add inline string format to app.certified.location schema with documentation and examples
#121 5c33b79 Thanks @aspiers! - Fix camelCase export names to use underscores. Generated constants like CONTRIBUTIONDETAILS_LEXICON_* are now CONTRIBUTION_DETAILS_LEXICON_* for consistency.

Affected exports:
- CONTRIBUTION_DETAILS_NSID, CONTRIBUTION_DETAILS_LEXICON_JSON, CONTRIBUTION_DETAILS_LEXICON_DOC (was CONTRIBUTIONDETAILS_*)
- CONTRIBUTOR_INFORMATION_NSID, CONTRIBUTOR_INFORMATION_LEXICON_JSON, CONTRIBUTOR_INFORMATION_LEXICON_DOC (was CONTRIBUTORINFORMATION_*)
- STRONG_REF_NSID, STRONG_REF_LEXICON_JSON, STRONG_REF_LEXICON_DOC (was STRONGREF_*)
- HELPER_WORK_SCOPE_TAG_NSID, HELPER_WORK_SCOPE_TAG_LEXICON_JSON, HELPER_WORK_SCOPE_TAG_LEXICON_DOC (was HELPER_WORKSCOPETAG_*)
#132 da481e0 Thanks @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 e134b26 Thanks @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.
#152 2afb6ed Thanks @holkexyz! - Use Leaflet linear documents for rich-text descriptions in activity and attachment lexicons, and make attachment content optional.
#161 96bdb6c Thanks @aspiers! - Improved exports structure with semantic collection mappings for extra syntactic sugar.

Breaking Changes:
- Renamed ids export to HYPERCERTS_NSIDS_BY_TYPE (maps type namespaces to NSIDs)
New Features:
- Added HYPERCERTS_NSIDS object with semantic keys (e.g., ACTIVITY, RIGHTS, CONTRIBUTION)
- Added HYPERCERTS_LEXICON_JSON object with semantic keys mapping to raw JSON lexicons
- Added HYPERCERTS_LEXICON_DOC object with semantic keys mapping to typed lexicon documents
- All three new objects share the same key structure for consistency
Migration Guide:

If you were using the ids export (rare):
```
// Before
import { ids } from "@hypercerts-org/lexicon";
const nsid = ids.OrgHypercertsClaimActivity;

// After
import { HYPERCERTS_NSIDS_BY_TYPE } from "@hypercerts-org/lexicon";
const nsid = HYPERCERTS_NSIDS_BY_TYPE.OrgHypercertsClaimActivity;
```
Most users should use individual NSID constants (unchanged):
```
import { ACTIVITY_NSID, RIGHTS_NSID } from "@hypercerts-org/lexicon";
```
Or the new semantic mapping:
```
import { HYPERCERTS_NSIDS } from "@hypercerts-org/lexicon";
const nsid = HYPERCERTS_NSIDS.ACTIVITY; // Same as ACTIVITY_NSID
```
#161 6a62c04 Thanks @aspiers! - This release represents the migration of the lexicon package from the SDK monorepo (hypercerts-sdk/packages/lexicon) to a dedicated standalone repository (hypercerts-lexicon). This separation allows for independent versioning and development of the lexicon definitions.

Major architectural and feature updates compared to the SDK lexicon package include but are not limited to the following:

New Lexicons:
- Activity model: org.hypercerts.claim.activity - activity-based hypercert records (replaces single claim model)
- Project records: org.hypercerts.claim.project - projects that group multiple activities
- Shared definitions: org.hypercerts.defs - common types (uri, smallBlob, largeBlob, smallImage, largeImage)
- Badge system: app.certified.badge.definition, app.certified.badge.award, app.certified.badge.response for badge-based endorsements
- Funding receipts: org.hypercerts.funding.receipt - payment and funding tracking
Architectural Changes:
- Claim model: Replaced single org.hypercerts.claim record with activity-based org.hypercerts.claim.activity model
- Collection model: Collections now reference activities (via activityWeight) instead of claims (via claimItem)
- Work scope: Activity model uses structured workScope object with label-based conditions (withinAllOf, withinAnyOf, withinNoneOf)
- Time fields: Activity uses startDate/endDate instead of workTimeFrameFrom/workTimeFrameTo
- Image references: Activity model references org.hypercerts.defs#smallImage instead of app.certified.defs#uri/smallBlob
Definition Updates:
- app.certified.defs now includes did type definition
- Added org.hypercerts.defs with image and blob type definitions
- Activity model references project via AT-URI instead of strongRef
Removed/Replaced:
- org.hypercerts.claim (replaced by org.hypercerts.claim.activity)
- Top-level org.hypercerts.collection (replaced by org.hypercerts.claim.collection using activities)
#153 57dc44c Thanks @holkexyz! - Improve acknowledgement schema: move to org.hypercerts.context.acknowledgement, generalize descriptions, make context optional, add maxGraphemes to comment.
#158 7743aa6 Thanks @holkexyz! - Move collection lexicon from org.hypercerts.claim.collection to org.hypercerts.collection to reflect that collections can contain more than just claims.
#154 4c52b2c Thanks @holkexyz! - Move evaluation and attachment lexicons to org.hypercerts.context namespace.
#135 806cfbc Thanks @Kzoeps! - Move profile lexicon from app.certified.profile to app.certified.actor.profile namespace, requiring migration of existing profile records
#97 ceddab9 Thanks @aspiers! - Move schema documentation tables from README.md to auto-generated SCHEMAS.md to reduce git merge conflicts. The SCHEMAS.md file is now auto-generated from lexicon definitions and included in the distributed package.
#102 68011ae Thanks @holkexyz! - Refactor contributions structure in activity lexicon

Breaking Changes:
- Activity lexicon (org.hypercerts.claim.activity):
  - Renamed contributions field to contributors
  - Replaced contributions array (array of strongRefs) with new contributors array containing contributor objects
  - Each contributor object (org.hypercerts.claim.activity#contributor) has three fields:
    - contributorIdentity (required): string (DID/identifier) or strongRef to a contributor information record
    - contributionWeight (optional): positive numeric value stored as string
    - contributionDetails (optional): string or strongRef to a contribution details record
  - Added internal defs:
    - #contributor: object type for contributor entries
    - #contributorIdentity: string type for DID/identifier values
    - #contributorRole: string type for contribution details (maxLength 10000, maxGraphemes 1000)
Migration:

Convert from array of strongRefs to array of contributor objects:
```
// Before
"contributions": [strongRef1, strongRef2]

// After
"contributors": [
  {
    "contributorIdentity": "did:example:123",
    "contributionWeight": "1.5",
    "contributionDetails": "Lead developer"
  },
  {
    "contributorIdentity": strongRefToContributorInfo,
    "contributionDetails": strongRefToContributionDetails
  }
]
```
#120 b2f7b68 Thanks @holkexyz! - Refactor measurement lexicon schema: convert subject to subjects array, add unit field, date ranges, and locations array

Breaking Changes:
- Measurement lexicon (org.hypercerts.context.measurement):
  - Changed subject (single strongRef) to subjects (array of strongRefs, maxLength: 100)
  - 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
#67 b51dd76 Thanks @bitbeckers! - Remove bidirectional project-activity link. Activities no longer include a project field reference. Projects continue to reference activities via the activities array, making the relationship unidirectional (project → activities only).
#98 43b0431 Thanks @aspiers! - Remove org.hypercerts.claim.collection.project lexicon
#155 a59e541 Thanks @holkexyz! - Rename contributionDetails to contribution (org.hypercerts.claim.contribution).
#118 8427780 Thanks @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:
```
// 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)
#156 86f252d Thanks @holkexyz! - Require createdAt in app.certified.actor.profile schema
#161 ec91289 Thanks @aspiers! - chore: switch to build via rollup

Major build system improvements:
- Build System: Migrated from direct TypeScript to Rollup-based builds
  - Generates proper ESM (dist/index.mjs) and CommonJS (dist/index.cjs) bundles
  - Generates TypeScript declarations (dist/index.d.ts)
  - Includes source maps for debugging
  - Adds /lexicons export for lighter bundle (validation only)
- Code Generation:
  - Auto-generates generated/exports.ts with clean, organized exports
  - Creates type shims for external lexicons (@atcute/leaflet)
  - All generated code now in generated/ directory (gitignored)
- Package Exports:
  - Main export: @hypercerts-org/lexicon (full package with types)
  - Lexicons export: @hypercerts-org/lexicon/lexicons (schemas only, smaller bundle)
  - Proper dual package support (ESM + CommonJS)
- Code Quality:
  - Added ESLint configuration
  - Added TypeScript type-checking to CI
  - Improved build validation workflow
- Dependencies:
  - Added @atcute/leaflet for external lexicon references
  - Added multiformats as runtime dependency
  - Moved @atproto/lex-cli to devDependencies (build-time only)
Migration: No breaking changes for existing users. Package structure is improved
but import paths remain compatible.
#125 771d142 Thanks @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.
#47 6a66e4b Thanks @satyam-mishra-pce! - Add support for multiple locations in an activity claim.
#103 b5d79da Thanks @s-adamantine! - Align all lexicons with the ATProto Lexicon Style Guide: change badge response enum to knownValues, add maxLength/maxGraphemes to unconstrained string and array fields, fix style checker to skip format-typed fields.
#75 95e2ba1 Thanks @s-adamantine! - Unify project and collection schemas into a single
org.hypercerts.claim.collection lexicon with type discriminator
field to allow collections to be designated as projects. Custom
strings are also allowed in type.

Also make shortDescription field optional in
org.hypercerts.claim.collection to match
org.hypercerts.claim.project.

This unification removes org.hypercerts.claim.project, so existing
projects should be migrated to collections with type set to
project.
#80 e8d5a7c Thanks @s-adamantine! - Updated org.hypercerts.claim.collection lexicon:
- Added optional type field to specify collection type (e.g., 'favorites', 'project')
- Renamed fields for consistency:
  - collectionTitle → title
  - shortCollectionDescription → shortDescription
  - collectionDescription → description
- Changed description from string to Leaflet linear document reference (pub.leaflet.pages.linearDocument#main) to support rich-text descriptions
Breaking changes:
- Field names have been renamed (e.g., collectionTitle → title)
- The description field now expects a reference object instead of a plain string
#92 bec8e63 Thanks @s-adamantine! - Update org.hypercerts.claim.contributor lexicon to support individual contributor profiles and roles.

Breaking Changes:
- Removed contributors array.
- Added identifier, displayName, and image fields for individual profiles.
- Renamed description to contributionDescription.
- Updated required fields to only include createdAt.
Also corrected incorrect references to org.hypercerts.claim.contribution across the codebase to use the correct ID org.hypercerts.claim.contributor.

Patch Changes

#118 8427780 Thanks @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:
```
{
  "$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.
#161 5a490bf Thanks @aspiers! - Add basic test suite using vitest 4.
#77 0d61ff7 Thanks @bitbeckers! - Document ATProto sidecar pattern for collections using app.certified.location. Collections can now have location metadata by creating a location record with the same TID, allowing location updates without changing the collection CID. Updated README with usage example and ERD with sidecar relationship.
#161 ece7629 Thanks @aspiers! - Include CHANGELOG.md in package distribution for better user documentation.
#74 f845f92 Thanks @aspiers! - Make startDate and endDate optional in activity lexicon
#161 913eb06 Thanks @aspiers! - Switch from bundled to individual type declaration files

Changes:
- Removed rollup-plugin-dts dependency
- Switched to native TypeScript declaration generation
- Type declarations now mirror source structure in dist/types/
- Individual type files are small (1-3KB each) and lazy-loaded by TypeScript
- Improves IDE performance by avoiding single 39MB bundled declaration file
Technical Details:

The package now generates individual .d.ts files alongside the bundled JavaScript
output. This provides better IDE performance as TypeScript can lazy-load type files
on demand rather than parsing a massive bundled declaration file upfront.

Assets 2