This proposal defines a full-text search syntax for ActivityPub client support.
The syntax supports:
facet:value)AND, OR, NOT)AND between adjacent expressions/.../)[a TO b], {a TO b}, [a TO b})The term query string means the value of the q query parameter in an HTTP request
against a search endpoint.
The term faceted expression means <facet>:expr, where expr may be a term,
phrase, regex, range, or parenthesized subexpression and the facet is typically a JSON property path.
The term unfaceted expression means a term, phrase, regex, or group that does not have a facet prefix.
The (simplified) grammar proposed by this FEP is:
query := or_expr
or_expr := and_expr ("OR" and_expr)*
and_expr := unary (("AND" unary) | (implicit_and unary))*
unary := "NOT" unary | primary
primary := term | phrase | regex | range | field_expr | "(" query ")"
field_expr := WORD ":" (primary | "(" query ")")
range := ("[" | "{") bound TO bound ("]" | "}")
bound := WORD | phrase
phrase := '"' <any-char-except-quote>* '"'
regex := "/" <regex-body> "/"
term := WORD
An AND is implicit when two primaries are adjacent. The “regex-body” SHOULD conform to RFC9485 (Interoperable Regular Expression Format).
A full ABNF grammar is available. This can be used with parser generators like ANTLR.
AND, OR, NOT, and TO are recognized as operators only in uppercase.WORD excludes whitespace and these delimiters: ()[]{}":/.The parser evaluates operators in this order:
NOTAND (explicit and implicit)ORAND and OR are left-associative.
A fielded expression has this form:
<facet>:value
<facet>:"some phrase"
<facet>:/xy.*/
<facet>:[10 TO 20]
<facet>:(cats OR dogs)
<facet>:(...) applies the nested expression to the facet value.
Ranges support inclusive and exclusive delimiters independently:
[a TO b] inclusive lower and upper bounds{a TO b} exclusive lower and upper bounds[a TO b} inclusive lower, exclusive upper{a TO b] exclusive lower, inclusive upperUnbounded bounds may use * where supported by the evaluator implementation
(e.g., rank:[4 TO *]).
The search endpoint is specified using the search property of the ActivityPub actor endpoints object. For example:
{
"@context": [
"https://w3id.org/fep/f011"
"https://www.w3.org/ns/activitystreams"
],
...
"endpoints": {
"search": "https://server.example/search"
}
}
This syntax is used as the q parameter on the search endpoint.
GET https://server.example/search?q=<query>
Responses MUST be an ActivityPub Collection or OrderedCollection. Paging is optional. If an OrderedCollection is returned, the results SHOULD be considered ranked although the ranking criteria will not be known by the client ( possibilities are relevance/BM25, recency, etc.).
Request: cats
GET /search?q=cats HTTP/1.1
Host: social.example
Accept: application/activity+json
Request: tag:fediverse language:en "ActivityPub client search"
GET /search?q=tag%3Afediverse%20language%3Aen%20%22ActivityPub%20client%20search%22 HTTP/1.1
Host: social.example
Accept: application/activity+json
Response:
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "OrderedCollection",
"id": "https://social.example/search?q=tag:fediverse language:en \"ActivityPub client search\"",
"totalItems": 1,
"orderedItems": [
{
"id": "https://social.example/notes/1",
"type": "Note"
}
]
}
Request:v(cats OR dogs) AND NOT testing
GET /search?q=%28cats%20OR%20dogs%29%20AND%20NOT%20testing HTTP/1.1
Host: social.example
Accept: application/activity+json
Request: type:Person preferredUsername:/alic.*/
GET /search?q=type%3APerson%20preferredUsername%3A%2Ffedi.%2A%2F
Host: social.example
Accept: application/activity+json
This could be useful for auto completion. Using a type:HashTag search term could similarly be used for hashtag autocompletion.
Request: rank:[2 TO 4]
GET /search?q=rank%3A%5B2%20TO%204%5D HTTP/1.1
Host: social.example
Accept: application/activity+json
Invalid syntax MUST result in an HTTP client error status. Examples include:
)<facet>:Implementations MAY include details in a problem response body.
AND is an operator, and is a term).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.