Hypercerts Protocol 2.1
The protocol major and minor version follows the Hypercerts Lexicon releases. A new major version can also come from a breaking change to the Lexicon package alone, as in 2.0, where the records did not change; each release's notes say whether existing records are affected. These notes explain the purpose and integration impact of each release; the Lexicon changelog records the detailed package changes. Component release histories have their own versions on the Releases overview.
2.1: A shared value for comments on attachments#
2026-11-17 · Based on Lexicons 2.1.0
This release adds one known value to the attachment lexicon. Apps that store a comment as an attachment can now label it the same way, and readers can tell comments from reports and other evidence.
commentis a known attachmentcontentType. Use it for a comment whosesubjectspoint at the record it comments on. The schema shape does not change. #279- Dual license. The Lexicon package is now licensed under either MIT or Apache-2.0, at your option. Earlier versions stay MIT. #281
- Deep imports recommended. The package documentation now recommends importing by NSID path instead of from the package root in libraries and bundled apps, for smaller bundles. #274
For existing integrations: No changes needed. Existing records remain valid, and contentType already accepts values outside its known list. Applications that show attachments can start treating comment as its own kind.
2.0: Schemas for the modern AT Protocol client, with no record changes#
2026-11-03 · Based on Lexicons 2.0.0
This release changes how applications use the Hypercerts lexicons from TypeScript, not the records themselves. No lexicon changed, and every existing record remains valid. The protocol version follows the Lexicon package, and the package's new major version marks a breaking change for code that imports it.
- Schemas and types for the modern AT Protocol client. The package now exports a schema and TypeScript type for every lexicon, for use with the
@atproto/lexclient and in the NSID layout its documentation uses.client.create(org.hypercerts.claim.activity, …)writes a typed record, andorg.hypercerts.claim.activity.$safeParse(record)validates one. Applications type and validate records the same way the AT Protocol's own tooling does, instead of through a second generated API. #270 - Validation checks the record type.
$safeParserequires the record's$type, which the 1.xvalidate()did not. Records read from a repository already carry it; data from forms or other APIs needs it added before checking, so a record cannot pass as a different type. - The 1.x API moves to
/legacy. The previous types, validators, and NSID constants are unchanged at@hypercerts-org/lexicon/legacy, published as ESM and CommonJS. They are deprecated and will be removed in a later major version.
For existing integrations: Records and stored data need no changes. Code that imports @hypercerts-org/lexicon needs one of two updates: change its imports to @hypercerts-org/lexicon/legacy to keep the 1.x API, including require(), or move to the new schemas using the migration guide in the Lexicon README. The package root is ESM only, requires @atproto/lex ^0.4.2 as a peer dependency, and requires Node.js 22 or later. Data checked with $safeParse must include its $type.
1.6: Clearer funding receipts, multilingual updates, and app provenance#
2026-10-27 · Based on Lexicons 1.6.0
This release helps applications share a clearer picture of funding and ongoing work. Funding platforms can describe what a donor paid and what a recipient received without guessing missing amounts. People and organizations have an explicit way to publish updates beyond a single project. Language hints and application signatures help other apps interpret and attribute that content when they read it elsewhere on AT Protocol.
- Funding receipts that reflect real payment flows. A donation can pass through a platform, incur fees, or arrive in another currency. Receipts now distinguish the gross amount paid from the net amount received, each with its own currency, and can record only what is known. They can identify an intermediary and distinguish donations, matching funds, and grants. Shared guidance separates payment methods from networks and explains when an onward payment is a separate grant rather than another receipt for the same donation. Omitting a donor's name does not make a public transaction hash anonymous. #263
- Updates without inventing a project. People and organizations can publish a standalone update using the existing attachment record, with their own profile as its subject. Project updates use the same record, pointing at the project instead. The new
updatecontent type lets apps distinguish narrative posts from reports and evidence without maintaining a separate post format. This clarifies an existing use, rather than introducing a new record type. #267 - Language hints for multilingual applications. Projects and other collections, activities, attachments, features, profiles, and organization records can declare up to three languages in
langs, using the same format as Bluesky posts. This helps readers prioritize translation and indexing. The tags describe the author's original text, not their interface language, and remain hints: missing or incorrect tags are not a reason to hide a record. #266 - A verifiable link to the app that wrote a record. An optional
createdViasignature lets an application identify itself as the writer of that version, even when the record lives in a user's repository. Readers can use it to attribute content across apps, but only after verifying the signature and checking that its key belongs to the expected application. It identifies the writing app, not an endorsement or a guarantee that the content is true. #268
For existing integrations: Existing records remain valid, but receipt readers need attention: amount and currency are now optional. Update validation, types, and display logic before consuming receipts that omit them; older schemas may reject these receipts. For existing receipts, review the clarified meaning of amount as gross paid, not net received. Signing integrations should follow the corrected procedure in the Lexicon README: the signed metadata includes the key and the DID of the repository holding the record. Signatures made using the previous example fail verification against the attestation specification and need to be recreated; remote proof CID calculation was also corrected.
1.5: Richer organization profiles, time-bound badges, and classified attachments#
2026-10-05 · Based on Lexicons 1.5.0
This release makes published records more useful in directories and assessments. Organizations can share the details a partner directory needs; badge awards can state their period of validity; and attachments can use the same reusable tags as features and collections.
- Organizations can add an optional legal name, full logo, public email, and additional locations. Existing profile fields still carry the public display name, avatar, and main website; the primary location remains a separate reference.
- Badge awards can specify when they start and stop applying. An expired award is not the same as a revoked one: deleting the award record remains the way to revoke it.
- Attachments can use shared vocabulary tags, making evidence easier to classify consistently alongside features and collections. Multiple tags describe the attachment together, not alternative classifications.
For existing integrations: All new fields are optional, so existing records remain valid. Applications that display organizations, badges, or attachments can adopt them as needed. Later 1.5.x fixes and additions are listed in the Lexicon changelog, not as separate protocol minor releases.
1.4: Features and shared vocabulary#
2026-08-24 · Based on Lexicons 1.4.0
Describe subjects such as land areas, ecological zones, or participant cohorts with feature records. Shared vocabulary tags let projects and features reuse the same definitions instead of relying on inconsistent free-text labels.
- Introduces org.hypercerts.entity.feature for subjects that are not people or organizations, with descriptions, optional locations, and external identifiers.
- Introduces org.hypercerts.vocab.tag for reusable classification, including broader terms, alternative names, external equivalents, and replacement terms.
- Collections can include features alongside activities and other collections. Existing activities continue to reference locations directly.
For existing integrations: Additive: existing records remain valid. Applications can add support for the new records as their use cases require.
1.3: Richer descriptions with updated Leaflet formats#
2026-08-13 · Based on Lexicons 1.3.0
Updates the bundled Leaflet schemas, giving applications more ways to represent rich descriptions while keeping them aligned with Leaflet's published formats.
- Adds Leaflet block types including image galleries, HTML, post lists, and publication blocks, plus theme-color definitions.
- Expands image, iframe, and rich-text options, including image display width, iframe aspect ratio, link hrefs, and highlight colors.
- Linear documents can include the newly supported blocks.
For existing integrations: Readers of rich descriptions should handle unfamiliar blocks gracefully. Applications that render or validate Leaflet content should review the updated bundled schemas.
1.2: Follow projects and request grouped permissions#
2026-08-03 · Based on Lexicons 1.2.0
Adds follows for records such as projects, and reusable permission sets that let applications request access to related record types together.
- Introduces app.certified.graph.entityFollow for non-account entities. Its AT-URI reference keeps following the record across updates instead of pinning one content version.
- Adds org.hypercerts.authWrite and app.certified.authWrite permission sets, so an application can request a namespace's listed write permissions through an include scope.
- Account follows remain separate in app.certified.graph.follow.
For existing integrations: These are additional capabilities. Use entity follows for records and account follows for accounts; review the permission sets when configuring authorization.
1.1: Optional signatures on record contents#
2026-07-06 · Based on Lexicons 1.1.0
Lets a signer attest to a record's contents, adding a form of provenance separate from the signature on the publishing AT Protocol repository.
- Adds optional signatures to the record schemas, with shared app.certified.signature.defs definitions.
- Supports inline signatures and references to remote app.certified.signature.proof records.
- Record signatures complement the existing wallet-consent proof on EVM identity links.
For existing integrations: Non-breaking: signatures are optional. Existing records without signatures remain valid.
1.0: First stable Lexicon baseline#
2026-06-17 · Based on Lexicons 1.0.0
Establishes the first stable release of the Hypercerts and Certified Lexicon package, its TypeScript types, and generated exports.
- Promotes the existing package to 1.0.0. The stability promotion itself does not introduce new schemas or types.
- Also increases the plain-text activity work-scope limit from 100 to 1,000 graphemes, with a 10,000-byte cap.
- Establishes standard semantic versioning for the package: breaking changes advance the major version, compatible additions the minor version, and fixes the patch version.
For existing integrations: The work-scope limit increase preserves existing valid records. This history begins with the stable 1.0 baseline; earlier pre-release migrations remain in the component changelog.