@hypercerts-org/lexicon 0.12.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +92 -9
  3. package/SCHEMAS.md +122 -106
  4. package/dist/exports.d.ts +39 -2
  5. package/dist/exports.d.ts.map +1 -1
  6. package/dist/generated/exports.d.ts +39 -2
  7. package/dist/generated/exports.d.ts.map +1 -1
  8. package/dist/generated/lexicons.d.ts +74 -10
  9. package/dist/generated/lexicons.d.ts.map +1 -1
  10. package/dist/generated/types/app/certified/graph/follow.d.ts +18 -0
  11. package/dist/generated/types/app/certified/graph/follow.d.ts.map +1 -0
  12. package/dist/generated/types/app/certified/location.d.ts +1 -1
  13. package/dist/generated/types/app/certified/location.d.ts.map +1 -1
  14. package/dist/generated/types/org/hypercerts/workscope/tag.d.ts +2 -2
  15. package/dist/generated/types/org/hypercerts/workscope/tag.d.ts.map +1 -1
  16. package/dist/index.cjs +323 -224
  17. package/dist/index.cjs.map +1 -1
  18. package/dist/index.mjs +315 -220
  19. package/dist/index.mjs.map +1 -1
  20. package/dist/lexicons.cjs +38 -5
  21. package/dist/lexicons.cjs.map +1 -1
  22. package/dist/lexicons.d.ts +74 -10
  23. package/dist/lexicons.d.ts.map +1 -1
  24. package/dist/lexicons.mjs +38 -5
  25. package/dist/lexicons.mjs.map +1 -1
  26. package/dist/types/app/certified/graph/follow.d.ts +18 -0
  27. package/dist/types/app/certified/graph/follow.d.ts.map +1 -0
  28. package/dist/types/app/certified/location.d.ts +1 -1
  29. package/dist/types/app/certified/location.d.ts.map +1 -1
  30. package/dist/types/org/hypercerts/workscope/tag.d.ts +2 -2
  31. package/dist/types/org/hypercerts/workscope/tag.d.ts.map +1 -1
  32. package/lexicons/app/certified/graph/follow.json +32 -0
  33. package/lexicons/app/certified/location.json +1 -1
  34. package/lexicons/org/hypercerts/claim/activity.json +2 -2
  35. package/lexicons/org/hypercerts/workscope/tag.json +2 -2
  36. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,45 @@
1
1
  # @hypercerts-org/lexicon
2
2
 
