fep

FEP-302f: QuantPub — federated personal metrics for quantified-self sharing

Summary

QuantPub is a small, vendor-neutral extension to ActivityPub for sharing personal quantified-self data — workouts, sleep, heart-rate variability, steps, mood — between federated instances and home-built personal tools, without giving up mainstream-fediverse compatibility or the author’s control over what leaves their instance.

It has three parts:

  1. A tiny vocabulary (quant:Exercise, quant:Observation) that attaches typed scalar summaries and a bounded time window to an ordinary AS2 Note, so Mastodon-class servers render a readable status while implementing peers read machine-readable data.
  2. An out-of-band structured-payload pattern — a well-known discovery document plus two public HTTP endpoints — because typed vocabulary extensions are, in practice, dropped by mainstream fediverse software. This channel is the interoperable core of the proposal.
  3. Privacy principles as normative requirements: scalar summaries never imply series access, series and geography are separate explicit opt-ins, unshared data is indistinguishable from nonexistent data, and revocation is immediate.

A home-built tool interoperates by implementing the discovery document and the two endpoint contracts — no ActivityPub actor required — and can grow into full federation later.

Motivation

Sharing a workout is a social act. On Strava, Garmin Connect and their peers a run shows up in followers’ feeds as a card: a map, a few headline stats, a heart-rate chart, room for kudos and comments. That is what people want from fitness sharing, and it is why those platforms hold the data.

The fediverse already has the social half: identity, follows, delivery, replies and likes. It lacks the card. A workout posted to Mastodon today is a sentence and a screenshot; a federated fitness server posting to another federated fitness server has no agreed shape for the stats behind it, so each pair of implementations negotiates its own.

Two things are missing:

QuantPub therefore treats the in-band vocabulary as progressive enhancement and standardises the out-of-band fetch: deliver a boring, Mastodon-compatible Note (text plus rendered-image attachments) and serve the machine-readable payload at a discoverable endpoint on the author’s own instance. A peer that recognises the pattern fetches the structured data and renders the card; everyone else sees a perfectly good status.

The same shape covers sleep, HRV, steps and mood, so the proposal is written for quantified-self data in general, with exercise as the leading case. And because the payload side needs no ActivityPub stack, the many hand-rolled single-user QS systems — a database, some sync scripts, a dashboard — can join with a handful of routes.

Requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.

Specification

1. Conformance levels and conventions

All names are lowerCamelCase, on the JSON-LD layer and the plain-JSON payload layer alike, so a post’s startTime and its payload’s startTime are the same name. AS2 properties are reused where they exist (startTime, endTime, name). Timestamps are ISO 8601 with timezone. The quant: namespace is https://w3id.org/quantpub# (final IRI to be settled with the FEP number).

quant:metrics and quant:series are JSON literals: the published @context defines both with "@type": "@json" (JSON-LD 1.1), so processors preserve the nested objects verbatim instead of expanding, and losing, unmapped keys. Consumers MUST treat these values as plain JSON; a series entry’s mediaType/href are data, not an AS2 Link.

2. quant:Exercise — a shared workout

A shared exercise is an AS2 object, RECOMMENDED to be dual-typed ["Note", "quant:Exercise"] — Note first, so plain clients render name/content as a status. The extra type is descriptive, not load-bearing: detection (§7) keys on the object id or quant:structuredUrl, never on the type, so a publisher MAY emit a single-typed Note where deployed consumers mishandle array-valued type (§10). Consumers MUST tolerate both forms.

Property Type Notes
startTime (AS2) ISO 8601 REQUIRED. Start of the bounded activity window
endTime (AS2) ISO 8601 RECOMMENDED. End of the window
quant:activityType string e.g. running, cycling, meditation
quant:metrics array of metric objects The scalar summaries the author chose to share (§2.1)
quant:series array of series links Links into §6 — only for series opted in on a publicly-visible post
quant:structuredUrl URL OPTIONAL explicit link to the object’s §5 payload (§7)

