Skip to content

chore: run all lexicons against the ATProto lexicon style guide #103

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.

Sign up for GitHub

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

Open
s-adamantine wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

chore: run all lexicons against the ATProto lexicon style guide #103

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0f768fa
chore: improve lexicon style guide compliance
s-adamantine Jan 21, 2026
063bc1b
edit schemas.md
s-adamantine Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .changeset/style-guide-compliance-fixes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
"@hypercerts-org/lexicon": patch
---

Improve lexicon style guide compliance

- Changed `enum` to `knownValues` in `badge/response.json` for schema evolution compliance
- Added `maxLength` constraints to string fields without format:
- `badge/definition.json`: badgeType (100), title (256), description (1000)
- `badge/award.json`: note (500)
- `badge/response.json`: weight (50)
- `rights.json`: rightsDescription (5000 bytes, 1000 graphemes)
- `funding/receipt.json`: to (256), amount (50), currency (10), paymentRail (50), paymentNetwork (50), transactionId (256)
- Changed `maxGraphemes` to `maxLength` for URI definition in `defs.json`
74 changes: 46 additions & 28 deletions SCHEMAS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,13 +140,13 @@ Hypercerts-specific lexicons for tracking impact work and claims.

#### Properties

| Property | Type | Required | Description | Comments |
| ------------------- | -------- | -------- | ------------------------------------------------------------------ | -------------- |
| `rightsName` | `string` | yes | Full name of the rights | maxLength: 100 |
| `rightsType` | `string` | yes | Short rights identifier for easier search | maxLength: 10 |
| `rightsDescription` | `string` | yes | Description of the rights of this hypercert | |
| `attachment` | `union` | no | An attachment to define the rights further, e.g. a legal document. | |
| `createdAt` | `string` | yes | Client-declared timestamp when this record was originally created | |
| Property | Type | Required | Description | Comments |
| ------------------- | -------- | -------- | ------------------------------------------------------------------ | ----------------------------------- |
| `rightsName` | `string` | yes | Full name of the rights | maxLength: 100 |
| `rightsType` | `string` | yes | Short rights identifier for easier search | maxLength: 10 |
| `rightsDescription` | `string` | yes | Description of the rights of this hypercert | maxLength: 5000, maxGraphemes: 1000 |
| `attachment` | `union` | no | An attachment to define the rights further, e.g. a legal document. | |
| `createdAt` | `string` | yes | Client-declared timestamp when this record was originally created | |

---

Expand All @@ -161,19 +161,37 @@ Hypercerts-specific lexicons for tracking impact work and claims.
| Property | Type | Required | Description | Comments |
| ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `from` | `ref` | yes | DID of the sender who transferred the funds. Leave empty if sender wants to stay anonymous. | |
| `to` | `string` | yes | The recipient of the funds. Can be identified by DID or a clear-text name. | |
| `amount` | `string` | yes | Amount of funding received. | |
| `currency` | `string` | yes | Currency of the payment (e.g. EUR, USD, ETH). | |
| `paymentRail` | `string` | no | How the funds were transferred (e.g. bank_transfer, credit_card, onchain, cash, check, payment_processor). | |
| `paymentNetwork` | `string` | no | Optional network within the payment rail (e.g. arbitrum, ethereum, sepa, visa, paypal). | |
| `transactionId` | `string` | no | Identifier of the underlying payment transaction (e.g. bank reference, onchain transaction hash, or processor-specific ID). Use paymentNetwork to specify the network where applicable. | |
| `to` | `string` | yes | The recipient of the funds. Can be identified by DID or a clear-text name. | maxLength: 256 |
| `amount` | `string` | yes | Amount of funding received. | maxLength: 50 |
| `currency` | `string` | yes | Currency of the payment (e.g. EUR, USD, ETH). | maxLength: 10 |
| `paymentRail` | `string` | no | How the funds were transferred (e.g. bank_transfer, credit_card, onchain, cash, check, payment_processor). | maxLength: 50 |
| `paymentNetwork` | `string` | no | Optional network within the payment rail (e.g. arbitrum, ethereum, sepa, visa, paypal). | maxLength: 50 |
| `transactionId` | `string` | no | Identifier of the underlying payment transaction (e.g. bank reference, onchain transaction hash, or processor-specific ID). Use paymentNetwork to specify the network where applicable. | maxLength: 256 |
| `for` | `string` | no | Optional reference to the activity, project, or organization this funding relates to. | |
| `notes` | `string` | no | Optional notes or additional context for this funding receipt. | maxLength: 500 |
| `occurredAt` | `string` | no | Timestamp when the payment occurred. | |
| `createdAt` | `string` | yes | Client-declared timestamp when this receipt record was created. | |

---

### `org.hypercerts.acknowledgement`

**Description:** Acknowledgement of inclusion/association between subjects and a context.

**Key:** `tid`

#### Properties

