Hypercerts Lexicon Documentation

This repository contains ATProto lexicon definitions for the Hypercerts protocol. Each lexicon defines a record type that can be stored on the ATProto network.

Entity Relationship Diagram

View ERD with field details

Installation

npm i @hypercerts-org/lexicon

Usage

import { AtpBaseClient } from "@hypercerts-org/lexicon";
import type { HypercertClaim } from "@hypercerts-org/lexicon";

const client = new AtpBaseClient({
  service: "https://bsky.social",
  headers: { Authorization: `Bearer ${token}` },
});

const hypercert: HypercertClaim = {
  $type: "org.hypercerts.claim.activity",
  title: "My Impact Work",
  shortDescription: "Description here",
  workScope: "Scope of work",
  startDate: "2023-01-01T00:00:00Z",
  endDate: "2023-12-31T23:59:59Z",
  createdAt: new Date().toISOString(),
};

await client.org.hypercerts.claim.activity.create(
  { repo: "did:plc:example" },
  hypercert,
);

Certified Lexicons

Certified lexicons are common/shared lexicons that can be used across multiple protocols.

Common Definitions

Lexicon ID: org.hypercerts.defs

Description: Common type definitions used across all certified protocols.

Defs

Def	Type	Description	Comments
uri	object	Object containing a URI to external data	Has uri property (string, format uri)
smallBlob	object	Object containing a blob to external data	Has blob property (blob, up to 10MB)
largeBlob	object	Object containing a blob to external data	Has blob property (blob, up to 100MB)
smallImage	object	Object containing a small image	Has image property (blob, up to 5MB)
largeImage	object	Object containing a large image	Has image property (blob, up to 10MB)

---

Location Lexicon

Lexicon ID: app.certified.location

Description: A location reference for use across certified protocols. For more information about

Key: any

Properties