There is no duration property: duration is derivable from the window, and when shared as a stat it is the duration metric key (seconds). AS2 duration MAY be set additionally for plain-AS2 consumers.

published is the share time and orders the timeline; the workout time lives in startTime. A workout shared a week later MUST NOT be back-dated in followers’ timelines.

2.1 Metric objects

{ "key": "heartRateAvg", "value": 152, "unit": "bpm" }

A publisher MUST emit only the metrics the author explicitly chose to share. Absence of a key means “not shared”, never “zero”.

3. quant:Observation — a measured metric over a window

Exercise is one case of the general shape: something was measured over a bounded window. A quant:Observation covers sleep, HRV, steps, mood, weight, blood glucose — anything with a window and values. It is dual-typed ["Note", "quant:Observation"] (RECOMMENDED, same single-type allowance as §2) and carries the §2 properties with quant:activityType replaced by:

Property Type Notes
quant:observationOf string The domain observed, e.g. sleep, daily, mood

quant:metrics carries the observed values in the §2.1 shape (sleepDuration, sleepScore, hrvAvg, steps, mood, …). Implementations MAY treat quant:Exercise as a specialisation of quant:Observation.

4. Discovery: /.well-known/quantpub

An implementation MUST serve, at its web base URL:

GET /.well-known/quantpub
{
  "product": "my-qs-tool",
  "version": "1.0.0",
  "quantpub": "0.2",
  "apiBase": "https://qs.example.net/api"
}

One cacheable request (responses SHOULD carry e.g. max-age=3600) tells a peer whether a host speaks QuantPub and where its API is. NodeInfo is deliberately not reused: this document gates a fetch decision made on every ingest, so it must be tiny and unambiguous.

5. Structured post endpoint

For every shared post the origin MUST serve a machine-readable payload at:

GET {apiBase}/public/{username}/feed/{postId}

returning a JSON object discriminated on kind. An exercise or observation share is kind: "activity":

{
  "kind": "activity",
  "activityType": "running",
  "name": "Morning run",
  "startTime": "2026-08-15T06:30:00+02:00",
  "endTime": "2026-08-15T07:09:00+02:00",
  "metrics": [
    { "key": "duration", "value": 2340, "unit": "seconds" },
    { "key": "distance", "value": 8.2, "unit": "km" },
    { "key": "heartRateAvg", "value": 152, "unit": "bpm" },
    { "key": "hrZoneMinutes", "value": { "z2": 22, "z3": 10 } }
  ],
  "series": [
    {
      "metric": "heartRate",
      "unit": "bpm",
      "bucket": "5s",
      "samples": [
        {
          "start": "2026-08-15T06:30:00+02:00",
          "end": "2026-08-15T06:30:05+02:00",
          "avg": 121,
          "min": 118,
          "max": 124,
          "count": 5
        }
      ]
    }
  ],
  "route": [{ "lat": 59.3251, "lon": 18.071, "t": "2026-08-15T06:30:00+02:00" }]
}

Authorization follows post visibility: a public or unlisted post resolves unconditionally; a followers-only post resolves only with a valid capability token or signed follower fetch (§9); anything else, a nonexistent post included, returns 404 (§8.3).

6. Series endpoint

High-resolution series MUST NOT be embedded in federated objects. They are served from one public, read-only endpoint:

GET {apiBase}/public/{username}/series?metric={key}&start={iso}&end={iso}&bucket={size}

bucket is an integer followed by s, m, h or d (5s, 60s, 1d).

A request resolves only when all of the following hold; this data-driven check is the entire authorization boundary:

  1. some shared post opted that exact metric in as a series (a shared scalar summary alone MUST NOT satisfy this);
  2. that post is publicly visible;
  3. the underlying activity still exists and has a bounded window;
  4. the activity’s window covers the requested [start, end].

Anything else returns 404 (§8.3). The server SHOULD additionally clamp the range to the shared window as defence in depth. The bucket size MUST be floored server-side (RECOMMENDED minimum: 5 seconds), and only aggregated buckets are returned (§8.5).

6.1 Bucketed samples

