fep

FEP-34c1: Collection Filtering using TREE Hypermedia Vocabulary

Summary

This FEP proposes using the TREE Hypermedia Vocabulary for client-initiated filter requests on ActivityPub Collections (especially Inbox). Clients can send a filter as a JSON-LD object via HTTP POST to retrieve a filtered subset of the collection.

This enables use cases such as:

Context

The context document for this ActivityPub extension is at https://w3id.org/fep/34c1/context. Its contents are as follows:

{
  "@context": {
    "fep34c1": "https://w3id.org/fep/34c1#",
    "FilterRequest": "fep34c1:FilterRequest",
    "pageSize": {
      "@id": "fep34c1:pageSize",
      "@type": "http://www.w3.org/2001/XMLSchema#nonNegativeInteger"
    },
    "myFollowees": { "@id": "fep34c1:myFollowees", "@type": "@id" },
    "myAudience": { "@id": "fep34c1:myAudience", "@type": "@id" }
  }
}

Defined Terms

fep34c1:FilterRequest

   
URI https://w3id.org/fep/34c1#FilterRequest
Notes A container object for a filter query. It holds one or more tree:relation entries that define the filter criteria, and an optional fep34c1:pageSize to control pagination.
Domain (none)
Range (none)

fep34c1:pageSize

   
URI https://w3id.org/fep/34c1#pageSize
Notes The maximum number of items per page in the filtered response.
Domain fep34c1:FilterRequest
Range xsd:nonNegativeInteger
Functional Yes

fep34c1:myFollowees

   
URI https://w3id.org/fep/34c1#myFollowees
Notes Server-resolved placeholder. When used as tree:value, the server MUST replace it with the set of actor IRIs from the following collection of the authenticated (requesting) actor.

fep34c1:myAudience

   
URI https://w3id.org/fep/34c1#myAudience
Notes Server-resolved placeholder. When used as tree:value, the server MUST resolve it to all collection IRIs in which the authenticated actor is known to be a member. This includes at minimum the followers collections of followed actors, and MAY include group memberships, lists, or other collections as the server discovers them.

Motivation

Problem

ActivityPub defines Collections (Inbox, Outbox, Followers, etc.) but no mechanism for clients to request filtered views. Clients must:

  1. Fetch all items with pagination
  2. Filter and sort locally
  3. Transfer unnecessarily large amounts of data

For a “Home Timeline” (activities from followees), this is particularly inefficient since the inbox also contains follow requests, likes, and other irrelevant activities.

Existing Approaches

Approach Problem
FEP-5bf0 WITHDRAWN (June 2025); focused on server-side views, not client queries
Hydra GET-oriented (URL templates), not for POST queries
SPARQL Too complex for simple filters, security risks
Proprietary Mastodon’s /api/v1/timelines/home is not standardized

Why TREE?

The TREE Hypermedia Vocabulary offers:


Specification

1. Filter Endpoint

Servers MAY provide a filter endpoint for collections:

POST /ap/actors/{username}/inbox/filter
Content-Type: application/ld+json

The endpoint MUST be announced in the Collection object via the tree:search property:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/tree"
  ],
  "type": "OrderedCollection",
  "id": "https://example.com/ap/actors/alice/inbox",
  "tree:search": {
    "@type": "fep34c1:FilterEndpoint",
    "tree:template": "https://example.com/ap/actors/alice/inbox/filter"
  }
}

2. Filter Request Format

A filter request is a JSON-LD object of type fep34c1:FilterRequest:

