@hypercerts-org/lexicon

ATProto lexicon definitions and generated TypeScript types for the Hypercerts protocol.

Installation

pnpm add @hypercerts-org/lexicon

Features

• Lexicon JSON Definitions: ATProto-compliant lexicon schemas for all Hypercerts record types
• Generated TypeScript Types: Strongly-typed interfaces generated via @atproto/lex-cli
• Runtime Validation: isRecord and validateRecord functions for each type
• Lexicon Registry: Pre-configured registry for schema validation

Usage

Using Types

import type { 
  OrgHypercertsClaim,
  OrgHypercertsCollection,
  OrgHypercertsClaimRights 
} from '@hypercerts-org/lexicon';

// Use the Main type for full records (includes $type)
const claim: OrgHypercertsClaim.Main = {
  $type: 'org.hypercerts.claim',
  title: 'My Impact Work',
  shortDescription: 'Description here',
  workScope: 'Scope of work',
  workTimeFrameFrom: '2023-01-01T00:00:00Z',
  workTimeFrameTo: '2023-12-31T23:59:59Z',
  createdAt: new Date().toISOString()
};

Runtime Validation

import { OrgHypercertsClaim } from '@hypercerts-org/lexicon';

// Check if a value matches the type
if (OrgHypercertsClaim.isRecord(unknownValue)) {
  // unknownValue is now typed as OrgHypercertsClaim.Main
  console.log(unknownValue.title);
}

// Validate with detailed error information
const result = OrgHypercertsClaim.validateRecord(data);
if (result.success) {
  // data is valid
} else {
  console.error(result.error);
}

Using Lexicon Constants

import { HYPERCERT_LEXICONS, HYPERCERT_COLLECTIONS } from '@hypercerts-org/lexicon';

// Collection names for ATProto operations
console.log(HYPERCERT_COLLECTIONS.CLAIM);       // 'org.hypercerts.claim'
console.log(HYPERCERT_COLLECTIONS.COLLECTION);  // 'org.hypercerts.collection'
console.log(HYPERCERT_COLLECTIONS.RIGHTS);      // 'org.hypercerts.claim.rights'

// Full lexicon documents for registry
import { Lexicons } from '@atproto/lexicon';
const registry = new Lexicons(HYPERCERT_LEXICONS);

Type Inheritance

This package is the source of truth for Hypercerts types. The SDK packages re-export these types with friendly aliases:

@hypercerts-org/lexicon
├── OrgHypercertsClaim.Main      → sdk-core: HypercertClaim
├── OrgHypercertsClaimRights.Main → sdk-core: HypercertRights
├── OrgHypercertsCollection.Main  → sdk-core: HypercertCollection
└── ...etc

Recommendation: Import types from @hypercerts-org/sdk-core for cleaner imports, unless you need direct access to validation functions.

Development

Regenerating Types

Types are generated from the lexicon JSON files using @atproto/lex-cli:

pnpm generate  # Regenerates src/types/ from lexicons/
pnpm build     # Build the package

Adding New Lexicons

1. Add lexicon JSON file to lexicons/ directory
2. Run pnpm generate to regenerate types
3. Export new types from src/index.ts
4. Update HYPERCERT_COLLECTIONS if adding a new collection

Certified Lexicons

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

Common Definitions

Lexicon ID: app.certified.defs

Description: Common type definitions used across all certified protocols.

Defs

| Def | Type | Description | Comments | |-----|------|-------------|----------| | uri | string | URI to external data | | | smallBlob | blob | Data stored in a PDS (up to 10MB) | | | largeBlob | blob | Data stored in a PDS (up to 100MB) | |

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 Record

Lexicon ID: org.hypercerts.claim.record

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 blob | | | workScope | string | ✅ | Scope of the work performed | | | workTimeframeFrom | string | ✅ | When the work began | | | workTimeFrameTo | string | ✅ | When the work ended | | | evidence | array | ❌ | Supporting evidence, documentation, or external data URIs | References must conform to org.hypercerts.claim.evidence | | contributions | array | ❌ | A strong reference to the contributions done to create the impact in the hypercerts | References must conform to org.hypercerts.claim.contributions | | 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 org.hypercerts.claim.location | | createdAt | string | ✅ | Client-declared timestamp when this record was originally created | |

Hypercerts Contributor

Lexicon ID: org.hypercerts.claim.contribution

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

Key: any

Properties

| Property | Type | Required | Description | Comments | |----------|------|----------|-------------|----------| | hypercert | ref | ✅ | A strong reference to the hypercert this contribution is for | The record referenced must conform with the lexicon org.hypercerts.claim.record | | 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 | | | workTimeframeFrom | string | ❌ | When this contribution started. This should be a subset of the hypercert timeframe. | | | workTimeframeTo | 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 | | | 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 | |----------|------|----------|-------------|----------| | content | union | ✅ | A piece of evidence (URI or blobs) supporting a hypercert claim | | | title | string | ❌ | Optional 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 | |----------|------|----------|-------------|----------| | hypercert | ref | ✅ | A strong reference to the hypercert that this measurement is for | The record referenced must conform with the lexicon org.hypercerts.claim.record | | measurers | array | ✅ | DIDs of the entity (or entities) that measured this data. | | | metric | string | ✅ | The metric being measured | | | value | string | ✅ | The measured value | | | measurementMethodURI | string | ❌ | URI to methodology documentation, standard protocol, or measurement procedure | | | evidenceURI | array | ❌ | URIs to supporting evidence or data | | | createdAt | string | ✅ | Client-declared timestamp when this record was originally created | |

org.hypercerts.collection

Lexicon ID: org.hypercerts.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.record | | | 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 | | | 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