{
  "metric": "heartRate",
  "unit": "bpm",
  "bucket": "5s",
  "samples": [
    {
      "start": "2026-08-15T06:30:00+02:00",
      "end": "2026-08-15T06:30:05+02:00",
      "avg": 121,
      "min": 118,
      "max": 124,
      "count": 5
    }
  ]
}

Each sample carries start, end, avg, min, max, count, and sum for cumulative metrics such as steps. One shape serves heart-rate traces, nightly HRV, daily step counts and mood check-ins alike; only the metric key and bucket size differ.

7. Detection and enrichment (Level 3)

A consumer needs a defined path from a received object to its §5 payload. The id convention is the baseline, since typed AS2 frameworks on the consuming side may drop unknown in-band properties before application code sees them:

On ingesting a Create/Update for a Note, a receiving peer:

  1. checks for a same-host quant:structuredUrl or an id matching the convention (a Mastodon status id never does, avoiding needless requests);
  2. resolves the payload URL — directly from quant:structuredUrl, or from the id convention plus {apiBase} from the cached discovery document. In the quant:structuredUrl case a consumer MAY fetch the discovery document as a capability check but MUST NOT require it;
  3. fetches the §5 payload and stores it alongside the sanitised note for native rendering.

Enrichment MUST be best-effort and additive: any failure (non-QuantPub host, 404, malformed payload, timeout) leaves the plain note intact. Fetches MUST be SSRF-guarded (see Security considerations).

8. Privacy model (normative)

  1. Scalars never imply series. Sharing heartRateAvg MUST NOT expose the heart-rate series. A per-sample trace is far more revealing than an average.
  2. Series are a separate, explicit opt-in, per post, per metric. The default for any share MUST be: no series.
  3. Unshared equals nonexistent. Requests for unshared data MUST return 404, never 403, so the response cannot reveal that unshared data exists.
  4. Revocation is immediate. Deleting a post, narrowing its visibility, or withdrawing a series opt-in MUST immediately stop the corresponding endpoints from resolving. All §5 and §6 responses — public and unlisted included — MUST be served Cache-Control: no-store, so no intermediary extends access beyond revocation. Only the discovery document (§4) is cacheable.
  5. Bounded resolution. The bucket floor (§6) is a privacy floor, not only a payload bound: implementations MUST NOT serve raw per-measurement series timestamps on public endpoints. (A route’s per-fix t is not a series timestamp; it is governed by item 6.)
  6. Geography is its own explicit opt-in. A route MUST NOT be exposed by any scalar or series share; the default MUST be: no route. Publishers SHOULD bound route resolution (RECOMMENDED: at most 500 points, or an equivalent minimum spacing) and SHOULD apply privacy geo-masking (home-zone trimming) before export, not only in rendering.

9. Capability tokens for follower-scoped payloads

Mainstream fediverse media and data fetches are unsigned: Mastodon’s “authorized fetch” signs ActivityPub object requests, not media downloads, and a Level 1 publisher has no actor keys at all. QuantPub therefore uses capability URLs as the baseline for followers-only posts.

Signed fetches as an additional grant. Purpose-built peers can sign their fetches (FitPub authorizes followers-only details this way). A Level 2+ publisher MAY additionally resolve a followers-only §5 payload for a request bearing a valid HTTP Signature from an accepted follower or its instance actor, and a Level 3 consumer SHOULD sign its enrichment fetches when it has an actor key. Signatures are strictly additive: they MUST NOT replace capability tokens, the only channel that works without ActivityPub keys on either side, and a request satisfying neither channel is still 404.

10. Coexistence and incremental adoption

Every part of this proposal is additive, so an implementation with an established federation format can adopt it without breaking federation with its own older versions:

Implementing this in a weekend

A home-built QS tool becomes a Level 1 publisher with two-and-a-half routes and no ActivityPub stack:

  1. Serve /.well-known/quantpub (static JSON, §4).
  2. Serve GET /public/{you}/feed/{postId} for each thing you choose to publish (§5) — near-static JSON for a single-user tool.
  3. Optionally serve the series endpoint (§6) for the series you explicitly share, with the four-condition check and 404 fallback.