{
  "@context": {
    "tree": "https://w3id.org/tree#",
    "fep34c1": "https://w3id.org/fep/34c1#",
    "as": "https://www.w3.org/ns/activitystreams#",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  },
  "@type": "fep34c1:FilterRequest",
  "tree:relation": [
    {
      "@type": "tree:EqualToRelation",
      "tree:path": { "@id": "rdf:type" },
      "tree:value": [
        { "@id": "as:Create" },
        { "@id": "as:Update" },
        { "@id": "as:Delete" },
        { "@id": "as:Announce" }
      ]
    },
    {
      "@type": "tree:EqualToRelation",
      "tree:path": { "@id": "as:actor" },
      "tree:value": { "@id": "fep34c1:myFollowees" }
    },
    {
      "@type": "tree:EqualToRelation",
      "tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
      "tree:value": [
        { "@id": "https://www.w3.org/ns/activitystreams#Public" },
        { "@id": "fep34c1:myAudience" }
      ]
    }
  ],
  "fep34c1:pageSize": 20
}

3. Relation Types

3.1 MUST be Supported (Core)

Relation Semantics SPARQL Equivalent
tree:EqualToRelation Value is equal to ?x = ?value
tree:NotEqualToRelation Value is not equal to ?x != ?value
tree:GreaterThanRelation Value is greater than ?x > ?value
tree:LessThanRelation Value is less than ?x < ?value
tree:GreaterThanOrEqualToRelation Value is greater than or equal to ?x >= ?value
tree:LessThanOrEqualToRelation Value is less than or equal to ?x <= ?value
Relation Semantics SPARQL Equivalent
tree:PrefixRelation Value starts with STRSTARTS(?x, ?value)
tree:SubstringRelation Value contains CONTAINS(?x, ?value)
tree:SuffixRelation Value ends with STRENDS(?x, ?value)

4. Special Values

4.1 fep34c1:myFollowees - Dynamic Followee List

The value fep34c1:myFollowees is a server-resolved placeholder. When used as tree:value, the server MUST replace it with the set of actor IRIs from the following collection of the authenticated (requesting) actor.

This means a relation like:

{
  "@type": "tree:EqualToRelation",
  "tree:path": { "@id": "as:actor" },
  "tree:value": { "@id": "fep34c1:myFollowees" }
}

is equivalent to: “Return only activities where the as:actor property matches one of the actor IRIs in the requesting actor’s following collection.” In other words, only activities authored by actors that the requesting user follows will be included in the result.

4.2 fep34c1:myAudience - Dynamic Audience Collections

The value fep34c1:myAudience is a server-resolved placeholder. When used as tree:value, the server MUST resolve it to all collection IRIs in which the authenticated actor is known to be a member. This includes at minimum the followers collections of followed actors, and MAY include group memberships, lists, or other collections.

This is useful for audience filtering: Fediverse servers typically address followers-only posts with the actor’s followers collection IRI in as:to or as:cc.

Note: These are explicit FEP-34c1 placeholder properties rather than reused ActivityStreams terms. An earlier version of this spec used as:following and as:followers as placeholders, but this was semantically incorrect — as:followers denotes the collection itself, not its items (see discussion). Using dedicated FEP-34c1 properties makes the server-resolved semantics explicit and avoids overloading AS2 vocabulary. An alternative approach using SHACL Property Paths was considered but rejected due to the complexity of expressing pagination traversal in SHACL path expressions.

4.3 Multiple Values (OR Conjunction)

If tree:value is an array, the values are combined with OR:

{
  "tree:value": [
    { "@id": "as:Create" },
    { "@id": "as:Update" },
    { "@id": "as:Delete" },
    { "@id": "as:Announce" }
  ]
}

Semantics: rdf:type = as:Create OR rdf:type = as:Update OR rdf:type = as:Delete OR rdf:type = as:Announce

5. Multiple Paths (UNION)

If tree:path is an array, the filter matches if any of the specified paths contains a matching value. This is equivalent to a UNION in SPARQL.

{
  "@type": "tree:EqualToRelation",
  "tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
  "tree:value": { "@id": "https://example.com/ap/actors/alice" }
}

Semantics: “Match if the value appears in as:to OR in as:cc.”

This is particularly useful for audience filtering, since ActivityPub activities use both as:to and as:cc for addressing.

