Social specs, sub-specs and who indexes what

This is the data model pubky.app and the apps around it share: what lives on the homeserver, which spec defines it, which indexer reads it, and what you can build on today. Each part says if it is built, merged in our Nexus fork, a draft or only planned. Section 9 lists the questions where we want the team's view.

1. Summary and the layers

• Every object lives on the user's homeserver. Public data is under /pub/, private data under /priv/. Indexers only read /pub/.
• pubky-social-specs defines what several apps must read: profile, posts, tags, follows, bookmarks, collections, files, feeds, mutes (1.0), and event, rsvp, rating, availability (1.1). Paths are /{pub,priv}/social/v1/….
• Sub-specs are an app's own post kinds on the same post envelope under /{pub,priv}/<ns>/v1/posts/: route (maps), listing, drop, shop (marketplace), listen, listening, session (music). Each lives in the app's own repo.
• Nexus indexes the social graph and the social kinds. It treats every app namespace the same way and reads no app content. We keep it as small as we can.
• Pinakes indexes external resources (web pages, places, events, books, music…) and gives app posts a card. It ranks and searches; it holds no posts, users or tags.
• Rule for clients: Pinakes ranks, Nexus hydrates. They join only by URI.

2. Where a kind lives

Owner decisions from 24 to 27 October fix one rule: a kind goes in the social specs (and so into Nexus) only if other apps must read it. Everything else belongs to an app. Ask the questions below in order; the first "yes" decides.

Rules a sub-spec follows

• Namespace: 1 to 32 characters of a-z, 0-9, -, starting with a letter, no dot. social is reserved. One per app family. Public sub-spec namespaces are music, maps, marketplace and events.
• Paths: a version is /{pub,priv}/<ns>/v1/posts/{id}/{editId}[-{slug}].json; references name the post versionless: pubky://{owner}/{pub,priv}/<ns>/v1/posts/{id}.
• v1 is the envelope's version, not the app's. Content changes are additive; a change that cannot be additive becomes a new kind name.
• Values: instants are *_at in integer microseconds; durations end in their unit (_ms, _s, _days) unless JSCalendar names them; places are canonical OSM object URLs or geo: pins; money is {amount_minor, currency, exponent}; the cover image is attachments[0].
• A sub-spec may not define a kind that repeats a primitive or a social kind, may not need Nexus code, and names no client.

3. Social specs 1.0 and 1.1

Built 1.0 is released as 1.0.0-rc.1 on crates.io and npm (pubky-social-specs, plus pubky-social-migrator for 0.x data). Draft spec 1.1 is draft PR pubky/pubky-social-specs#207, branch v1.1-subspecs, head 8e7f1ad, crate version 1.1.0-alpha.1 (not published). 1.1 changes nothing in 1.0: a 1.0 reader reads a 1.1 post as a kind it does not know and skips it.

The post envelope (1.0)

Every post, social or sub-spec, is PostEnvelope<K>. Only the kind set and the rules for content differ.

Ids are timestamp ids. A post is a folder of versions: /pub/social/v1/posts/{id}/{editId}[-{slug}].json. An edit writes a new version; the indexer keeps the newest. A public post can never reference a private object (the gate refuses it).

1.0 objects

1.0 post kinds

1.1 kinds Draft spec

Four kinds on the same envelope under social. Member names follow JSCalendar (RFC 8984), so iCalendar import and export are renames. Times are local: start is a wall-clock time in timeZone, and the indexer computes the instant.

{
  "title": "Lugano Bitcoin Evening",
  "description": "Monthly meetup. Talks start at 19:00.",
  "start": "2026-10-14T18:30:00",
  "timeZone": "Europe/Zurich",
  "duration": "PT2H30M",
  "status": "confirmed",
  "locations": [{ "name": "Plan ₿ Hub",
    "uri": "https://www.openstreetmap.org/way/481516234" }],
  "attendance": { "policy": "open", "capacity": null,
                  "waitlist": false },
  "links": [{ "title": "Website",
              "url": "https://planb.network/" }],
  "recurrenceRules": [{ "frequency": "monthly",
    "byDay": [{ "day": "tu", "nthOfPeriod": 2 }] }]
}

