Reference

The Gifthood lexicon

On the open network, a Lexicon is the shared grammar that lets independent apps understand each other's data. This is ours — the handful of record types Gifthood writes to your repo, defined plainly, with the exact shapes underneath.

How to read this

* marks a required field.
offer is an enum value — one of the exact strings a field accepts.
graphemes are user-perceived characters, not bytes — the real limit a person types.

listing

· record

community.gifthood.listing · keyed by tid

An offer or a request, set down where the neighbors closest to it will notice. A listing is the smallest unit of giving here — one thing you’re passing on, or one thing you’re hoping someone nearby can spare.

“Maria’s done with the crib. She posts a listing, and the blocks around her are the first to see it.”

Fields * required

title*: string · 1–100 graphemes

Required short title for the item being offered or requested.
description*: string · 1–1500 graphemes

Required free text describing the item being offered or requested.
intent*: string

offerrequest

Whether the poster is giving away an item or looking for one.
status: string

availablependinggone

Current availability. Clients should treat a missing value as 'available'.
geohash*: string · ≤6 chars

Approximate location as a geohash, precision 6 (~1.2km cell). This is a privacy floor: indexers MUST truncate any finer-precision value to 6 characters before indexing or display.
locationName: string · ≤100 graphemes

Optional human-readable area name. App-populated via reverse geocoding of the geohash cell. Display only; MUST NOT be used for proximity matching or filtering.
images: blob[] · ≤4 · jpeg/png/webp · ≤1 MB

Up to 4 images of the item, stored as blobs in the poster's repo.
imageAlts: string[] · ≤4 · ≤1000 graphemes

Alt text for images, parallel to the images array by index.
category: string

one of 16: furniture, kitchen, clothing, baby, books, instruments, electronics, tools, garden, health, pets, hobbies, food, animals, service, other

Optional single-level category for opt-out feed filtering. Append-only enum; unknown or missing values index as 'other'. Never used for proximity or safety logic.
langs: string[] · ≤3 · language

Language(s) the content is written in, as BCP-47 language tags. Author-asserted; clients default from the composer's locale.
facets: facet[]

Annotations over `description` (mentions, links) keyed by UTF-8 byte range. Reuses app.bsky.richtext.facet for atmosphere-wide interop. Author-asserted at compose time; clients MUST treat them as display hints, re-validate ranges, and never trust a facet URI over the visible text. Addresses and phone numbers are deliberately NOT faceted here — those affordances are direct-message-only.
labels: union · label.defs

Self-labels set by the author. Used to flag mature/adult content (e.g. the global 'sexual' value), which the AppView gates behind an opt-in.
createdAt*: datetime

↪ borrows facet · label.defs

profile

· record

community.gifthood.actor.profile · keyed by literal:self

How a neighbor shows up in Gifthood. It’s yours to set, and it sits lightly over your wider network identity: fill in a field and it speaks for you here; leave it blank and your Bluesky profile shows through.

“The same face you bring to the rest of the open network — with the parts particular to giving laid over the top.”

Fields * required

displayName: string · ≤64 graphemes

Gifthood display name. Overrides the Bluesky display name when set.
description: string · ≤256 graphemes

Gifthood bio. Overrides the Bluesky description when set.
pronouns: string · ≤20 graphemes

Free-form pronouns. Overrides the Bluesky pronouns when set.
website: uri

A personal link. Overrides the Bluesky website when set.
avatar: blob · png/jpeg · ≤1 MB

Avatar image blob in the member's repo. Overrides the Bluesky avatar when set.
banner: blob · png/jpeg · ≤1 MB

Banner image blob in the member's repo.
createdAt*: datetime

The gifthood join date. Write-once: edits MUST preserve it.

follow

· record

community.gifthood.follow · keyed by tid

A quiet way of saying you’d like to keep up with a neighbor. Following is public and entirely yours to give or take back, and it keeps a generous neighbor’s comings and goings within reach.

“You liked how someone gives — generous, no fuss. A follow keeps their offers in view.”

Fields * required

subject*: did

The DID of the member being followed.
createdAt*: datetime

interest

· record

community.gifthood.interest · keyed by tid

Raising your hand for a listing. Interest is a public note that says you’d like the thing — a first hello. The where and when of a hand-off happen off to the side, in a direct message, not here in the open.

“‘Still available?’ — a raised hand for the bookshelf; the rest gets sorted in a message.”

Fields * required

subject*: ref → strongRef

Strong reference (URI + CID) to the listing this interest refers to.
message: string · ≤300 graphemes

Optional short public note (e.g. 'still available?'). Pickup details belong in direct messages, not here.
langs: string[] · ≤3 · language

Language(s) the message is written in, as BCP-47 language tags. Author-asserted; clients default from the composer's locale.
facets: facet[]

Annotations over `message` (mentions, links) keyed by UTF-8 byte range. Reuses app.bsky.richtext.facet for atmosphere-wide interop. Author-asserted at compose time; clients MUST treat them as display hints, re-validate ranges, and never trust a facet URI over the visible text. Addresses and phone numbers are deliberately NOT faceted here — those affordances are direct-message-only.
createdAt*: datetime

↪ borrows strongRef · facet

Loanwords

Words Gifthood borrows from the open network rather than coining its own — so the records interoperate with the wider atmosphere instead of standing apart.

com.atproto.repo.strongRef AT Protocol core: Lets an interest point at exactly one listing — by address and content hash — so it can't be quietly swapped underneath.
app.bsky.richtext.facet Bluesky: Marks up the mentions and links inside a description or message the same way the rest of the network does, so other apps understand them too.
com.atproto.label.defs AT Protocol moderation: The shared vocabulary of content labels, so a poster can flag their own listing as mature and every client can honor it.