6. Combination of Relations (AND Conjunction)

Multiple tree:relation entries are combined with AND:

{
  "tree:relation": [
    { "@type": "tree:EqualToRelation", "tree:path": {"@id": "rdf:type"}, "tree:value": {"@id": "as:Create"} },
    { "@type": "tree:EqualToRelation", "tree:path": {"@id": "as:actor"}, "tree:value": {"@id": "fep34c1:myFollowees"} },
    { "@type": "tree:EqualToRelation", "tree:path": [{"@id": "as:to"}, {"@id": "as:cc"}], "tree:value": {"@id": "https://www.w3.org/ns/activitystreams#Public"} }
  ]
}

Semantics: rdf:type = as:Create AND as:actor IN myFollowees AND (as:to = as:Public OR as:cc = as:Public)

7. Response Format

The response is an OrderedCollectionPage with the filtered items. Pagination MUST use as:next and as:prev (standard ActivityStreams pagination). Servers MAY additionally include tree:relation entries to provide boundary values for TREE-aware clients.

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/tree",
    { "fep34c1": "https://w3id.org/fep/34c1#" }
  ],
  "@type": "OrderedCollectionPage",
  "partOf": "https://example.com/ap/actors/alice/inbox",
  "next": "https://example.com/ap/actors/alice/inbox/filter?cursor=abc123",
  "prev": "https://example.com/ap/actors/alice/inbox/filter?cursor=def456",
  "orderedItems": [
    { /* Activity 1 */ },
    { /* Activity 2 */ }
  ],
  "tree:relation": [
    {
      "@type": "tree:GreaterThanRelation",
      "tree:path": { "@id": "as:published" },
      "tree:value": "2026-01-28T10:00:00Z",
      "tree:node": "https://example.com/ap/actors/alice/inbox/filter?cursor=abc123"
    }
  ],
  "totalItems": 42
}

8. Pagination

Servers MUST provide as:next and as:prev links on OrderedCollectionPage responses for standard ActivityStreams pagination. This ensures compatibility with existing ActivityPub clients.

Servers MAY additionally include tree:relation entries to provide boundary values for TREE-aware clients. Each pagination relation uses three properties from the TREE vocabulary:

For example, a tree:GreaterThanRelation with tree:value of "2026-01-28T10:00:00Z" and a tree:node URL means: “Fetching tree:node will return items with as:published greater than 2026-01-28T10:00:00Z.”

Pagination directions:

9. Authentication

The filter endpoint MUST require the same authentication as the collection itself:


Security Considerations

Query Injection

Servers MUST validate and sanitize filter requests. In particular:

Recommended allowed tree:path values:

Rate Limiting

Filter requests are potentially more expensive than regular GET requests. Servers SHOULD implement rate limiting.

No Arbitrary SPARQL Queries

This FEP explicitly defines no SPARQL interface. The supported operations are limited to the defined tree:Relation types.


Examples

Example 1: Home Timeline

Shows content lifecycle activities from followed actors, visible to public or followers.

{
  "@context": {
    "tree": "https://w3id.org/tree#",
    "fep34c1": "https://w3id.org/fep/34c1#",
    "as": "https://www.w3.org/ns/activitystreams#",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  },
  "@type": "fep34c1:FilterRequest",
  "tree:relation": [
    {
      "@type": "tree:EqualToRelation",
      "tree:path": { "@id": "rdf:type" },
      "tree:value": [
        { "@id": "as:Create" },
        { "@id": "as:Update" },
        { "@id": "as:Delete" },
        { "@id": "as:Announce" }
      ]
    },
    {
      "@type": "tree:EqualToRelation",
      "tree:path": { "@id": "as:actor" },
      "tree:value": { "@id": "fep34c1:myFollowees" }
    },
    {
      "@type": "tree:EqualToRelation",
      "tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
      "tree:value": [
        { "@id": "https://www.w3.org/ns/activitystreams#Public" },
        { "@id": "fep34c1:myAudience" }
      ]
    }
  ],
  "fep34c1:pageSize": 20
}