Property	Type	Required	Description	Comments
lpVersion	string	✅	The version of the Location Protocol
srs	string	✅	The Spatial Reference System URI (e.g., http://www.opengis.net/def/crs/OGC/1.3/CRS84) that defines the coordinate system.
locationType	string	✅	An identifier for the format of the location data (e.g., coordinate-decimal, geojson-point)
location	union	✅	The location of where the work was performed as a URI or blob.
name	string	❌	Optional name for this location
description	string	❌	Optional description for this location
createdAt	string	✅	Client-declared timestamp when this record was originally created

---

Hypercerts Lexicons

Hypercerts-specific lexicons for tracking impact work and claims.

Hypercerts Activity Claim

Lexicon ID: org.hypercerts.claim.activity

Description: The main lexicon where everything is connected to. This is the hypercert record that tracks impact work.

Key: any

Properties

Property	Type	Required	Description	Comments
title	string	✅	Title of the hypercert
shortDescription	string	✅	Short blurb of the impact work done.
description	string	❌	Optional longer description of the impact work done.
image	union	❌	The hypercert visual representation as a URI or image blob
workScope	object	❌	Logical scope of the work using label-based conditions	Object with withinAllOf, withinAnyOf, withinNoneOf arrays of labels
startDate	string	✅	When the work began
endDate	string	✅	When the work ended
contributions	array	❌	A strong reference to the contributions done to create the impact in the hypercerts	References must conform to org.hypercerts.claim.contribution
rights	ref	❌	A strong reference to the rights that this hypercert has	References must conform to org.hypercerts.claim.rights
location	ref	❌	A strong reference to the location where the work for done hypercert was located	References must conform to app.certified.location
createdAt	string	✅	Client-declared timestamp when this record was originally created

---

Hypercerts Contribution

Lexicon ID: org.hypercerts.claim.contribution

Description: A contribution made toward a hypercert's impact.

Key: any

Properties

Property	Type	Required	Description	Comments
role	string	❌	Role or title of the contributor(s).
contributors	array	✅	List of the contributors (names, pseudonyms, or DIDs). If multiple contributors are stored in the same hypercertContribution, then they would have the exact same role.
description	string	❌	What the contribution concretely achieved
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

---

Hypercerts Evaluation

Lexicon ID: org.hypercerts.claim.evaluation

Description: An evaluation of a hypercert or other claim

Key: tid

Properties

Property	Type	Required	Description	Comments
subject	ref	✅	A strong reference to the evaluated claim	(e.g measurement, hypercert, contribution, etc)
evaluators	array	✅	DIDs of the evaluators
evaluations	array	❌	Evaluation data (URIs or blobs) containing detailed reports or methodology
summary	string	✅	Brief evaluation summary
location	ref	❌	An optional reference for georeferenced evaluations	References must conform to app.certified.location
createdAt	string	✅	Client-declared timestamp when this record was originally created

---

Hypercerts Evidence

Lexicon ID: org.hypercerts.claim.evidence

Description: A piece of evidence supporting a hypercert claim

Key: any

Properties

Property	Type	Required	Description	Comments
activity	ref	❌	A strong reference to the activity this evidence is for	The record referenced must conform with the lexicon org.hypercerts.claim.activity
content	union	✅	A piece of evidence (URI or blobs) supporting a hypercert claim
title	string	✅	Title to describe the nature of the evidence
shortDescription	string	❌	Short description explaining what this evidence demonstrates or proves
description	string	❌	Optional longer description describing the impact claim evidence.
createdAt	string	✅	Client-declared timestamp when this hypercert claim was originally created

---

org.hypercerts.claim.measurement

Lexicon ID: org.hypercerts.claim.measurement

Description: External measurement data supporting a hypercert claim

Key: tid

Properties

Property	Type	Required	Description	Comments
activity	ref	❌	A strong reference to the activity that this measurement is for	The record referenced must conform with the lexicon org.hypercerts.claim.activity
measurers	array	✅	DIDs of the entity (or entities) that measured this data
metric	string	✅	The metric being measured
value	string	✅	The measured value
measurementMethodType	string	❌	Short identifier for the measurement methodology
measurementMethodURI	string	❌	URI to methodology documentation, standard protocol, or measurement procedure
evidenceURI	array	❌	URIs to supporting evidence or data
location	ref	❌	A strong reference to the location where the measurement was taken	References must conform to app.certified.location
createdAt	string	✅	Client-declared timestamp when this record was originally created

---

org.hypercerts.claim.collection

Lexicon ID: org.hypercerts.claim.collection

Description: A collection/group of hypercerts that have a specific property.

Key: tid

Properties

Property	Type	Required	Description	Comments
title	string	✅	The title of this collection
shortDescription	string	❌	A short description of this collection
coverPhoto	union	❌	The cover photo of this collection (either in URI format or in a blob).
claims	array	✅	Array of claims with their associated weights in this collection	Each item references #claimItem
createdAt	string	✅	Client-declared timestamp when this record was originally created

Defs

claimItem

Property	Type	Required	Description	Comments
claim	ref	✅	A strong reference to a hypercert claim record. This claim must conform to the lexicon org.hypercerts.claim.activity
weight	string	✅	The weight/importance of this hypercert claim in the collection (a percentage from 0-100, stored as a string to avoid float precision issues). The total claim weights should add up to 100.

---

org.hypercerts.claim.rights

Lexicon ID: org.hypercerts.claim.rights

Description: Describes the rights that a user has with a hypercert, such as whether it can be sold, transferred, and under what conditions.

Key: any

Properties

Property	Type	Required	Description	Comments
rightsName	string	✅	Full name of the rights
rightsType	string	✅	Short rights identifier for easier search
rightsDescription	string	✅	Description of the rights of this hypercert
attachment	union	❌	An attachment to define the rights further, e.g. a legal document	URI or blob
createdAt	string	✅	Client-declared timestamp when this record was originally created

---

Notes

• All timestamps use the datetime format (ISO 8601)
• Strong references (com.atproto.repo.strongRef) include both the URI and CID of the referenced record
• Union types allow multiple possible formats (e.g., URI or blob)
• Array items may have constraints like maxLength to limit the number of elements
• String fields may have both maxLength (bytes) and maxGraphemes (Unicode grapheme clusters) constraints