fep

FEP-c195: JSONPath Filtering for ActivityPub Collection Retrieval

Summary

This proposal defines a filter syntax for ActivityPub collection retrieval.

The syntax supports:

[!Note] This proposal is based on the standard RFC9535 JSONPath language. Some JSONPath libraries implement extended functionality beyond the scope of this FEP.

Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 RFC2119 and RFC8174 when, and only when, they appear in all capitals, as shown here.

Filter Syntax

Grammar

Filter expressions MUST use JSONPath syntax defined by RFC9535.

Implementations of this proposal MUST accept at least:

See also: examples.

Evaluation Model

A viewable object is defined as an ActivityPub entity:

A server applying this proposal:

  1. Retrieves the viewable items from the addressed collection or the shared inbox.
  2. Applies the JSONPath filter expression to candidate activity/object items
  3. Returns matched item values in collection order for OrderedCollection or subtypes.

The filter is applied to collection items, not to the outer collection object.

HTTP Usage

This syntax is used for the filter parameter on collection retrieval endpoints. The filter is an item-level filter. Depending on the collection type it will be applied to orderedItems or items.

The item filter has two variations:

Case Description
No leading [ The expression will be wrapped in [ and ]
Leading [ Used as-is for the item filter expresssion

Example

@.type == 'Create'

becomes

$[?@type == 'Create']

(for an OrderedCollection, otherwise items will be used)

For filtering with additional features like projection, the query should start with “[”.

Example

[?@.object[*].attachment[?@.type == 'Video']].id

becomes

$[?@.object[*].attachment[?@.type == 'Video']].id]

Query Results

The results MUST be returned as ActivityPub collection objects (optionally paged). The result collection URI should be unique to that filtering operation rather than the original collection URI. For example, it could be original URI with the filter criteria query argument or a generated URI.

Example Filters

# Get all CRUD activities
@.type == 'Create' || @.type == 'Update' || @.type == 'Delete'

# Get all notification (non-CRUD) activities
!(@.type == 'Create' || @.type == 'Update' || @.type == 'Delete')

# Get all activities where Alice is the actor
@.actor=='https://example.social/users/alice'

# Get all items published before a specified date
@.published<='2026-02-20T10:30:00Z'

# Get the URI of the objects of all activities having a Video attachment
# This also peforms "projection" of the "id" property
[?@.object[*].attachment[?@.type == 'Video']].id

# Get all activities related to the given object URI (handles refs or embedded)
# Uses "id" projection
[?@.object == 'https://example.social/objects/note-1' || \
  @..object[?@ == 'https://example.social/objects/note-1']].id

# Get all activities who have an actor with 'bob' or 'Bob' in the name
search(@.actor, '[Bb]ob')

HTTP Example

GET /actor/inbox?filter=%24.orderedItems%5B%3F%28%40.type%20%3D%3D%20%27Create%27%20%7C%7C%20%40.type%20%3D%3D%20%27Update%27%20%7C%7C%20%40.type%20%3D%3D%20%27Delete%27%29%5D
Accept: application/activity+json

HTTP/1.1 200 OK
Content-Type: application/activity+json

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://example.com/actor/inbox?filter=%24.orderedItems%5B%3F%28%40.type%20%3D%3D%20%27Create%27%20%7C%7C%20%40.type%20%3D%3D%20%27Update%27%20%7C%7C%20%40.type%20%3D%3D%20%27Delete%27%29%5D
Accept: application/activity+json",
  "type": "OrderedCollectionPage",
  "totalItems": 3,
  "partOf": "https://example.com/actor/inbox",
  "next": "https://example.com/actor/inbox?offset=2&filter=%24.orderedItems%5B%3F%28%40.type%20%3D%3D%20%27Create%27%20%7C%7C%20%40.type%20%3D%3D%20%27Update%27%20%7C%7C%20%40.type%20%3D%3D%20%27Delete%27%29%5D",
  "orderedItems": [
    {
      ...
    }
}

Error Handling

Invalid filters MUST result in an HTTP client error status. Examples include:

Implementations MAY include parser or feature details in a problem response body.

FEP-34c1: Collection Filtering using TREE Hypermedia Vocabulary

This FEP is similar in intent but more oriented to RDF and Linked Data use cases.

FEP-6606: ActivityPub client to server collections addressing conventions

A simpler, but less powerful, filtering language based on a URL query parameter-based language defined in the FEP. The “fuzzy” matching is not well-defined (seems to be substring match) and it appears to not be able to handle conjunctions.

FEP-bad1: Object history collection

Filtering some collections (e.g., inbox and outbox) can provide similar historical results for a given object without the need for explicit history collections.

Implementations

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.