| Property | Type | Required | Description | Comments |
| ----------- | --------- | -------- | ----------------------------------------------------------------------- | --------------- |
| `subjects` | `ref` | yes | The records being acknowledged (e.g., activities). | |
| `context` | `ref` | yes | The target context (e.g. a collection) for the acknowledgement/consent. | |
| `given` | `boolean` | yes | Indicates whether acknowledgement is granted (true) or denied (false). | |
| `comment` | `string` | no | Optional comment providing additional details or reasoning. | maxLength: 1000 |
| `createdAt` | `string` | yes | Client-declared timestamp when this record was originally created. | |
Copy link

@coderabbitai coderabbitai bot Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# Search for acknowledgement lexicon JSON file
find . -type f -name "*acknowledgement*" | grep -E '\.(json|md)$'

Repository: hypercerts-org/hypercerts-lexicon

Length of output: 59

🏁 Script executed:

# Check README.md for acknowledgement documentation
rg -n "acknowledgement" README.md -i

Repository: hypercerts-org/hypercerts-lexicon

Length of output: 59

🏁 Script executed:

# List lexicons directory structure to understand organization
find ./lexicons -type f -name "*.json" | head -20

Repository: hypercerts-org/hypercerts-lexicon

Length of output: 740

🏁 Script executed:

# Check if SCHEMAS.md exists and contains acknowledgement section
grep -n "org.hypercerts.acknowledgement" SCHEMAS.md

Repository: hypercerts-org/hypercerts-lexicon

Length of output: 117

🏁 Script executed:

# Check README.md structure
head -50 README.md

Repository: hypercerts-org/hypercerts-lexicon

Length of output: 1155

🏁 Script executed:

# Verify README does not mention acknowledgement
grep -i "acknowledgement" README.md || echo "No acknowledgement found in README"

Repository: hypercerts-org/hypercerts-lexicon

Length of output: 111

Create the acknowledgement lexicon JSON file and document it in README.md

SCHEMAS.md documents org.hypercerts.acknowledgement (line 177), but the corresponding lexicon JSON file is missing. Create lexicons/org/hypercerts/claim/acknowledgement.json following ATProto lexicon schema v1, and update README.md to document the new lexicon alongside other claim-related records.

🧰 Tools
🪛 LanguageTool

[style] ~191-~191: This phrase is redundant. Consider writing “created”.
Context: ...declared timestamp when this record was originally created. | | --- ## Cert...

(ORIGINALLY_CREATED)

🤖 Prompt for AI Agents 
In `@SCHEMAS.md` around lines 177 - 191, Create a new ATProto lexicon v1 JSON file
named lexicons/org/hypercerts/claim/acknowledgement.json that defines the record
"org.hypercerts.acknowledgement" with the properties listed in SCHEMAS.md:
subjects (ref, required), context (ref, required), given (boolean, required),
comment (string, optional, maxLength 1000), and createdAt (string, required);
ensure the lexicon includes proper ids, defs, record key, and required array per
ATProto lexicon schema v1 and mirrors the table types and descriptions. Then
update README.md to list and briefly describe the new acknowledgement lexicon
alongside the existing claim-related records so it appears in the lexicon
index/documentation.


---

## Certified Lexicons

Certified lexicons are common/shared lexicons that can be used across multiple protocols.
Expand Down Expand Up @@ -224,10 +242,10 @@ Certified lexicons are common/shared lexicons that can be used across multiple p

| Property | Type | Required | Description | Comments |
| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `badgeType` | `string` | yes | Category of the badge (e.g. endorsement, participation, affiliation). | |
| `title` | `string` | yes | Human-readable title of the badge. | |
| `badgeType` | `string` | yes | Category of the badge (e.g. endorsement, participation, affiliation). | maxLength: 100 |
| `title` | `string` | yes | Human-readable title of the badge. | maxLength: 256 |
| `icon` | `blob` | yes | Icon representing the badge, stored as a blob for compact visual display. | maxSize: 1048576, accepts: image/png, image/jpeg, image/webp, image/svg+xml |
| `description` | `string` | no | Optional short statement describing what the badge represents. | |
| `description` | `string` | no | Optional short statement describing what the badge represents. | maxLength: 1000 |
| `allowedIssuers` | `ref` | no | Optional allowlist of DIDs allowed to issue this badge. If omitted, anyone may issue it. | |
| `createdAt` | `string` | yes | Client-declared timestamp when this record was originally created | |

Expand All @@ -241,12 +259,12 @@ Certified lexicons are common/shared lexicons that can be used across multiple p

#### Properties

| Property | Type | Required | Description |
| ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `badge` | `ref` | yes | Reference to the badge definition for this award. |
| `subject` | `union` | yes | Entity the badge award is for (either an account DID or any specific AT Protocol record), e.g. a user, a project, or a specific activity claim. |
| `note` | `string` | no | Optional statement explaining the reason for this badge award. |
| `createdAt` | `string` | yes | Client-declared timestamp when this record was originally created |
| Property | Type | Required | Description | Comments |
| ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `badge` | `ref` | yes | Reference to the badge definition for this award. | |
| `subject` | `union` | yes | Entity the badge award is for (either an account DID or any specific AT Protocol record), e.g. a user, a project, or a specific activity claim. | |
| `note` | `string` | no | Optional statement explaining the reason for this badge award. | maxLength: 500 |
| `createdAt` | `string` | yes | Client-declared timestamp when this record was originally created | |