Any Level 3 peer that learns one of your post URLs can now render your data natively. Adding a minimal ActivityPub actor later (WebFinger, inbox/outbox, Create{Note} delivery — Level 2) makes you followable from Mastodon and every QuantPub peer, with the structured channel already in place.

Examples

A federated exercise share (Create)

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    {
      "quant": "https://w3id.org/quantpub#",
      "quant:metrics": { "@type": "@json" },
      "quant:series": { "@type": "@json" }
    }
  ],
  "id": "https://qs.example.net/users/freja/feed/01J5X0#create",
  "type": "Create",
  "actor": "https://qs.example.net/users/freja",
  "published": "2026-08-15T08:02:11+02:00",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://qs.example.net/users/freja/followers"],
  "object": {
    "id": "https://qs.example.net/users/freja/feed/01J5X0",
    "type": ["Note", "quant:Exercise"],
    "attributedTo": "https://qs.example.net/users/freja",
    "name": "Morning run",
    "content": "<p><strong>Morning run</strong></p><p>Duration 39m · Distance 8.2 km · Heart rate avg 152 bpm · HR zones z2 22, z3 10</p>",
    "published": "2026-08-15T08:02:11+02:00",
    "startTime": "2026-08-15T06:30:00+02:00",
    "endTime": "2026-08-15T07:09:00+02:00",
    "quant:activityType": "running",
    "quant:structuredUrl": "https://qs.example.net/api/public/freja/feed/01J5X0",
    "quant:metrics": [
      { "key": "duration", "value": 2340, "unit": "seconds" },
      { "key": "distance", "value": 8.2, "unit": "km" },
      { "key": "heartRateAvg", "value": 152, "unit": "bpm" },
      { "key": "hrZoneMinutes", "value": { "z2": 22, "z3": 10 } }
    ],
    "quant:series": [
      {
        "metric": "heartRate",
        "mediaType": "application/json",
        "href": "https://qs.example.net/api/public/freja/series?metric=heartRate&start=2026-08-15T06%3A30%3A00%2B02%3A00&end=2026-08-15T07%3A09%3A00%2B02%3A00&bucket=5s"
      }
    ]
  }
}

Mastodon renders content and any attached chart image; a QuantPub peer recognises the id shape (or the same-host quant:structuredUrl), discovers the origin and fetches the §5 payload. The inline "@type": "@json" definitions mirror the published @context; once the final context IRI is settled, referencing it alone suffices.

A sleep observation (object only)

{
  "type": ["Note", "quant:Observation"],
  "name": "Last night's sleep",
  "content": "<p><strong>Last night's sleep</strong></p><p>Sleep 7h 40m · HRV avg 64 ms · Score 86</p>",
  "quant:observationOf": "sleep",
  "startTime": "2026-08-14T23:05:00+02:00",
  "endTime": "2026-08-15T06:45:00+02:00",
  "quant:metrics": [
    { "key": "sleepDuration", "value": 27600, "unit": "seconds" },
    { "key": "hrvAvg", "value": 64, "unit": "ms" },
    { "key": "sleepScore", "value": 86 }
  ]
}

Series requests and the 404 boundary

GET /api/public/freja/series?metric=heartRate&start=2026-08-15T06:30:00%2B02:00&end=2026-08-15T07:09:00%2B02:00&bucket=60s
→ 200, bucketed samples (shared as a series on a public post, window covered)

GET /api/public/freja/series?metric=heartRate&start=2026-08-14T00:00:00Z&end=2026-08-16T00:00:00Z&bucket=60s
→ 404 (window not covered by any shared activity — the share can't be widened)

GET /api/public/freja/series?metric=stress&start=...&end=...&bucket=60s
→ 404 (stress scalar was shared, but its series was not opted in)

Security considerations

Prior art

Implementations

VertMatch serves the 0.1 snake_case field names at the time of writing; Aurboda serves 0.2 and accepts both on ingest.

References

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication.

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.