~mariusor/Fediverse-Enhancement-Proposal

fe2f26ebdbe76a139369353c152774c070862733 — Marius Orcsik 5 months ago fe83b75 master
Adding first elements of how to use the query params in collection filtering
1 files changed, 58 insertions(+), 9 deletions(-)

M feps/fep-6606.md
M feps/fep-6606.md => feps/fep-6606.md +58 -9
@@ 14,7 14,7 @@ the adressing of [ActivityPub] objects on servers that support [Client to
Server Interactions]. Its main purpose is to formalize a basic vocabulary for
defining subsets of IRIs [RFC-3987] for collections in a way that can be
generalized to both servers and clients. It builds upon the definition of query
parametrs [RFC-3986], by using a set of additional operators that can be
parametrs [RFC-3986], by introducing a set of additional operators that can be
applied to values.

## What we are trying to solve


@@ 28,8 28,8 @@ focusing on. -->

## Syntax 

The following syntax is extracted form RFC-3986 section 3.4, and it details the
URL query parameters as representing any string that conforms to the
The following syntax is extracted form RFC-3986 section 3.4, and it formalizes
the URL query parameters as representing any string that conforms to the
restrictions below between the first "?" character and the end of the URL or a
"#" character marking the start of the fragment part of the URL.



@@ 43,8 43,10 @@ restrictions below between the first "?" character and the end of the URL or a

    sub-delims    = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
    
There is no formal definition of the query string in terms of key and value pairs,
but for our use this is paramount, so we will take this extra step:
As we can see this is not formal definition of the query string as a group of
key and value pairs, but for our intended use, this is paramount.

So we will take this extra step ourselves and extend the definition to be:

    query         = *( query-pair [ qconcat ] )
    


@@ 79,9 81,15 @@ version with the following elements:
The operator symbols are "!" and "~" that correspond to negation respectively fuzzy 
matching of the query value.

Additionally we added a nil value symbol "-" that can be used 
Explicitly, when encountering a URL parameter value that has a "!" symbol in front
of it we mean it as "different than". Similarly when encountering a value prepended 
with the "~" symbol, we mean it as "similar with" in a textual manner. 

Additionally we added a nil value symbol "-" that can be used for operations where
the value to compare against is absent.

Examples:
Please look at the following examples to see how these rules apply and compound with
one another:

    ?element=value 
    // resources matching exactly "value"


@@ 107,18 115,59 @@ Examples:
    ?element=!- 
    // resources matching all non empty element values
    
## Applicability for ActivityPub IRIs

We will define how we are going to apply this new defined schema for URL query
paramters to ActivityPub collections.
    
We will assume an ActivityPub collection base IRI follows the following pattern:

    https://example.com/ActorName/outbox
    
Where `example.com` is the host of the ActivityPub service, `ActorName` is an
identifier for an actor on this service, and `outbox` identifies the collection
we want to load.

The response to a GET request to this IRI could return something like:

    {
        "@context": "https://www.w3.org/ns/activitystreams",
        "id": "https://example.com/ActorName/outbox",
        "type": "OrderedCollection",
        "updated": "2021-04-09T08:16:05Z",
        "first": "https://example.com/ActorName/outbox?maxItems=10",
        "totalItems": 12,
        "orderedItems": [ /* skipping items for brevity */ ]
    }
    
The filtering for the elements in the collection will be done by using URL
query parameters with the key names corresponding to the different property
names of a valid ActivityPub object.

Example:

    https://example.com/ActorName/outbox?type=Delete
    
    // will return only activities with the type `Delete` that exist in the
    // ActorName's `outbox` collection
    
    https://example.com/ActorName/outbox?summary=~test%20example
    
    // will return only activities containing a summary property that contains
    // the "test example" text.

## Starting assumptions

### Objects collections:

An objects collection represents any collection that contains only ActivityPub
Objects. The ActivitypPub specification names the following ones as such:
Objects. The ActivityPub specification names the following ones as such:
`following`, `followers`, `liked`.

### Activities collections:

An activities collection represents any collection that contains only
ActivityPub Activities. The ActivitypPub spec names the following ones as such:
ActivityPub Activities. The ActivityPub spec names the following ones as such:
`outbox`, `inbox`, `likes`, `shares`, `replies`.

## Addressing grammar