---

Expand All @@ -258,12 +276,12 @@ Certified lexicons are common/shared lexicons that can be used across multiple p

#### Properties

| Property | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------------------------------------------ |
| `badgeAward` | `ref` | yes | Reference to the badge award. |
| `response` | `string` | yes | The recipient’s response for the badge (accepted or rejected). |
| `weight` | `string` | no | Optional relative weight for accepted badges, assigned by the recipient. |
| `createdAt` | `string` | yes | Client-declared timestamp when this record was originally created |
| Property | Type | Required | Description | Comments |
| ------------ | -------- | -------- | ------------------------------------------------------------------------ | ------------------------------------ |
| `badgeAward` | `ref` | yes | Reference to the badge award. | |
| `response` | `string` | yes | The recipient’s response for the badge (accepted or rejected). | Known values: `accepted`, `rejected` |
| `weight` | `string` | no | Optional relative weight for accepted badges, assigned by the recipient. | maxLength: 50 |
| `createdAt` | `string` | yes | Client-declared timestamp when this record was originally created | |

---

Expand Down
3 changes: 2 additions & 1 deletion lexicons/app/certified/badge/award.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@
},
"note": {
"type": "string",
"description": "Optional statement explaining the reason for this badge award."
"description": "Optional statement explaining the reason for this badge award.",
"maxLength": 500
},
"createdAt": {
"type": "string",
Expand Down
9 changes: 6 additions & 3 deletions lexicons/app/certified/badge/definition.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,13 @@
"properties": {
"badgeType": {
"type": "string",
"description": "Category of the badge (e.g. endorsement, participation, affiliation)."
"description": "Category of the badge (e.g. endorsement, participation, affiliation).",
"maxLength": 100
},
"title": {
"type": "string",
"description": "Human-readable title of the badge."
"description": "Human-readable title of the badge.",
"maxLength": 256
},
"icon": {
"type": "blob",
Expand All @@ -31,7 +33,8 @@
},
"description": {
"type": "string",
"description": "Optional short statement describing what the badge represents."
"description": "Optional short statement describing what the badge represents.",
"maxLength": 1000
},
"allowedIssuers": {
"type": "array",
Expand Down
5 changes: 3 additions & 2 deletions lexicons/app/certified/badge/response.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,13 @@
},
"response": {
"type": "string",
"enum": ["accepted", "rejected"],
"knownValues": ["accepted", "rejected"],
"description": "The recipient’s response for the badge (accepted or rejected)."
},
"weight": {
"type": "string",
"description": "Optional relative weight for accepted badges, assigned by the recipient."
"description": "Optional relative weight for accepted badges, assigned by the recipient.",
"maxLength": 50
},
"createdAt": {
"type": "string",
Expand Down
4 changes: 3 additions & 1 deletion lexicons/org/hypercerts/claim/rights.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@
},
"rightsDescription": {
"type": "string",
"description": "Description of the rights of this hypercert"
"description": "Description of the rights of this hypercert",
"maxLength": 5000,
"maxGraphemes": 1000
},
"attachment": {
"type": "union",
Expand Down
2 changes: 1 addition & 1 deletion lexicons/org/hypercerts/defs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"uri": {
"type": "string",
"format": "uri",
"maxGraphemes": 1024,
"maxLength": 2048,
"description": "URI to external data"
}
}
Expand Down
18 changes: 12 additions & 6 deletions lexicons/org/hypercerts/funding/receipt.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,27 +17,33 @@
},
"to": {
"type": "string",
"description": "The recipient of the funds. Can be identified by DID or a clear-text name."
"description": "The recipient of the funds. Can be identified by DID or a clear-text name.",
"maxLength": 256
},
"amount": {
"type": "string",
"description": "Amount of funding received."
"description": "Amount of funding received.",
"maxLength": 50
},
"currency": {
"type": "string",
"description": "Currency of the payment (e.g. EUR, USD, ETH)."
"description": "Currency of the payment (e.g. EUR, USD, ETH).",
"maxLength": 10
},
"paymentRail": {
"type": "string",
"description": "How the funds were transferred (e.g. bank_transfer, credit_card, onchain, cash, check, payment_processor)."
"description": "How the funds were transferred (e.g. bank_transfer, credit_card, onchain, cash, check, payment_processor).",
"maxLength": 50
},
"paymentNetwork": {
"type": "string",
"description": "Optional network within the payment rail (e.g. arbitrum, ethereum, sepa, visa, paypal)."
"description": "Optional network within the payment rail (e.g. arbitrum, ethereum, sepa, visa, paypal).",
"maxLength": 50
},
"transactionId": {
"type": "string",
"description": "Identifier of the underlying payment transaction (e.g. bank reference, onchain transaction hash, or processor-specific ID). Use paymentNetwork to specify the network where applicable."
"description": "Identifier of the underlying payment transaction (e.g. bank reference, onchain transaction hash, or processor-specific ID). Use paymentNetwork to specify the network where applicable.",
"maxLength": 256
},
"for": {
"type": "string",
Expand Down