3
+ ## 1.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - [#220](https://github.com/hypercerts-org/hypercerts-lexicon/pull/220) [`dd78ed4`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/dd78ed41406b460cea6c407f789a5eb3ae8bd2f8) Thanks [@s-adamantine](https://github.com/s-adamantine)! - Promote `@hypercerts-org/lexicon` to v1.0.0 — first stable release.
8
+
9
+ This changeset contributes no schema or type changes of its own; it
10
+ exists solely to force a major version bump so the package crosses the
11
+ 0.x → 1.0 line. From v1.0.0 onward, the lexicons, TypeScript types,
12
+ and generated exports are considered stable for downstream consumers,
13
+ and the package follows standard SemVer semantics: breaking changes
14
+ bump the major version, non-breaking additions the minor version, and
15
+ fixes the patch version. (Prior to v1.0.0, breaking changes were
16
+ allowed under `minor` per the SemVer 0.x convention — see
17
+ `.claude/skills/writing-changesets/SKILL.md`.)
18
+
19
+ Any other changesets pending at the time this one is consumed are
20
+ folded into the same v1.0.0 release; see the other entries below for
21
+ those contributions.
22
+
23
+ ### Minor Changes
24
+
25
+ - [#212](https://github.com/hypercerts-org/hypercerts-lexicon/pull/212) [`871608f`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/871608f50fc4a16d4290e56f02035574d71be8ed) Thanks [@Kzoeps](https://github.com/Kzoeps)! - Increase the free-form activity work scope string limit from 100 to 1,000 graphemes, with a 10,000-byte cap.
26
+
27
+ The previous 100-grapheme limit was too tight for simple work scope descriptions: if the relevant terms are around 10–15 characters each, the field only fits roughly 5–6 words. Gainforest hit this limit while implementing the work scope string field and had to move to the CEL-based work scope form earlier than intended.
28
+
29
+ Most invalid work scope records were caused by the newer typed shape requiring `$type`; the length cap only affects two known accounts at the time, so raising it fixes those without changing currently valid claims.
30
+
31
+ The string form is the simplest option for producers that do not need CEL's structured, machine-evaluable semantics. Raising the grapheme and byte limits keeps that simple path viable for concise natural-language scopes while CEL remains available for more complex tagging and query logic.
32
+
33
+ ## 0.13.0
34
+
35
+ ### Minor Changes
36
+
37
+ - [#209](https://github.com/hypercerts-org/hypercerts-lexicon/pull/209) [`8ec051f`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/8ec051faaf46b507409d97ca609b05fb8f318a3d) Thanks [@s-adamantine](https://github.com/s-adamantine)! - Add `app.certified.graph.follow` lexicon — a social-graph follow record schema-compatible with `app.bsky.graph.follow` (same `tid` key, same `subject` / `createdAt` / optional `via` strongRef fields). Exports new `GRAPH_FOLLOW_NSID`, `GRAPH_FOLLOW_LEXICON_JSON`, `GRAPH_FOLLOW_LEXICON_DOC`, and `AppCertifiedGraphFollow` type namespace.
38
+
39
+ ### Patch Changes
40
+
41
+ - [#213](https://github.com/hypercerts-org/hypercerts-lexicon/pull/213) [`80e5b42`](https://github.com/hypercerts-org/hypercerts-lexicon/commit/80e5b427b1e6886417d2db12017e7aa4a42a6482) Thanks [@s-adamantine](https://github.com/s-adamantine)! - Clarify that `knownValues` is an open vocabulary, not a closed enum. Adds a "Schema Conventions" section to README.md explaining that custom string values are permitted on any `knownValues` field (and contrasting with `enum`, which is closed and validator-enforced). Updates inline descriptions on `app.certified.location#locationType`, `org.hypercerts.workscope.tag#category`, and `org.hypercerts.workscope.tag#status` to explicitly note that values beyond the listed set are permitted — bringing them in line with the existing wording on `org.hypercerts.collection#type`, `org.hypercerts.context.attachment#contentType`, and `app.certified.badge.definition#badgeType`. The `locationType` description now also explicitly calls out that polygons / multipolygons / featurecollections use the catch-all `geojson` entry rather than a typed variant. Fixes a misleading line in STRING_CONSTRAINTS.md that conflated `knownValues` with `enum`. Documentation-only — no schema or type changes.
42
+
3
43
  ## 0.12.0
4
44
 
5
45
  ### Minor Changes
package/README.md CHANGED
@@ -45,6 +45,7 @@ CERTIFIED ─ shared lexicons (certified.app)
45
45
  actor/profile (user profile)
46
46
  actor/organization (org metadata)
47
47
  badge/response ──► badge/award ──► badge/definition
48
+ graph/follow ────────────► account DID (social follow)
48
49
  ```
49
50
 
50
51
  Every arrow (`►`) is a `strongRef` or union reference stored on the
@@ -266,18 +267,71 @@ await agent.api.com.atproto.repo.createRecord({
266
267
 
267
268
  ### Certified (`app.certified.*`)
268
269
 
269
- | Lexicon | NSID | Description |
270
- | -------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
271
- | **Location** | `app.certified.location` | Geographic reference using the [Location Protocol](https://spec.decentralizedgeo.org) (coordinates, GeoJSON, H3, WKT, etc.). |
272
- | **Profile** | `app.certified.actor.profile` | User account profile with display name, bio, avatar, and banner. |
273
- | **Organization** | `app.certified.actor.organization` | Organization metadata: legal structure, URLs, location, founding date, optional long description, and discoverability visibility. |
274
- | **Badge Definition** | `app.certified.badge.definition` | Defines a badge type with title, icon, and optional issuer allowlist. |
275
- | **Badge Award** | `app.certified.badge.award` | Awards a badge to a user, project, or activity. |
276
- | **Badge Response** | `app.certified.badge.response` | Recipient accepts or rejects a badge award. |
277
- | **EVM Link** | `app.certified.link.evm` | Verifiable ATProto DID ↔ EVM wallet link via EIP-712 signature. Extensible for future proof methods (e.g. ERC-1271, ERC-6492). |
270
+ | Lexicon | NSID | Description |
271
+ | -------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
272
+ | **Location** | `app.certified.location` | Geographic reference using the [Location Protocol](https://spec.decentralizedgeo.org) (coordinates, GeoJSON, H3, WKT, etc.). |
273
+ | **Profile** | `app.certified.actor.profile` | User account profile with display name, bio, avatar, and banner. |
274
+ | **Organization** | `app.certified.actor.organization` | Organization metadata: legal structure, URLs, location, founding date, optional long description, and discoverability visibility. |
275
+ | **Badge Definition** | `app.certified.badge.definition` | Defines a badge type with title, icon, and optional issuer allowlist. |
276
+ | **Badge Award** | `app.certified.badge.award` | Awards a badge to a user, project, or activity. |
277
+ | **Badge Response** | `app.certified.badge.response` | Recipient accepts or rejects a badge award. |
278
+ | **EVM Link** | `app.certified.link.evm` | Verifiable ATProto DID ↔ EVM wallet link via EIP-712 signature. Extensible for future proof methods (e.g. ERC-1271, ERC-6492). |
279
+ | **Follow** | `app.certified.graph.follow` | Social-graph follow relationship — declares that the author follows another account by DID. Schema-compatible with `app.bsky.graph.follow`. |
278
280
 
279
281
  > **Full property tables** → [SCHEMAS.md](SCHEMAS.md)
280
282
 
283
+ ## Schema Conventions
284
+
285
+ A few conventions are worth knowing before you start emitting records,
286
+ because they affect what counts as a "valid" record vs. one that breaks
287
+ interop with the wider ecosystem.
288
+
289
+ ### `knownValues` is an open vocabulary, not a closed enum
290
+
291
+ When you see `"knownValues": [...]` on a string field, those values are
292
+ **conventions for interoperability, not constraints.** Lexicon validators
293
+ do not reject values outside the list. The vocabulary is intentionally
294
+ open so applications can extend it with domain-specific variants without
295
+ waiting for a schema bump.
296
+
297
+ If the lexicon authors wanted a field to be closed, they would have used
298
+ `enum` instead — which the validator does enforce.
299
+
300
+ In practice:
301
+
302
+ - **Prefer a `knownValues` entry** when one matches your semantics. It
303
+ guarantees other Hypercerts-aware consumers (indexers, AppViews,
304
+ search facets, dropdown UIs) will recognize the value without
305
+ per-app special-casing.
306
+ - **Custom values are permitted** when no listed value fits. The record
307
+ is still wire-valid. Consumers that filter on the canonical list
308
+ simply won't categorize the value; consumers that read the raw string
309
+ will see whatever you wrote.
310
+ - **Custom values are at-your-own-risk for interop.** A custom
311
+ `locationType: "geojson-polygon"`, for example, is a perfectly valid
312
+ record — but a downstream tool that buckets by the Location Protocol
313
+ registry will treat it as "other". Use the closest `knownValues`
314
+ entry (here, `geojson`, which is the catch-all for non-Point GeoJSON)
315
+ when you want canonical bucketing.
316
+
317
+ When a `knownValues` list grows in a way that's broadly useful, open a
318
+ PR to add the new entry to the lexicon — that's how the canonical list
319
+ stays in sync with real-world usage.
320
+
321
+ ### `strongRef` pins to a specific record version
322
+
323
+ Fields typed as `com.atproto.repo.strongRef` carry both `uri` AND `cid`.
324
+ The `cid` is a content hash that pins the reference to the exact record
325
+ version at the time the reference was written — if the referenced
326
+ record is later overwritten, consumers can detect that the reference
327
+ has drifted.
328
+
329
+ This matters when you might otherwise be tempted to embed a full record
330
+ by value to "snapshot" it. A strongRef + CID already provides the
331
+ snapshot semantic, and it's what the lexicon uses across
332
+ `badge.award.badge`, `badge.response.badgeAward`, `funding.receipt.for`,
333
+ and similar fields where the historical content needs to stay stable.
334
+
281
335
  ## Entity Relationship Diagram
282
336
 
283
337
  ![Hypercert ERD](ERD.svg)
@@ -524,6 +578,35 @@ npm run gen-schemas-md # Regenerate SCHEMAS.md
524
578
  npm run test # Run tests
525
579
  ```
526
580
 
581
+ ### Following another account
582
+
583
+ The `app.certified.graph.follow` record is the social-graph primitive
584
+ for `certified.app`. Its shape is identical to `app.bsky.graph.follow`
585
+ (same `key: tid`, same `subject` / `createdAt` / optional `via`
586
+ fields), so feed-builders and view services can index it with the
587
+ same logic they already use for Bluesky follows.
588
+
589
+ ```typescript
590
+ import { GRAPH_FOLLOW_NSID } from "@hypercerts-org/lexicon";
591
+
592
+ const follow = {
593
+ $type: GRAPH_FOLLOW_NSID,
594
+ // DID of the account being followed (any valid DID — did:plc, did:web, etc.)
595
+ subject: "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
596
+ createdAt: new Date().toISOString(),
597
+ // Optional `via` strongRef — set when the follow was mediated by another
598
+ // record (e.g. a starter-pack-style curated list). Omit for direct follows.
599
+ // via: {
600
+ // uri: "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.certified.graph.starterpack/3k2abc",
601
+ // cid: "bafyreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy",
602
+ // },
603
+ };
604
+ ```
605
+
606
+ The optional `via` field is a `com.atproto.repo.strongRef` to any
607
+ record that mediated the follow (e.g. a starter pack or other curated
608
+ list), mirroring the equivalent field on `app.bsky.graph.follow`.
609
+
527
610
  ### Linking ATProto Identity to EVM Wallets
528
611
 
529
612
  The `app.certified.link.evm` record enables verifiable linking between
package/SCHEMAS.md CHANGED
@@ -36,35 +36,35 @@ Hypercerts-specific lexicons for tracking impact work and claims.
36
36
 
37
37
  A contributor to the activity, with identity, weight, and contribution details.
38
38
 
39
- | Property | Type | Required | Description |
40
- | --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41
- | `contributorIdentity` | `union` | ✅ | Inline contributor identity object with an identity string (DID or identifier) via org.hypercerts.claim.activity#contributorIdentity, or a strong reference to a contributor information record. The record referenced must conform with the lexicon org.hypercerts.claim.contributorInformation. |
42
- | `contributionWeight` | `string` | ❌ | The relative weight/importance of this contribution (stored as a string to avoid float precision issues). Must be a positive numeric value. Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed. |
43
- | `contributionDetails` | `union` | ❌ | Inline contribution role object with a role string via org.hypercerts.claim.activity#contributorRole, or a strong reference to a contribution details record. The record referenced must conform with the lexicon org.hypercerts.claim.contribution. |
39
+ | Property | Type | Required | Description | Comments |
40
+ | --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
41
+ | `contributorIdentity` | `union` | ✅ | Inline contributor identity object with an identity string (DID or identifier) via org.hypercerts.claim.activity#contributorIdentity, or a strong reference to a contributor information record. The record referenced must conform with the lexicon org.hypercerts.claim.contributorInformation. | |
42
+ | `contributionWeight` | `string` | ❌ | The relative weight/importance of this contribution (stored as a string to avoid float precision issues). Must be a positive numeric value. Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed. | maxLength: 100 |
43
+ | `contributionDetails` | `union` | ❌ | Inline contribution role object with a role string via org.hypercerts.claim.activity#contributorRole, or a strong reference to a contribution details record. The record referenced must conform with the lexicon org.hypercerts.claim.contribution. | |
44
44
 
45
45
  ##### `org.hypercerts.claim.activity#contributorIdentity`
46
46
 
47
47
  Contributor information as a string (DID or identifier).
48
48
 
49
- | Property | Type | Required | Description |
50
- | ---------- | -------- | -------- | ---------------------------------------------------- |
51
- | `identity` | `string` | ✅ | The contributor identity string (DID or identifier). |
49
+ | Property | Type | Required | Description | Comments |
50
+ | ---------- | -------- | -------- | ---------------------------------------------------- | ---------------------------------- |
51
+ | `identity` | `string` | ✅ | The contributor identity string (DID or identifier). | maxLength: 1000, maxGraphemes: 100 |
52
52
 
53
53
  ##### `org.hypercerts.claim.activity#contributorRole`
54
54
 
55
55
  Contribution details as a string.
56
56
 
57
- | Property | Type | Required | Description |
58
- | -------- | -------- | -------- | --------------------------------- |
59
- | `role` | `string` | ✅ | The contribution role or details. |
57
+ | Property | Type | Required | Description | Comments |
58
+ | -------- | -------- | -------- | --------------------------------- | ---------------------------------- |
59
+ | `role` | `string` | ✅ | The contribution role or details. | maxLength: 1000, maxGraphemes: 100 |
60
60
 
61
61
  ##### `org.hypercerts.claim.activity#workScopeString`
62
62
 
63
63
  A free-form string describing the work scope for simple or legacy scopes.
64
64
 
65
- | Property | Type | Required | Description |
66
- | -------- | -------- | -------- | ---------------------------------- |
67
- | `scope` | `string` | ✅ | The work scope description string. |
65
+ | Property | Type | Required | Description | Comments |
66
+ | -------- | -------- | -------- | ---------------------------------- | ------------------------------------ |
67
+ | `scope` | `string` | ✅ | The work scope description string. | maxLength: 10000, maxGraphemes: 1000 |
68
68
 
69
69
  ---
70
70
 
@@ -148,10 +148,10 @@ A free-form string describing the work scope for simple or legacy scopes.
148
148
 
149
149
  An item in a collection, with an identifier and optional weight.
150
150
 
151
- | Property | Type | Required | Description |
152
- | ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
153
- | `itemIdentifier` | `ref` | ✅ | Strong reference to an item in this collection. Items can be activities (org.hypercerts.claim.activity) and/or other collections (org.hypercerts.collection). |
154
- | `itemWeight` | `string` | ❌ | Optional weight for this item (positive numeric value stored as string). Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed. |
151
+ | Property | Type | Required | Description | Comments |
152
+ | ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
153
+ | `itemIdentifier` | `ref` | ✅ | Strong reference to an item in this collection. Items can be activities (org.hypercerts.claim.activity) and/or other collections (org.hypercerts.collection). | |
154
+ | `itemWeight` | `string` | ❌ | Optional weight for this item (positive numeric value stored as string). Weights do not need to sum to a specific total; normalization can be performed by the consuming application as needed. | maxLength: 100 |
155
155
 
156
156
  ---
157
157
 
@@ -220,11 +220,11 @@ An item in a collection, with an identifier and optional weight.
220
220
 
221
221
  Overall score for an evaluation on a numeric scale.
222
222
 
223
- | Property | Type | Required | Description |
224
- | -------- | -------- | -------- | ----------------------------------------------------------------------------- |
225
- | `min` | `string` | ✅ | Minimum value of the scale as a numeric string (e.g. '0', '1'). |
226
- | `max` | `string` | ✅ | Maximum value of the scale as a numeric string (e.g. '5', '10'). |
227
- | `value` | `string` | ✅ | Score within the inclusive range [min, max] as a numeric string (e.g. '3.7'). |
223
+ | Property | Type | Required | Description | Comments |
224
+ | -------- | -------- | -------- | ----------------------------------------------------------------------------- | ------------- |
225
+ | `min` | `string` | ✅ | Minimum value of the scale as a numeric string (e.g. '0', '1'). | maxLength: 50 |
226
+ | `max` | `string` | ✅ | Maximum value of the scale as a numeric string (e.g. '5', '10'). | maxLength: 50 |
227
+ | `value` | `string` | ✅ | Score within the inclusive range [min, max] as a numeric string (e.g. '3.7'). | maxLength: 50 |
228
228
 
229
229
  ---
230
230
 
@@ -283,9 +283,9 @@ Overall score for an evaluation on a numeric scale.
283
283
 
284
284
  A free-text string value (e.g. a display name, wallet address, or other identifier).
285
285
 
286
- | Property | Type | Required | Description |
287
- | -------- | -------- | -------- | ----------------- |
288
- | `value` | `string` | ✅ | The string value. |
286
+ | Property | Type | Required | Description | Comments |
287
+ | -------- | -------- | -------- | ----------------- | --------------- |
288
+ | `value` | `string` | ✅ | The string value. | maxLength: 2048 |
289
289
 
290
290
  ---
291
291
 
@@ -316,10 +316,10 @@ A free-text string value (e.g. a display name, wallet address, or other identifi
316
316
  | ------------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
317
317
  | `key` | `string` | ✅ | Lowercase, underscore-separated machine-readable key for this scope (e.g., 'mangrove_restoration', 'biodiversity_monitoring'). Used as the canonical identifier in CEL expressions. | maxLength: 120 |
318
318
  | `name` | `string` | ✅ | Human-readable name for this scope. | maxLength: 200 |
319
- | `category` | `string` | ❌ | Category type of this scope. | maxLength: 50, Known values: `topic`, `language`, `domain`, `method` |
319
+ | `category` | `string` | ❌ | Category type of this scope. Values beyond the known set are permitted. | maxLength: 50, Known values: `topic`, `language`, `domain`, `method` |
320
320
  | `description` | `string` | ❌ | Optional longer description of this scope. | maxLength: 10000, maxGraphemes: 1000 |
321
321
  | `parent` | `ref` | ❌ | Optional strong reference to a parent work scope tag record for taxonomy/hierarchy support. The record referenced must conform with the lexicon org.hypercerts.workscope.tag. | |
322
- | `status` | `string` | ❌ | Lifecycle status of this tag. Communities propose tags, curators accept them, deprecated tags point to replacements via supersededBy. | maxLength: 20, Known values: `proposed`, `accepted`, `deprecated` |
322
+ | `status` | `string` | ❌ | Lifecycle status of this tag. Communities propose tags, curators accept them, deprecated tags point to replacements via supersededBy. Values beyond the known set are permitted. | maxLength: 20, Known values: `proposed`, `accepted`, `deprecated` |
323
323
  | `supersededBy` | `ref` | ❌ | When status is 'deprecated', points to the replacement work scope tag record. The record referenced must conform with the lexicon org.hypercerts.workscope.tag. | |
324
324
  | `aliases` | `string[]` | ❌ | Alternative human-readable names for this scope (e.g., translations, abbreviations, or common synonyms). Unlike sameAs, these are plain-text labels, not links to external ontologies. | maxLength: 50 |
325
325
  | `sameAs` | `string[]` | ❌ | URIs to semantically equivalent concepts in external ontologies or taxonomies (e.g., Wikidata QIDs, ENVO terms, SDG targets). Used for interoperability, not as documentation. | maxLength: 20 |
@@ -340,15 +340,15 @@ Certified lexicons are common/shared lexicons that can be used across multiple p
340
340
 
341
341
  #### Properties
342
342
 
343
- | Property | Type | Required | Description | Comments |
344
- | -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
345
- | `lpVersion` | `string` | ✅ | The version of the Location Protocol | maxLength: 10 |
346
- | `srs` | `string` | ✅ | The Spatial Reference System URI (e.g., http://www.opengis.net/def/crs/OGC/1.3/CRS84) that defines the coordinate system. | maxLength: 100 |
347
- | `locationType` | `string` | ✅ | An identifier for the format of the location data (e.g., coordinate-decimal, geojson-point). See the Location Protocol spec for the full registry: https://spec.decentralizedgeo.org/specification/location-types/#location-type-registry | maxLength: 20, Known values: `coordinate-decimal`, `geojson-point`, `geojson`, `h3`, `geohash`, `wkt`, `address`, `scaledCoordinates` |
348
- | `location` | `union` | ✅ | The location of where the work was performed as a URI, blob, or inline string. | |
349
- | `name` | `string` | ❌ | Human-readable name for this location (e.g. 'Golden Gate Park', 'San Francisco Bay Area') | maxLength: 1000, maxGraphemes: 100 |
350
- | `description` | `string` | ❌ | Additional context about this location, such as its significance to the work or specific boundaries | maxLength: 2000, maxGraphemes: 500 |
351
- | `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | |
343
+ | Property | Type | Required | Description | Comments |
344
+ | -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
345
+ | `lpVersion` | `string` | ✅ | The version of the Location Protocol | maxLength: 10 |
346
+ | `srs` | `string` | ✅ | The Spatial Reference System URI (e.g., http://www.opengis.net/def/crs/OGC/1.3/CRS84) that defines the coordinate system. | maxLength: 100 |
347
+ | `locationType` | `string` | ✅ | An identifier for the format of the location data. Use `geojson-point` for a single GeoJSON Point; use `geojson` as the catch-all for any other GeoJSON geometry (Polygon, MultiPolygon, FeatureCollection, etc.) — the inner payload's own GeoJSON `type` field carries the specifics. Values beyond the known set are permitted; see the Location Protocol spec for the canonical registry: https://spec.decentralizedgeo.org/specification/location-types/#location-type-registry | maxLength: 20, Known values: `coordinate-decimal`, `geojson-point`, `geojson`, `h3`, `geohash`, `wkt`, `address`, `scaledCoordinates` |
348
+ | `location` | `union` | ✅ | The location of where the work was performed as a URI, blob, or inline string. | |
349
+ | `name` | `string` | ❌ | Human-readable name for this location (e.g. 'Golden Gate Park', 'San Francisco Bay Area') | maxLength: 1000, maxGraphemes: 100 |
350
+ | `description` | `string` | ❌ | Additional context about this location, such as its significance to the work or specific boundaries | maxLength: 2000, maxGraphemes: 500 |
351
+ | `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created | |
352
352
 
353
353
  #### Defs
354
354
 
@@ -356,9 +356,9 @@ Certified lexicons are common/shared lexicons that can be used across multiple p
356
356
 
357
357
  A location represented as a string, e.g. coordinates or a small GeoJSON string.
358
358
 
359
- | Property | Type | Required | Description |
360
- | -------- | -------- | -------- | ------------------------- |
361
- | `string` | `string` | ✅ | The location string value |
359
+ | Property | Type | Required | Description | Comments |
360
+ | -------- | -------- | -------- | ------------------------- | ------------------------------------ |
361
+ | `string` | `string` | ✅ | The location string value | maxLength: 10000, maxGraphemes: 1000 |
362
362
 
363
363
  ---
364
364
 
@@ -440,10 +440,10 @@ A location represented as a string, e.g. coordinates or a small GeoJSON string.
440
440
 
441
441
  A labeled URL reference.
442
442
 
443
- | Property | Type | Required | Description |
444
- | -------- | -------- | -------- | ---------------------------------------------------------------------------------- |
445
- | `url` | `string` | ✅ | The URL. |
446
- | `label` | `string` | ❌ | Optional human-readable label for this URL (e.g. 'Support page', 'Donation page'). |
443
+ | Property | Type | Required | Description | Comments |
444
+ | -------- | -------- | -------- | ---------------------------------------------------------------------------------- | ------------------------------------ |
445
+ | `url` | `string` | ✅ | The URL. | maxLength: 10000, maxGraphemes: 2048 |
446
+ | `label` | `string` | ❌ | Optional human-readable label for this URL (e.g. 'Support page', 'Donation page'). | maxLength: 640, maxGraphemes: 64 |
447
447
 
448
448
  ---
449
449
 
@@ -467,6 +467,22 @@ A labeled URL reference.
467
467
 
468
468
  ---
469
469
 
470
+ ### `app.certified.graph.follow`
471
+
472
+ **Description:** Record declaring a social 'follow' relationship of another account. Duplicate follows will be ignored by the AppView.
473
+
474
+ **Key:** `tid`
475
+
476
+ #### Properties
477
+
478
+ | Property | Type | Required | Description |
479
+ | ----------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
480
+ | `subject` | `string` | ✅ | DID of the account being followed. |
481
+ | `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created. |
482
+ | `via` | `ref` | ❌ | Optional strong reference to a record that mediated this follow (e.g. a starter pack or other curated list). Mirrors the optional `via` field on app.bsky.graph.follow; the referenced record may conform with any lexicon. |
483
+
484
+ ---
485
+
470
486
  ### `app.certified.link.evm`
471
487
 
472
488
  **Description:** A verifiable link between an ATProto DID and an EVM wallet address, proven via a cryptographic signature. Currently supports EOA wallets via EIP-712 typed data signatures; the proof field is an open union to allow future signature methods.
@@ -487,22 +503,22 @@ A labeled URL reference.
487
503
 
488
504
  EOA wallet ownership proof via EIP-712 typed data signature. Contains both the structured message that was signed and the resulting signature.
489
505
 
490
- | Property | Type | Required | Description |
491
- | ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
492
- | `signature` | `string` | ✅ | ECDSA signature over the EIP-712 hash (hex-encoded with 0x prefix, 64 or 65 bytes). |
493
- | `message` | `ref` | ✅ | The EIP-712 typed data message that was signed by the wallet. Contains the fields binding an ATProto DID to an EVM address on a specific chain. |
506
+ | Property | Type | Required | Description | Comments |
507
+ | ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
508
+ | `signature` | `string` | ✅ | ECDSA signature over the EIP-712 hash (hex-encoded with 0x prefix, 64 or 65 bytes). | maxLength: 132 |
509
+ | `message` | `ref` | ✅ | The EIP-712 typed data message that was signed by the wallet. Contains the fields binding an ATProto DID to an EVM address on a specific chain. | |
494
510
 
495
511
  ##### `app.certified.link.evm#eip712Message`
496
512
 
497
513
  The EIP-712 typed data message that was signed by the wallet. Contains the fields binding an ATProto DID to an EVM address on a specific chain.
498
514
 
499
- | Property | Type | Required | Description |
500
- | ------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
501
- | `did` | `string` | ✅ | The ATProto DID being linked to the EVM address. |
502
- | `evmAddress` | `string` | ✅ | The EVM wallet address (must match the top-level address field). |
503
- | `chainId` | `string` | ✅ | EVM chain ID as string (bigint serialized). Identifies which chain was used for signing; for EOA wallets the identity link applies across all EVM-compatible chains. |
504
- | `timestamp` | `string` | ✅ | Unix timestamp when the attestation was created (bigint serialized). |
505
- | `nonce` | `string` | ✅ | Replay-protection nonce (bigint serialized). |
515
+ | Property | Type | Required | Description | Comments |
516
+ | ------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
517
+ | `did` | `string` | ✅ | The ATProto DID being linked to the EVM address. | maxLength: 256 |
518
+ | `evmAddress` | `string` | ✅ | The EVM wallet address (must match the top-level address field). | maxLength: 42 |
519
+ | `chainId` | `string` | ✅ | EVM chain ID as string (bigint serialized). Identifies which chain was used for signing; for EOA wallets the identity link applies across all EVM-compatible chains. | maxLength: 78 |
520
+ | `timestamp` | `string` | ✅ | Unix timestamp when the attestation was created (bigint serialized). | maxLength: 78 |
521
+ | `nonce` | `string` | ✅ | Replay-protection nonce (bigint serialized). | maxLength: 78 |
506
522
 
507
523
  ---
508
524
 
@@ -520,9 +536,9 @@ Common type definitions used across all protocols.
520
536
 
521
537
  A Decentralized Identifier (DID) string.
522
538
 
523
- | Property | Type | Required | Description |
524
- | -------- | -------- | -------- | --------------------- |
525
- | `did` | `string` | ✅ | The DID string value. |
539
+ | Property | Type | Required | Description | Comments |
540
+ | -------- | -------- | -------- | --------------------- | -------------- |
541
+ | `did` | `string` | ✅ | The DID string value. | maxLength: 256 |
526
542
 
527
543
  ---
528
544
 
@@ -536,10 +552,10 @@ A Decentralized Identifier (DID) string.
536
552
 
537
553
  An inline long-form description as plain text or markdown, with optional rich-text annotations.
538
554
 
539
- | Property | Type | Required | Description |
540
- | -------- | -------- | -------- | -------------------------------------------------------------------------- |
541
- | `value` | `string` | ✅ | The description text (plain text or markdown). |
542
- | `facets` | `ref[]` | ❌ | Rich text annotations for the description (mentions, URLs, hashtags, etc). |
555
+ | Property | Type | Required | Description | Comments |
556
+ | -------- | -------- | -------- | -------------------------------------------------------------------------- | -------------------------------------- |
557
+ | `value` | `string` | ✅ | The description text (plain text or markdown). | maxLength: 250000, maxGraphemes: 25000 |
558
+ | `facets` | `ref[]` | ❌ | Rich text annotations for the description (mentions, URLs, hashtags, etc). | |
543
559
 
544
560
  ##### `org.hypercerts.defs#uri`
545
561
 
@@ -553,41 +569,41 @@ Object containing a URI to external data
553
569
 
554
570
  Object containing a blob to external data
555
571
 
556
- | Property | Type | Required | Description |
557
- | -------- | ------ | -------- | ---------------------------------- |
558
- | `blob` | `blob` | ✅ | Blob to external data (up to 10MB) |
572
+ | Property | Type | Required | Description | Comments |
573
+ | -------- | ------ | -------- | ---------------------------------- | --------------------------------- |
574
+ | `blob` | `blob` | ✅ | Blob to external data (up to 10MB) | maxSize: 10485760, accepts: `*/*` |
559
575
 
560
576
  ##### `org.hypercerts.defs#largeBlob`
561
577
 
562
578
  Object containing a blob to external data
563
579
 
564
- | Property | Type | Required | Description |
565
- | -------- | ------ | -------- | ----------------------------------- |
566
- | `blob` | `blob` | ✅ | Blob to external data (up to 100MB) |
580
+ | Property | Type | Required | Description | Comments |
581
+ | -------- | ------ | -------- | ----------------------------------- | ---------------------------------- |
582
+ | `blob` | `blob` | ✅ | Blob to external data (up to 100MB) | maxSize: 104857600, accepts: `*/*` |
567
583
 
568
584
  ##### `org.hypercerts.defs#smallImage`
569
585
 
570
586
  Object containing a small image
571
587
 
572
- | Property | Type | Required | Description |
573
- | -------- | ------ | -------- | ----------------- |
574
- | `image` | `blob` | ✅ | Image (up to 5MB) |
588
+ | Property | Type | Required | Description | Comments |
589
+ | -------- | ------ | -------- | ----------------- | ------------------------------------------------------------------------------- |
590
+ | `image` | `blob` | ✅ | Image (up to 5MB) | maxSize: 5242880, accepts: `image/jpeg`, `image/jpg`, `image/png`, `image/webp` |
575
591
 
576
592
  ##### `org.hypercerts.defs#smallVideo`
577
593
 
578
594
  Object containing a small video
579
595
 
580
- | Property | Type | Required | Description |
581
- | -------- | ------ | -------- | ------------------ |
582
- | `video` | `blob` | ✅ | Video (up to 20MB) |
596
+ | Property | Type | Required | Description | Comments |
597
+ | -------- | ------ | -------- | ------------------ | ----------------------------------------------------- |
598
+ | `video` | `blob` | ✅ | Video (up to 20MB) | maxSize: 20971520, accepts: `video/mp4`, `video/webm` |
583
599
 
584
600
  ##### `org.hypercerts.defs#largeImage`
585
601
 
586
602
  Object containing a large image
587
603
 
588
- | Property | Type | Required | Description |
589
- | -------- | ------ | -------- | ------------------ |
590
- | `image` | `blob` | ✅ | Image (up to 10MB) |
604
+ | Property | Type | Required | Description | Comments |
605
+ | -------- | ------ | -------- | ------------------ | -------------------------------------------------------------------------------- |
606
+ | `image` | `blob` | ✅ | Image (up to 10MB) | maxSize: 10485760, accepts: `image/jpeg`, `image/jpg`, `image/png`, `image/webp` |
591
607
 
592
608
  ---
593
609
 
@@ -628,9 +644,9 @@ Facet feature for a URL. The text URL may have been simplified or truncated, but
628
644
 
629
645
  Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').
630
646
 
631
- | Property | Type | Required | Description |
632
- | -------- | -------- | -------- | ----------- |
633
- | `tag` | `string` | ✅ | |
647
+ | Property | Type | Required | Description | Comments |
648
+ | -------- | -------- | -------- | ----------- | -------------------------------- |
649
+ | `tag` | `string` | ✅ | | maxLength: 640, maxGraphemes: 64 |
634
650
 
635
651
  ##### `app.bsky.richtext.facet#byteSlice`
636
652
 
@@ -675,33 +691,33 @@ Specifies the sub-string range a facet feature applies to. Start index is inclus
675
691
 
676
692
  Visual configuration for a hyperboard's background, colors, and layout.
677
693
 
678
- | Property | Type | Required | Description |
679
- | --------------------- | --------- | -------- | --------------------------------------------------------------------- |
680
- | `backgroundType` | `string` | ❌ | Type of background content. |
681
- | `backgroundImage` | `union` | ❌ | Background image as a URI or image blob. |
682
- | `backgroundIframeUrl` | `string` | ❌ | URI of the background iframe. |
683
- | `backgroundGrayscale` | `boolean` | ❌ | Whether the background is rendered in grayscale. Default: true. |
684
- | `backgroundOpacity` | `integer` | ❌ | Background opacity as a percentage (0–100). |
685
- | `backgroundColor` | `string` | ❌ | Background color as a hex string (e.g. '#ffffff'). |
686
- | `borderColor` | `string` | ❌ | Border color as a hex string (e.g. '#000000'). |
687
- | `grayscaleImages` | `boolean` | ❌ | Whether contributor images are rendered in grayscale. Default: false. |
688
- | `imageShape` | `string` | ❌ | Shape used to crop contributor images on this board. |
689
- | `aspectRatio` | `string` | ❌ | Display aspect ratio of the board. |
694
+ | Property | Type | Required | Description | Comments |
695
+ | --------------------- | --------- | -------- | --------------------------------------------------------------------- | ------------------------------------------------- |
696
+ | `backgroundType` | `string` | ❌ | Type of background content. | maxLength: 10, Known values: `image`, `iframe` |
697
+ | `backgroundImage` | `union` | ❌ | Background image as a URI or image blob. | |
698
+ | `backgroundIframeUrl` | `string` | ❌ | URI of the background iframe. | maxLength: 2048 |
699
+ | `backgroundGrayscale` | `boolean` | ❌ | Whether the background is rendered in grayscale. Default: true. | |
700
+ | `backgroundOpacity` | `integer` | ❌ | Background opacity as a percentage (0–100). | |
701
+ | `backgroundColor` | `string` | ❌ | Background color as a hex string (e.g. '#ffffff'). | maxLength: 20 |
702
+ | `borderColor` | `string` | ❌ | Border color as a hex string (e.g. '#000000'). | maxLength: 20 |
703
+ | `grayscaleImages` | `boolean` | ❌ | Whether contributor images are rendered in grayscale. Default: false. | |
704
+ | `imageShape` | `string` | ❌ | Shape used to crop contributor images on this board. | maxLength: 20, Known values: `circular`, `square` |
705
+ | `aspectRatio` | `string` | ❌ | Display aspect ratio of the board. | maxLength: 10, Known values: `16:9`, `4:3`, `1:1` |
690
706
 
691
707
  ##### `org.hyperboards.board#contributorConfig`
692
708
 
693
709
  Configuration for a specific contributor within a board. Values serve as fallbacks when the contributor has not defined them on their profile. It can also be used to override contributor settings on this board without changing their global profile.
694
710
 
695
- | Property | Type | Required | Description |
696
- | ---------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
697
- | `contributor` | `union` | ✅ | Identifies the contributor being styled. A strong reference to an org.hypercerts.claim.contributorInformation record, or a contributorIdentity (DID or identifier string) for contributors without a dedicated record. |
698
- | `override` | `boolean` | ❌ | When true, these values take precedence over the contributor's own profile and display settings. When false or omitted, they are only used as fallbacks if the contributor has not set their own settings. |
699
- | `displayName` | `string` | ❌ | Display name for this contributor on this board. |
700
- | `image` | `union` | ❌ | Avatar or face image for this contributor on this board, as a URI or image blob. |
701
- | `video` | `union` | ❌ | Video for this contributor, as a URI (embed/direct link) or uploaded video blob. |
702
- | `hoverImage` | `union` | ❌ | Image overlay shown when hovering over this contributor, as a URI or image blob. |
703
- | `hoverIframeUrl` | `string` | ❌ | Iframe overlay shown when hovering over this contributor. |
704
- | `url` | `string` | ❌ | Click-through link URL for this contributor. |
711
+ | Property | Type | Required | Description | Comments |
712
+ | ---------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
713
+ | `contributor` | `union` | ✅ | Identifies the contributor being styled. A strong reference to an org.hypercerts.claim.contributorInformation record, or a contributorIdentity (DID or identifier string) for contributors without a dedicated record. | |
714
+ | `override` | `boolean` | ❌ | When true, these values take precedence over the contributor's own profile and display settings. When false or omitted, they are only used as fallbacks if the contributor has not set their own settings. | |
715
+ | `displayName` | `string` | ❌ | Display name for this contributor on this board. | maxLength: 640, maxGraphemes: 64 |
716
+ | `image` | `union` | ❌ | Avatar or face image for this contributor on this board, as a URI or image blob. | |
717
+ | `video` | `union` | ❌ | Video for this contributor, as a URI (embed/direct link) or uploaded video blob. | |
718
+ | `hoverImage` | `union` | ❌ | Image overlay shown when hovering over this contributor, as a URI or image blob. | |
719
+ | `hoverIframeUrl` | `string` | ❌ | Iframe overlay shown when hovering over this contributor. | maxLength: 2048 |
720
+ | `url` | `string` | ❌ | Click-through link URL for this contributor. | maxLength: 2048 |
705
721
 
706
722
  ---
707
723
 
@@ -932,10 +948,10 @@ Configuration for a specific contributor within a board. Values serve as fallbac
932
948
 
933
949
  ##### `pub.leaflet.pages.linearDocument#block`
934
950
 
935
- | Property | Type | Required | Description |
936
- | ----------- | -------- | -------- | ----------- |
937
- | `block` | `union` | ✅ | |
938
- | `alignment` | `string` | ❌ | |
951
+ | Property | Type | Required | Description | Comments |
952
+ | ----------- | -------- | -------- | ----------- | ------------------------------------------------------------------------------------------ |
953
+ | `block` | `union` | ✅ | | |
954
+ | `alignment` | `string` | ❌ | | Known values: `#textAlignLeft`, `#textAlignCenter`, `#textAlignRight`, `#textAlignJustify` |
939
955
 
940
956
  ##### `pub.leaflet.pages.linearDocument#quote`
941
957