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 all commits
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`
56 changes: 28 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,12 +161,12 @@ 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. | |
Expand Down Expand Up @@ -224,10 +224,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 +241,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 +258,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