Example 2: Mentions

Shows activities where the actor is directly addressed via as:to or as:cc (public mentions only, excluding DMs).

{
  "@context": {
    "tree": "https://w3id.org/tree#",
    "fep34c1": "https://w3id.org/fep/34c1#",
    "as": "https://www.w3.org/ns/activitystreams#",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  },
  "@type": "fep34c1:FilterRequest",
  "tree:relation": [
    {
      "@type": "tree:EqualToRelation",
      "tree:path": { "@id": "rdf:type" },
      "tree:value": [{ "@id": "as:Create" }]
    },
    {
      "@type": "tree:EqualToRelation",
      "tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
      "tree:value": { "@id": "https://example.com/ap/actors/alice" }
    },
    {
      "@type": "tree:EqualToRelation",
      "tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
      "tree:value": { "@id": "https://www.w3.org/ns/activitystreams#Public" }
    }
  ]
}

Example 3: Private Messages

Shows activities not addressed to as:Public (neither in as:to nor as:cc). This includes direct messages, followers-only posts, and group messages.

{
  "@context": {
    "tree": "https://w3id.org/tree#",
    "fep34c1": "https://w3id.org/fep/34c1#",
    "as": "https://www.w3.org/ns/activitystreams#",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  },
  "@type": "fep34c1:FilterRequest",
  "tree:relation": [
    {
      "@type": "tree:EqualToRelation",
      "tree:path": { "@id": "rdf:type" },
      "tree:value": [{ "@id": "as:Create" }]
    },
    {
      "@type": "tree:NotEqualToRelation",
      "tree:path": { "@id": "as:to" },
      "tree:value": { "@id": "https://www.w3.org/ns/activitystreams#Public" }
    },
    {
      "@type": "tree:NotEqualToRelation",
      "tree:path": { "@id": "as:cc" },
      "tree:value": { "@id": "https://www.w3.org/ns/activitystreams#Public" }
    }
  ]
}

Example 4: Activities Since Timestamp

{
  "@context": {
    "tree": "https://w3id.org/tree#",
    "fep34c1": "https://w3id.org/fep/34c1#",
    "as": "https://www.w3.org/ns/activitystreams#",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "@type": "fep34c1:FilterRequest",
  "tree:relation": [
    {
      "@type": "tree:GreaterThanRelation",
      "tree:path": { "@id": "as:published" },
      "tree:value": {
        "@value": "2026-01-27T00:00:00Z",
        "@type": "xsd:dateTime"
      }
    }
  ]
}

Example 5: Posts from a Specific Instance

{
  "@context": {
    "tree": "https://w3id.org/tree#",
    "fep34c1": "https://w3id.org/fep/34c1#",
    "as": "https://www.w3.org/ns/activitystreams#"
  },
  "@type": "fep34c1:FilterRequest",
  "tree:relation": [
    {
      "@type": "tree:PrefixRelation",
      "tree:path": { "@id": "as:actor" },
      "tree:value": "https://mastodon.social/"
    }
  ]
}

Implementation Notes

For Servers

  1. Special placeholder values (fep34c1:myFollowees, fep34c1:myAudience) MUST be resolved at query time before evaluating the filter (see Section 4).

  2. Allowed tree:path values SHOULD be restricted to a known set of ActivityStreams properties (see Security Considerations).

  3. For multi-path with EqualToRelation, the semantics are UNION (match if any path matches). For NotEqualToRelation, the semantics are ALL (none of the paths may match).

For Clients

  1. Clients SHOULD check if tree:search is present in the collection
  2. If not present: fall back to client-side filtering
  3. Filter requests SHOULD be cached (ETag/If-None-Match)
  4. Clients SHOULD expect 405 Method Not Allowed if the server does not support filters

Backwards Compatibility

This FEP is fully backwards compatible:


Implementations

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.