From df1f02f1556db56f33132b004cc1f9bae62fea3a Mon Sep 17 00:00:00 2001 From: holkexyz Date: Wed, 25 Feb 2026 11:32:15 +0100 Subject: [PATCH] feat: reorganize lexicon folder structure into semantic namespaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure lexicons into purpose-driven namespaces: - app.certified.location → app.certified.geo.location - org.hypercerts.claim.{attachment,evaluation,measurement} → org.hypercerts.context.* - org.hypercerts.acknowledgement → org.hypercerts.graph.acknowledgement - org.hypercerts.claim.collection → org.hypercerts.curation.collection - org.hypercerts.helper.workScopeTag → org.hypercerts.ontology.workScopeTag Updated all description cross-references, ERD comments, and SCHEMAS.md. Co-Authored-By: Claude Opus 4.6 --- .changeset/reorganize-lexicon-folders.md | 5 + ERD.puml | 12 +- SCHEMAS.md | 294 ++++++++++-------- .../app/certified/{ => geo}/location.json | 2 +- lexicons/org/hypercerts/claim/activity.json | 4 +- .../{claim => context}/attachment.json | 4 +- .../{claim => context}/evaluation.json | 6 +- .../{claim => context}/measurement.json | 4 +- .../{claim => curation}/collection.json | 6 +- .../{ => graph}/acknowledgement.json | 2 +- .../{helper => ontology}/workScopeTag.json | 2 +- scripts/generate-schemas.js | 2 +- 12 files changed, 194 insertions(+), 149 deletions(-) create mode 100644 .changeset/reorganize-lexicon-folders.md rename lexicons/app/certified/{ => geo}/location.json (98%) rename lexicons/org/hypercerts/{claim => context}/attachment.json (96%) rename lexicons/org/hypercerts/{claim => context}/evaluation.json (95%) rename lexicons/org/hypercerts/{claim => context}/measurement.json (97%) rename lexicons/org/hypercerts/{claim => curation}/collection.json (94%) rename lexicons/org/hypercerts/{ => graph}/acknowledgement.json (97%) rename lexicons/org/hypercerts/{helper => ontology}/workScopeTag.json (97%) diff --git a/.changeset/reorganize-lexicon-folders.md b/.changeset/reorganize-lexicon-folders.md new file mode 100644 index 00000000..843c5aa3 --- /dev/null +++ b/.changeset/reorganize-lexicon-folders.md @@ -0,0 +1,5 @@ +--- +"@hypercerts-org/lexicon": minor +--- + +Reorganize lexicon folder structure into semantic namespaces: location to app.certified.geo, attachment/evaluation/measurement to org.hypercerts.context, acknowledgement to org.hypercerts.graph, collection to org.hypercerts.curation, workScopeTag to org.hypercerts.ontology diff --git a/ERD.puml b/ERD.puml index 574e502f..72d9f36b 100644 --- a/ERD.puml +++ b/ERD.puml @@ -69,7 +69,7 @@ dataclass activity <> #B4E5D0 { !endif } -' org.hypercerts.claim.attachment +' org.hypercerts.context.attachment dataclass attachment { !if (SHOW_FIELDS == "true") subjects[]? @@ -83,7 +83,7 @@ dataclass attachment { !endif } -' org.hypercerts.claim.measurement +' org.hypercerts.context.measurement dataclass measurement { !if (SHOW_FIELDS == "true") subject? @@ -98,7 +98,7 @@ dataclass measurement { !endif } -' org.hypercerts.claim.evaluation +' org.hypercerts.context.evaluation dataclass evaluation { !if (SHOW_FIELDS == "true") subject? @@ -133,7 +133,7 @@ dataclass contributionDetails { !endif } -' app.certified.location +' app.certified.geo.location dataclass location { !if (SHOW_FIELDS == "true") lpVersion @@ -187,7 +187,7 @@ dataclass rights { !endif } -' org.hypercerts.claim.collection +' org.hypercerts.curation.collection dataclass collection { !if (SHOW_FIELDS == "true") type? @@ -200,7 +200,7 @@ dataclass collection { !endif } -' org.hypercerts.acknowledgement +' org.hypercerts.graph.acknowledgement dataclass acknowledgement { !if (SHOW_FIELDS == "true") subject diff --git a/SCHEMAS.md b/SCHEMAS.md index a638d21b..bbe3381a 100644 --- a/SCHEMAS.md +++ b/SCHEMAS.md @@ -7,24 +7,6 @@ Hypercerts-specific lexicons for tracking impact work and claims. -### `org.hypercerts.acknowledgement` - -**Description:** Acknowledges the inclusion of one record (subject) within another (context). Typically created in the subject owner's repo to form a bidirectional link. For example, a contributor acknowledging inclusion in an activity, or an activity owner acknowledging inclusion in a collection. - -**Key:** `tid` - -#### Properties - -| Property | Type | Required | Description | Comments | -| -------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -| `subject` | `ref` | ✅ | The record whose inclusion is being acknowledged (e.g. an activity, a contributor information record). | | -| `context` | `ref` | ✅ | The record that includes the subject (e.g. a collection/project that includes an activity, or an activity that includes a contributor). | | -| `acknowledged` | `boolean` | ✅ | Whether inclusion is acknowledged (true) or rejected (false). | | -| `comment` | `string` | ❌ | Optional comment providing additional context or reasoning. | maxLength: 1000 | -| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created. | | - ---- - ### `org.hypercerts.claim.activity` **Description:** A hypercert record tracking impact work. @@ -33,21 +15,21 @@ Hypercerts-specific lexicons for tracking impact work and claims. #### Properties -| Property | Type | Required | Description | Comments | -| ------------------------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | -| `title` | `string` | ✅ | Title of the hypercert. | maxLength: 256 | -| `shortDescription` | `string` | ✅ | Short summary of this activity claim, suitable for previews and list views. Rich text annotations may be provided via `shortDescriptionFacets`. | maxLength: 3000, maxGraphemes: 300 | -| `shortDescriptionFacets` | `ref` | ❌ | Rich text annotations for `shortDescription` (mentions, URLs, hashtags, etc). | | -| `description` | `string` | ❌ | Optional longer description of this activity claim, including context or interpretation. Rich text annotations may be provided via `descriptionFacets`. | maxLength: 30000, maxGraphemes: 3000 | -| `descriptionFacets` | `ref` | ❌ | Rich text annotations for `description` (mentions, URLs, hashtags, etc). | | -| `image` | `union` | ❌ | The hypercert visual representation as a URI or image blob. | | -| `workScope` | `union` | ❌ | Work scope definition. Either a strongRef to a work-scope logic record (structured, nested logic), or a free-form string for simple or legacy scopes. The work scope record should conform to the org.hypercerts.helper.workScopeTag lexicon. | | -| `startDate` | `string` | ❌ | When the work began | | -| `endDate` | `string` | ❌ | When the work ended | | -| `contributors` | `ref` | ❌ | An array of contributor objects, each containing contributor information, weight, and contribution details. | | -| `rights` | `ref` | ❌ | A strong reference to the rights that this hypercert has. The record referenced must conform with the lexicon org.hypercerts.claim.rights. | | -| `locations` | `ref` | ❌ | An array of strong references to the location where activity was performed. The record referenced must conform with the lexicon app.certified.location. | | -| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | +| Property | Type | Required | Description | Comments | +| ------------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| `title` | `string` | ✅ | Title of the hypercert. | maxLength: 256 | +| `shortDescription` | `string` | ✅ | Short summary of this activity claim, suitable for previews and list views. Rich text annotations may be provided via `shortDescriptionFacets`. | maxLength: 3000, maxGraphemes: 300 | +| `shortDescriptionFacets` | `ref` | ❌ | Rich text annotations for `shortDescription` (mentions, URLs, hashtags, etc). | | +| `description` | `string` | ❌ | Optional longer description of this activity claim, including context or interpretation. Rich text annotations may be provided via `descriptionFacets`. | maxLength: 30000, maxGraphemes: 3000 | +| `descriptionFacets` | `ref` | ❌ | Rich text annotations for `description` (mentions, URLs, hashtags, etc). | | +| `image` | `union` | ❌ | The hypercert visual representation as a URI or image blob. | | +| `workScope` | `union` | ❌ | Work scope definition. Either a strongRef to a work-scope logic record (structured, nested logic), or a free-form string for simple or legacy scopes. The work scope record should conform to the org.hypercerts.ontology.workScopeTag lexicon. | | +| `startDate` | `string` | ❌ | When the work began | | +| `endDate` | `string` | ❌ | When the work ended | | +| `contributors` | `ref` | ❌ | An array of contributor objects, each containing contributor information, weight, and contribution details. | | +| `rights` | `ref` | ❌ | A strong reference to the rights that this hypercert has. The record referenced must conform with the lexicon org.hypercerts.claim.rights. | | +| `locations` | `ref` | ❌ | An array of strong references to the location where activity was performed. The record referenced must conform with the lexicon app.certified.geo.location. | | +| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | #### Defs @@ -79,96 +61,83 @@ Hypercerts-specific lexicons for tracking impact work and claims. --- -### `org.hypercerts.claim.attachment` +### `org.hypercerts.claim.contributionDetails` -**Description:** An attachment providing commentary, context, evidence, or documentary material related to a hypercert record (e.g. an activity, project, claim, or evaluation). +**Description:** Details about a specific contribution including role, description, and timeframe. **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. | | +| 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.collection` +### `org.hypercerts.claim.contributorInformation` -**Description:** A collection/group of items (activities and/or other collections). Collections support recursive nesting. +**Description:** Contributor information including identifier, display name, and image. **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. | +| 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.contributionDetails` +### `org.hypercerts.claim.rights` -**Description:** Details about a specific contribution including role, description, and timeframe. +**Description:** Describes the rights that a contributor and/or an owner has, such as whether the hypercert can be sold, transferred, and under what conditions. **Key:** `tid` #### Properties -| Property | Type | Required | Description | Comments | -| ------------------------- | -------- | -------- | ------------------------------------------------------------------------------------ | ------------------------------------ | -| `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. | | +| Property | Type | Required | Description | Comments | +| ------------------- | -------- | -------- | ------------------------------------------------------------------ | -------------- | +| `rightsName` | `string` | ✅ | Full name of the rights | maxLength: 100 | +| `rightsType` | `string` | ✅ | Short rights identifier for easier search | maxLength: 10 | +| `rightsDescription` | `string` | ✅ | Description of the rights of this hypercert | | +| `attachment` | `union` | ❌ | An attachment to define the rights further, e.g. a legal document. | | +| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | --- -### `org.hypercerts.claim.contributorInformation` +### `org.hypercerts.context.attachment` -**Description:** Contributor information including identifier, display name, and image. +**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 | -| ------------- | -------- | -------- | ------------------------------------------------------------------ | -------------- | -| `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. | | +| 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.geo.location. | | +| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created. | | --- -### `org.hypercerts.claim.evaluation` +### `org.hypercerts.context.evaluation` **Description:** An evaluation of a hypercert record (e.g. an activity and its impact). @@ -176,20 +145,20 @@ Hypercerts-specific lexicons for tracking impact work and claims. #### Properties -| Property | Type | Required | Description | Comments | -| -------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -| `subject` | `ref` | ❌ | A strong reference to what is being evaluated. (e.g activity, measurement, contribution, etc.) | | -| `evaluators` | `ref` | ✅ | DIDs of the evaluators | maxLength: 1000 | -| `content` | `union` | ❌ | Evaluation data (URIs or blobs) containing detailed reports or methodology | maxLength: 100 | -| `measurements` | `ref` | ❌ | Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.claim.measurement | maxLength: 100 | -| `summary` | `string` | ✅ | Brief evaluation summary | maxLength: 5000, maxGraphemes: 1000 | -| `score` | `ref` | ❌ | Overall score for an evaluation on a numeric scale. | | -| `location` | `ref` | ❌ | An optional reference for georeferenced evaluations. The record referenced must conform with the lexicon app.certified.location. | | -| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | +| Property | Type | Required | Description | Comments | +| -------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| `subject` | `ref` | ❌ | A strong reference to what is being evaluated. (e.g activity, measurement, contribution, etc.) | | +| `evaluators` | `ref` | ✅ | DIDs of the evaluators | maxLength: 1000 | +| `content` | `union` | ❌ | Evaluation data (URIs or blobs) containing detailed reports or methodology | maxLength: 100 | +| `measurements` | `ref` | ❌ | Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.context.measurement | maxLength: 100 | +| `summary` | `string` | ✅ | Brief evaluation summary | maxLength: 5000, maxGraphemes: 1000 | +| `score` | `ref` | ❌ | Overall score for an evaluation on a numeric scale. | | +| `location` | `ref` | ❌ | An optional reference for georeferenced evaluations. The record referenced must conform with the lexicon app.certified.geo.location. | | +| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | #### Defs -##### `org.hypercerts.claim.evaluation#score` +##### `org.hypercerts.context.evaluation#score` | Property | Type | Required | Description | | -------- | --------- | -------- | -------------------------------------------- | @@ -199,7 +168,7 @@ Hypercerts-specific lexicons for tracking impact work and claims. --- -### `org.hypercerts.claim.measurement` +### `org.hypercerts.context.measurement` **Description:** Measurement data related to a hypercert record (e.g. an activity and its impact). @@ -207,40 +176,53 @@ Hypercerts-specific lexicons for tracking impact work and claims. #### Properties -| Property | Type | Required | Description | Comments | -| --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| `subject` | `ref` | ❌ | A strong reference to the record this measurement refers to (e.g. an activity, project, or claim). | | -| `metric` | `string` | ✅ | The metric being measured, e.g. forest area restored, number of users, etc. | maxLength: 500 | -| `unit` | `string` | ✅ | The unit of the measured value (e.g. kg CO₂e, hectares, %, index score). | maxLength: 50 | -| `value` | `string` | ✅ | The measured numeric value. | maxLength: 500 | -| `startDate` | `string` | ❌ | The start date and time when the measurement began. | | -| `endDate` | `string` | ❌ | The end date and time when the measurement ended. If it was a one time measurement, the endDate should be equal to the startDate. | | -| `locations` | `ref` | ❌ | Optional geographic references related to where the measurement was taken. Each referenced record must conform with the app.certified.location lexicon. | maxLength: 100 | -| `methodType` | `string` | ❌ | Short identifier for the measurement methodology | maxLength: 30 | -| `methodURI` | `string` | ❌ | URI to methodology documentation, standard protocol, or measurement procedure | | -| `evidenceURI` | `string` | ❌ | URIs to related evidence or underlying data (e.g. org.hypercerts.claim.evidence records or raw datasets) | maxLength: 50 | -| `measurers` | `ref` | ❌ | DIDs of the entity (or entities) that measured this data | maxLength: 100 | -| `comment` | `string` | ❌ | Short comment of this measurement, suitable for previews and list views. Rich text annotations may be provided via `commentFacets`. | maxLength: 3000, maxGraphemes: 300 | -| `commentFacets` | `ref` | ❌ | Rich text annotations for `comment` (mentions, URLs, hashtags, etc). | | -| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | +| Property | Type | Required | Description | Comments | +| --------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| `subject` | `ref` | ❌ | A strong reference to the record this measurement refers to (e.g. an activity, project, or claim). | | +| `metric` | `string` | ✅ | The metric being measured, e.g. forest area restored, number of users, etc. | maxLength: 500 | +| `unit` | `string` | ✅ | The unit of the measured value (e.g. kg CO₂e, hectares, %, index score). | maxLength: 50 | +| `value` | `string` | ✅ | The measured numeric value. | maxLength: 500 | +| `startDate` | `string` | ❌ | The start date and time when the measurement began. | | +| `endDate` | `string` | ❌ | The end date and time when the measurement ended. If it was a one time measurement, the endDate should be equal to the startDate. | | +| `locations` | `ref` | ❌ | Optional geographic references related to where the measurement was taken. Each referenced record must conform with the app.certified.geo.location lexicon. | maxLength: 100 | +| `methodType` | `string` | ❌ | Short identifier for the measurement methodology | maxLength: 30 | +| `methodURI` | `string` | ❌ | URI to methodology documentation, standard protocol, or measurement procedure | | +| `evidenceURI` | `string` | ❌ | URIs to related evidence or underlying data (e.g. org.hypercerts.claim.evidence records or raw datasets) | maxLength: 50 | +| `measurers` | `ref` | ❌ | DIDs of the entity (or entities) that measured this data | maxLength: 100 | +| `comment` | `string` | ❌ | Short comment of this measurement, suitable for previews and list views. Rich text annotations may be provided via `commentFacets`. | maxLength: 3000, maxGraphemes: 300 | +| `commentFacets` | `ref` | ❌ | Rich text annotations for `comment` (mentions, URLs, hashtags, etc). | | +| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | --- -### `org.hypercerts.claim.rights` +### `org.hypercerts.curation.collection` -**Description:** Describes the rights that a contributor and/or an owner has, such as whether the hypercert can be sold, transferred, and under what conditions. +**Description:** A collection/group of items (activities and/or other collections). Collections support recursive nesting. **Key:** `tid` #### Properties -| Property | Type | Required | Description | Comments | -| ------------------- | -------- | -------- | ------------------------------------------------------------------ | -------------- | -| `rightsName` | `string` | ✅ | Full name of the rights | maxLength: 100 | -| `rightsType` | `string` | ✅ | Short rights identifier for easier search | maxLength: 10 | -| `rightsDescription` | `string` | ✅ | Description of the rights of this hypercert | | -| `attachment` | `union` | ❌ | An attachment to define the rights further, e.g. a legal document. | | -| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | +| Property | Type | Required | Description | Comments | +| ------------------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| `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.geo.location. | | +| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | + +#### Defs + +##### `org.hypercerts.curation.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.curation.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. | --- @@ -268,7 +250,65 @@ Hypercerts-specific lexicons for tracking impact work and claims. --- -### `org.hypercerts.helper.workScopeTag` +### `org.hypercerts.graph.acknowledgement` + +**Description:** Acknowledges the inclusion of one record (subject) within another (context). Typically created in the subject owner's repo to form a bidirectional link. For example, a contributor acknowledging inclusion in an activity, or an activity owner acknowledging inclusion in a collection. + +**Key:** `tid` + +#### Properties + +| Property | Type | Required | Description | Comments | +| -------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------- | +| `subject` | `ref` | ✅ | The record whose inclusion is being acknowledged (e.g. an activity, a contributor information record). | | +| `context` | `ref` | ✅ | The record that includes the subject (e.g. a collection/project that includes an activity, or an activity that includes a contributor). | | +| `acknowledged` | `boolean` | ✅ | Whether inclusion is acknowledged (true) or rejected (false). | | +| `comment` | `string` | ❌ | Optional comment providing additional context or reasoning. | maxLength: 1000 | +| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created. | | + +--- + +### `org.hypercerts.helper.ops` + +**Description:** Operator node for work scope logic. Nesting is achieved by having args strongRefs point to either workScopeTag records (leaf atoms) or other ops records (nested expressions). Operator semantics are defined by consuming applications. + +Examples: op='all' (AND), op='any' (OR), op='not' (NOT; typically unary). + +**Key:** `tid` + +#### Properties + +| Property | Type | Required | Description | Comments | +| ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| `op` | `string` | ✅ | Operator identifier. Semantics are defined by the evaluating application. Examples: 'all' (AND), 'any' (OR), 'not' (NOT). | maxLength: 64, Known values: `all`, `any`, `not` | +| `args` | `ref` | ✅ | Arguments. Each strongRef should point to either org.hypercerts.helper.workScopeTag (leaf) or org.hypercerts.helper.ops (nested). For op='not', args SHOULD have exactly one element (enforced by clients). | maxLength: 100 | +| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | | + +--- + +### `org.hypercerts.helper.workScopeExpr` + +**Description:** A reusable work-scope boolean expression (simple flat form): (ALL allOf) AND (ANY anyOf, if present) AND (NONE noneOf). Designed to cover the vast majority of practical work-scope definitions (include, require, exclude) without recursion. For full nested boolean logic or complex conditional expressions, use org.hypercerts.helper.ops. + +An empty work-scope expression represents an unconstrained scope. If `allOf`, `anyOf`, and `noneOf` are all absent or empty, the expression imposes no filtering constraints. In this case, all work is considered in scope by default. + +**Key:** `tid` + +#### Properties + +| Property | Type | Required | Description | Comments | +| ------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------- | +| `version` | `integer` | ✅ | Schema version for this expression. Start with 1. Enables forward-compatible evolution of evaluation semantics. | | +| `label` | `string` | ❌ | Optional short human-readable label for UI display (e.g., 'OSS docs/code — no marketing'). | maxLength: 140 | +| `description` | `string` | ❌ | Optional longer explanation of the scope intent, interpretation guidance, or edge-case clarifications. | maxLength: 4000 | +| `allOf` | `ref` | ❌ | All referenced tags must match for something to be considered in-scope. Typically refs to org.hypercerts.helper.workScopeTag. | maxLength: 100 | +| `anyOf` | `ref` | ❌ | At least one referenced tag must match (if anyOf is present and non-empty). Typically refs to org.hypercerts.helper.workScopeTag. | maxLength: 100 | +| `noneOf` | `ref` | ❌ | None of the referenced tags may match. If any excluded tag matches, the contribution or activity is considered out-of-scope. | maxLength: 100 | +| `createdAt` | `string` | ✅ | Timestamp when this work-scope expression was created. | | + +--- + +### `org.hypercerts.ontology.workScopeTag` **Description:** A reusable scope atom for work scope logic expressions. Scopes can represent topics, languages, domains, deliverables, methods, regions, tags, or other categorical labels. @@ -293,7 +333,7 @@ Hypercerts-specific lexicons for tracking impact work and claims. Certified lexicons are common/shared lexicons that can be used across multiple protocols. -### `app.certified.location` +### `app.certified.geo.location` **Description:** A location reference @@ -313,7 +353,7 @@ Certified lexicons are common/shared lexicons that can be used across multiple p #### Defs -##### `app.certified.location#string` +##### `app.certified.geo.location#string` | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------- | diff --git a/lexicons/app/certified/location.json b/lexicons/app/certified/geo/location.json similarity index 98% rename from lexicons/app/certified/location.json rename to lexicons/app/certified/geo/location.json index ec30d871..bdf3e1e2 100644 --- a/lexicons/app/certified/location.json +++ b/lexicons/app/certified/geo/location.json @@ -1,6 +1,6 @@ { "lexicon": 1, - "id": "app.certified.location", + "id": "app.certified.geo.location", "defs": { "main": { "type": "record", diff --git a/lexicons/org/hypercerts/claim/activity.json b/lexicons/org/hypercerts/claim/activity.json index f914b47c..c7877038 100644 --- a/lexicons/org/hypercerts/claim/activity.json +++ b/lexicons/org/hypercerts/claim/activity.json @@ -54,7 +54,7 @@ "workScope": { "type": "union", "refs": ["com.atproto.repo.strongRef", "#workScopeString"], - "description": "Work scope definition. Either a strongRef to a work-scope logic record (structured, nested logic), or a free-form string for simple or legacy scopes. The work scope record should conform to the org.hypercerts.helper.workScopeTag lexicon." + "description": "Work scope definition. Either a strongRef to a work-scope logic record (structured, nested logic), or a free-form string for simple or legacy scopes. The work scope record should conform to the org.hypercerts.ontology.workScopeTag lexicon." }, "startDate": { "type": "string", @@ -81,7 +81,7 @@ }, "locations": { "type": "array", - "description": "An array of strong references to the location where activity was performed. The record referenced must conform with the lexicon app.certified.location.", + "description": "An array of strong references to the location where activity was performed. The record referenced must conform with the lexicon app.certified.geo.location.", "items": { "type": "ref", "ref": "com.atproto.repo.strongRef" diff --git a/lexicons/org/hypercerts/claim/attachment.json b/lexicons/org/hypercerts/context/attachment.json similarity index 96% rename from lexicons/org/hypercerts/claim/attachment.json rename to lexicons/org/hypercerts/context/attachment.json index 7ec034b5..ad1896df 100644 --- a/lexicons/org/hypercerts/claim/attachment.json +++ b/lexicons/org/hypercerts/context/attachment.json @@ -1,6 +1,6 @@ { "lexicon": 1, - "id": "org.hypercerts.claim.attachment", + "id": "org.hypercerts.context.attachment", "defs": { "main": { "type": "record", @@ -72,7 +72,7 @@ "location": { "type": "ref", "ref": "com.atproto.repo.strongRef", - "description": "A strong reference to the location where this attachment's subject matter occurred. The record referenced must conform with the lexicon app.certified.location." + "description": "A strong reference to the location where this attachment's subject matter occurred. The record referenced must conform with the lexicon app.certified.geo.location." }, "createdAt": { "type": "string", diff --git a/lexicons/org/hypercerts/claim/evaluation.json b/lexicons/org/hypercerts/context/evaluation.json similarity index 95% rename from lexicons/org/hypercerts/claim/evaluation.json rename to lexicons/org/hypercerts/context/evaluation.json index 8a5f8f10..d9b1875e 100644 --- a/lexicons/org/hypercerts/claim/evaluation.json +++ b/lexicons/org/hypercerts/context/evaluation.json @@ -1,6 +1,6 @@ { "lexicon": 1, - "id": "org.hypercerts.claim.evaluation", + "id": "org.hypercerts.context.evaluation", "defs": { "score": { "type": "object", @@ -57,7 +57,7 @@ }, "measurements": { "type": "array", - "description": "Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.claim.measurement", + "description": "Optional references to the measurements that contributed to this evaluation. The record(s) referenced must conform with the lexicon org.hypercerts.context.measurement", "items": { "type": "ref", "ref": "com.atproto.repo.strongRef" @@ -78,7 +78,7 @@ "location": { "type": "ref", "ref": "com.atproto.repo.strongRef", - "description": "An optional reference for georeferenced evaluations. The record referenced must conform with the lexicon app.certified.location." + "description": "An optional reference for georeferenced evaluations. The record referenced must conform with the lexicon app.certified.geo.location." }, "createdAt": { "type": "string", diff --git a/lexicons/org/hypercerts/claim/measurement.json b/lexicons/org/hypercerts/context/measurement.json similarity index 97% rename from lexicons/org/hypercerts/claim/measurement.json rename to lexicons/org/hypercerts/context/measurement.json index 96b3813e..be108d79 100644 --- a/lexicons/org/hypercerts/claim/measurement.json +++ b/lexicons/org/hypercerts/context/measurement.json @@ -1,6 +1,6 @@ { "lexicon": 1, - "id": "org.hypercerts.claim.measurement", + "id": "org.hypercerts.context.measurement", "defs": { "main": { "type": "record", @@ -42,7 +42,7 @@ }, "locations": { "type": "array", - "description": "Optional geographic references related to where the measurement was taken. Each referenced record must conform with the app.certified.location lexicon.", + "description": "Optional geographic references related to where the measurement was taken. Each referenced record must conform with the app.certified.geo.location lexicon.", "items": { "type": "ref", "ref": "com.atproto.repo.strongRef" diff --git a/lexicons/org/hypercerts/claim/collection.json b/lexicons/org/hypercerts/curation/collection.json similarity index 94% rename from lexicons/org/hypercerts/claim/collection.json rename to lexicons/org/hypercerts/curation/collection.json index d12f8d35..0437ac08 100644 --- a/lexicons/org/hypercerts/claim/collection.json +++ b/lexicons/org/hypercerts/curation/collection.json @@ -1,6 +1,6 @@ { "lexicon": 1, - "id": "org.hypercerts.claim.collection", + "id": "org.hypercerts.curation.collection", "defs": { "main": { "type": "record", @@ -58,7 +58,7 @@ "location": { "type": "ref", "ref": "com.atproto.repo.strongRef", - "description": "A strong reference to the location where this collection's activities were performed. The record referenced must conform with the lexicon app.certified.location." + "description": "A strong reference to the location where this collection's activities were performed. The record referenced must conform with the lexicon app.certified.geo.location." }, "createdAt": { "type": "string", @@ -75,7 +75,7 @@ "itemIdentifier": { "type": "ref", "ref": "com.atproto.repo.strongRef", - "description": "Strong reference to an item in this collection. Items can be activities (org.hypercerts.claim.activity) and/or other collections (org.hypercerts.claim.collection)." + "description": "Strong reference to an item in this collection. Items can be activities (org.hypercerts.claim.activity) and/or other collections (org.hypercerts.curation.collection)." }, "itemWeight": { "type": "string", diff --git a/lexicons/org/hypercerts/acknowledgement.json b/lexicons/org/hypercerts/graph/acknowledgement.json similarity index 97% rename from lexicons/org/hypercerts/acknowledgement.json rename to lexicons/org/hypercerts/graph/acknowledgement.json index 21137bf0..7b5fec27 100644 --- a/lexicons/org/hypercerts/acknowledgement.json +++ b/lexicons/org/hypercerts/graph/acknowledgement.json @@ -1,6 +1,6 @@ { "lexicon": 1, - "id": "org.hypercerts.acknowledgement", + "id": "org.hypercerts.graph.acknowledgement", "defs": { "main": { "type": "record", diff --git a/lexicons/org/hypercerts/helper/workScopeTag.json b/lexicons/org/hypercerts/ontology/workScopeTag.json similarity index 97% rename from lexicons/org/hypercerts/helper/workScopeTag.json rename to lexicons/org/hypercerts/ontology/workScopeTag.json index abadf118..bae02b82 100644 --- a/lexicons/org/hypercerts/helper/workScopeTag.json +++ b/lexicons/org/hypercerts/ontology/workScopeTag.json @@ -1,6 +1,6 @@ { "lexicon": 1, - "id": "org.hypercerts.helper.workScopeTag", + "id": "org.hypercerts.ontology.workScopeTag", "defs": { "main": { "type": "record", diff --git a/scripts/generate-schemas.js b/scripts/generate-schemas.js index b7628025..c4626dce 100644 --- a/scripts/generate-schemas.js +++ b/scripts/generate-schemas.js @@ -182,7 +182,7 @@ function categorizeLexicons(lexicons) { lexicons: [], ordering: (lex) => { const order = [ - "app.certified.location", + "app.certified.geo.location", "app.certified.badge.definition", "app.certified.badge.award", "app.certified.badge.response",