{ "status": "accepted",
  "recurrenceId": "2026-11-10T18:30:00",
  "guests": 1, "note": "bringing cake" }

{ "kind": "rating",
  "parent": "https://www.openstreetmap.org/node/240109189",
  "content": "{\"rating\":7,\"text\":\"great coffee\"}",
  "attachments": [] }

availability

When a person, or a resource of theirs, can be booked: a public, coarse schedule the client derives from its private calendar and bookings. One current post per author per for (absent for means the author). Blocks have start, duration, optional recurrence; available blocks may carry title and capacity (units free). Slots are derived, never stored. Prices and booking rules go in ext.<ns> or the app's own kind.

{
  "timeZone": "Europe/Zurich", "horizonDays": 60,
  "for": "pubky://<owner>/pub/marketplace/v1/posts/0032SSN7Q4EVG",
  "available": [{ "title": "Double room", "start": "2026-10-19T14:00:00", "duration": "P1D",
                  "capacity": 12, "recurrenceRules": [{ "frequency": "daily" }] }],
  "busy": [{ "start": "2026-10-24T14:00:00", "duration": "P2D" }]
}

Places (1.1 writer conventions)

No object has a location field. A located post is a post whose parent or embed (or an event's locations[].uri) is a place. Two spellings make every writer land on one resource:

• An OSM place: https://www.openstreetmap.org/{node|way|relation}/{id}, nothing else. Map view links (#map=, ?mlat=, osm.org) are not places; the client turns them into a pin or a reverse lookup before writing.
• A coordinate: geo:<lat>,<lon>, at most 5 decimals (about 1 m), no trailing zeros. Fewer digits for a rough spot: 3 is about 100 m.

The conventions are enforced in the 1.1 place positions (event locations, sub-spec place fields such as route waypoints). In parent, embed, tags and collection items they are what a 1.1 client writes, but the 1.0 gate does not check them.

Calendars

There is no calendar kind. A calendar is a collection of event URIs, public or private, at most 100 items. Items are universal, so a Luma page or an .ics feed sits next to Pubky events.

4. Sub-specs: maps, marketplace, music, events

Each sub-spec is a Rust crate in the app's own repo, built on pubky_social_specs::subspec. None of them needs anything from Nexus. The maps, marketplace and events crates are not pushed to a repository yet, and pin social at 6baa542 (before availability became a social kind).

Maps: route

A saved route: ordered waypoints (2 to 100, each a place under the conventions), an encoded polyline with the engine and profile that made it, distance, duration, elevation, optional steps. parent is refused; embed may name the trail it follows (an OSM relation). Directions are not stored; a route reaches Pubky only when someone saves it.

{ "name": "Lakeside loop", "activity": "running",
  "waypoints": [{ "uri": "geo:46.00547,8.95186", "name": "Start" },
                { "uri": "https://www.openstreetmap.org/node/240109189" }],
  "polyline": { "encoded": "_p~iF~ps|U_ulLnnqC_mqNvxq`@", "engine": "valhalla",
                "profile": "pedestrian", "precision": 6 },
  "distance_m": 5200, "duration_s": 1800, "elevation_gain_m": 12, "elevation_loss_m": 12 }

Marketplace: listing, drop, shop, and reviews

• listing: something for sale. Title, description, state (active, paused, ended, removed), category, condition, optional location.uri (a place), variants, a sale (fixed_price or auction), fulfillment, shipping, returns, adult_only. Photos are attachments (1 to 10). parent and embed are refused.
• drop: a timed first-come-first-served release of 1 to 20 of the seller's listings (starts_at, ends_at?, quantities).
• shop: the storefront: name, bio, location, policies, transaction_service (the https endpoint for checkout and orders). One current post per seller.
• Reviews are social rating posts. A buyer rates the listing (parent the listing); a seller rates the buyer (parent the buyer's profile). ext.marketplace carries role, listing, order_ref, a purchase attestation (compact JWS signed by the transaction service) and sub-scores on the same 1 to 10 scale. A response to a review is a reply to the rating.

Music: listen, listening, session

Every music post embeds the music it is about and has no parent. Times are microseconds, durations milliseconds. The path decides who sees it.

The optional name on listening and session is merged on both music branches (commit dd8a24c): 1 to 100 code points; when absent, readers show a generic name ("Alice's listening session", "Alice is listening"). Playlists are social collections; ext.music adds per-item source and added_at, and per-playlist source_order and original. Audio files stay app data in /priv/pubky.music/files/ on purpose. A rating of a track is a social rating with parent the music URL.

Events and calendar apps

An events or calendar app writes only social kinds: event, rsvp, availability, calendars as collections, rating on events, venues as place URIs, labels as tags, saved events as bookmarks. A personal calendar and its private events live under /priv/social/v1/. Busy details stay private; the app derives the public, coarse availability from them. If an app later needs more (prices on a schedule, booking rules), it adds ext.events on the availability or its own kind in the events namespace.

Manifests and client declarations Proposal

The sub-spec proposal (27 October) adds two small JSON files. Owner decisions on it are already taken; nothing is built yet.

• subspec.json in each crate says how a kind becomes a Pinakes card: schema.org type, name, image, place, time, facts, which references count. Pinakes bundles a pinned copy and reviews it like code; it never fetches manifests live. Planned cards: route → Trip; listing → Product; drop → SaleEvent; shop → OnlineStore; session → BroadcastEvent; a public listen gets no card and counts on the track; listening gets a short-lived card.
• Client declarations: each client publishes pubky://<client key>/pub/clients/v1/client.json with the namespaces and kinds it handles and an optional open URL template. Pinakes collects them from a reviewed key list and shows "Clients that support this" on each card. This replaces today's hard-coded open_in. clients becomes a reserved namespace.
• A post in a namespace without a manifest still gets a general card from standard fields (name or title, description, image).

{ "declaration": 1, "name": "Pubky Maps", "homepage": "https://maps.pubky.app",
  "supports": [
    { "namespace": "maps", "kind": "route", "open": "https://maps.pubky.app/route/{owner}/{id}" },
    { "namespace": "social", "kind": "rating" } ] }

5. Storage and privacy

There is no visibility flag on any object. Who can read something is decided by where it is stored.

Locks for events

Nexus shows public RSVP counts; it never checks tickets or invites. Refunds and transfers are not possible (no refund rail in Paykit).

6. Who indexes what

Nexus: what exists

Pinakes: what exists

Pinakes ranks, Nexus hydrates

One detail for event screens: since the owner's decision of 26 October, Pinakes does not index social events. "Events near me" over both Pubky and external events is therefore two queries today: Nexus /v0/stream/events (time, tags, collection, author, following; no location filter) and Pinakes search for external events. Nexus stores LOCATED_AT edges to venue Resources, so a client can ask Pinakes for venues in an area and Nexus for their events, but there is no single "Pubky events in this bbox" query yet. See question 6.

7. Links between apps

All links between apps are plain URI references. Whether a link is possible depends on which positions a kind allows. The solid lines below are allowed by the current specs. The dashed red lines are in the ecosystem plan but have no position in the specs today.

What works today, per the specs

• Ratings on places, tracks, listings, events, links: a rating with that parent. Nexus counts it on the post or on the Resource of the URI (fork #23).
• An event at a place: locations[].uri. Nexus writes a LOCATED_AT edge to the place's Resource.
• A song at an event: a note or reply with parent the event and embed the song; or both in a collection.
• A music session, a listen: embed the track.
• A bookable listing: an availability with for the listing.
• A calendar mixing Pubky and external events, a list of places and routes, a playlist: a collection.
• A route along a trail: embed the OSM relation; waypoints are places.
• Grouping across services: Pinakes also_on shows the same song on Spotify and Apple Music, or one event on two platforms.

8. What pubky.app can build now and later

"Backend" below means the version a dev or staging pubky.app can run against: Nexus from the fork's fork/v1, Pinakes main. Production Nexus is upstream and has none of the fork work yet.

9. Open questions

Each question has the current recommendation. Where the owner already decided, it is not listed here.

10. Sources

Two design notes are older than the current decisions. The Events design still says availability is per app, ratings are 0 to 9, and Pinakes gets an event feed line. The Maps plan still has Nexus indexing route with a bbox stream. This page follows the later decisions: availability is social, ratings are 1 to 10, Nexus indexes social events itself, and route is a maps sub-spec kind that Nexus treats like any app post.