mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
refactor: ♻️ Add URI Collections and change all appropriate Collections to use them
This commit is contained in:
Jesse Wierzbinski
parent
3babd7a5a3
commit
b59b6b8ebb
|
|
@ -22,6 +22,8 @@ This page lists changes since Working Draft 3. {{ className: 'lead' }}
|
|||
- In most cases, the two are interchangeable, but RFC 3339 is more strict. Most implementations should not need to change anything.
|
||||
- Add optional `$schema` field to [Entities](/entities).
|
||||
- Added [Interaction Controls Extensions](/extensions/interaction-controls)
|
||||
- Added [URI Collections](/structures/collection#uri-collection)
|
||||
- Changed all Collections that can contain remote entities to use URI Collections (eg. [User](/entities/user) `collections.followers`).
|
||||
|
||||
## Since WD 3
|
||||
|
||||
|
|
|
|||
|
|
@ -25,10 +25,10 @@ Refer to [Note](/entities/note#entity-definition)'s `group` property for how not
|
|||
Text only (`text/plain`, `text/html`, etc).
|
||||
</Property>
|
||||
<Property name="members" type="URI" required={true} typeLink="/types#uri">
|
||||
URI of the group's members list. [Collection](/structures/collection) of [Users](/entities/user).
|
||||
URI of the group's members list. [URI Collection](/structures/collection#uri-collection) of [Users](/entities/user).
|
||||
</Property>
|
||||
<Property name="notes" type="URI" required={false} typeLink="/types#uri">
|
||||
URI of the group's associated notes. [Collection](/structures/collection) of [Notes](/entities/note).
|
||||
URI of the group's associated notes. [URI Collection](/structures/collection#uri-collection) of [Notes](/entities/note).
|
||||
</Property>
|
||||
</Properties>
|
||||
</Col>
|
||||
|
|
|
|||
|
|
@ -114,19 +114,19 @@ Instance **must** be the host of the instance the user is on (hostname with opti
|
|||
}
|
||||
```
|
||||
|
||||
All URIs must resolve to a [Collection](/structures/collection) of the appropriate entities. Extensions may add additional collections.
|
||||
All URIs must resolve to either a [Collection](/structures/collection) or a [URI Collection](/structures/collection#uri-collection) of the appropriate entities. Extensions may add additional collections.
|
||||
|
||||
### Outbox
|
||||
The user's federation outbox. Refer to the [federation documentation](/federation).
|
||||
The user's federation outbox. Refer to the [federation documentation](/federation). [Collection](/structures/collection) of [Note](/entities/note) entities.
|
||||
|
||||
### Followers
|
||||
User's followers. [Collection](/structures/collection) of [User](/entities/user) entities.
|
||||
User's followers. [URI Collection](/structures/collection#uri-collection) of [User](/entities/user) entities.
|
||||
|
||||
### Following
|
||||
Users that the user follows. [Collection](/structures/collection) of [User](/entities/user) entities.
|
||||
Users that the user follows. [URI Collection](/structures/collection#uri-collection) of [User](/entities/user) entities.
|
||||
|
||||
### Featured
|
||||
[Notes](/entities/note) that the user wants to feature (also known as "pin") on their profile. [Collection](/structures/collection) of [Note](/entities/note) entities.
|
||||
[Notes](/entities/note) that the user wants to feature (also known as "pin") on their profile. [Collection](/structures/collection) of [Note](/entities/note) entities. Only notes authored by the user can be featured.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@ Extensions **may** choose to register their own interaction types (such as `pub.
|
|||
|
||||
Implementations that find a user attempting to create an interaction they are not allowed to **MUST** return a `403 Forbidden` HTTP status code when processing the Note during federation. The Note **must** also be discarded.
|
||||
|
||||
It is important for implementations to backfill any related [Collections](/structures/collection) (e.g. user followers) in order to not incorrectly reject Notes based off of outdated data.
|
||||
It is important for implementations to backfill any related [Collections](/structures/collection)/[URI Collections](/structures/collection#uri-collection) (e.g. user followers) in order to not incorrectly reject Notes based off of outdated data.
|
||||
|
||||
<Note>
|
||||
To avoid server load from constant Collection refreshing, implementations **could** only refetch associated Collections when forbidden interactions are detected, then recalculate permissions again.
|
||||
|
|
|
|||
|
|
@ -92,8 +92,8 @@ To undo a like or dislike, a [Delete](/entities/delete) entity should be used. T
|
|||
|
||||
The Likes extension adds the following collections to the [User](/entities/user) entity:
|
||||
|
||||
- `likes`: A [Collection](/structures/collection) of all the notes the user has liked.
|
||||
- `dislikes`: A [Collection](/structures/collection) of all the notes the user has disliked.
|
||||
- `likes`: A [URI Collection](/structures/collection#uri-collection) of all the notes the user has liked.
|
||||
- `dislikes`: A [URI Collection](/structures/collection#uri-collection) of all the notes the user has disliked.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ The Reactions Extension extends the [Note](/entities/note) entity with the follo
|
|||
<Col>
|
||||
<Properties>
|
||||
<Property name="reactions" type="array" required>
|
||||
URI to a [Collection](/structures/collection) of the [Reactions](#entity-definition) attached to the note.
|
||||
URI to a [URI Collection](/structures/collection#uri-collection) of the [Reactions](#entity-definition) attached to the note.
|
||||
</Property>
|
||||
</Properties>
|
||||
</Col>
|
||||
|
|
|
|||
|
|
@ -39,6 +39,6 @@ Shared inboxes are defined in the [Instance Metadata](/entities/instance-metadat
|
|||
|
||||
## Outboxes
|
||||
|
||||
In addition to inboxes, every user has an outbox (e.g., `/users/3/outbox`). The outbox is simply a collection of all the messages that a user has sent. When a user sends a message to another user, a copy of that message is accessible in the sender's outbox.
|
||||
In addition to inboxes, every user has an outbox (e.g., `/users/3/outbox`). The outbox is simply a [Collection](/structures/collection) of all the messages that a user has sent. When a user sends a message to another user, a copy of that message is accessible in the sender's outbox.
|
||||
|
||||
Outboxes are very useful for "backfilling" data when a new instance joins the network. By resolving the outboxes of all new users it encounters, a new instance can quickly catch up on all old messages.
|
||||
|
|
@ -77,3 +77,60 @@ Pages should be limited to a reasonable number of entities, such as 20 or 80.
|
|||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
## URI Collection
|
||||
|
||||
URI Collections are identical to regular collections, but they contain only URIs instead of full entities. They are useful for cases when remote entities need to be included in a collection, as those are typically not stored in implementation databases. {{ className: 'lead' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
<Properties>
|
||||
<Property name="author" type="URI | null" required={true} typeLink="/types#uri">
|
||||
Author of the collection. Usually the user who owns the collection. [Can be set to `null` to represent the instance](/entities/instance-metadata#the-null-author).
|
||||
</Property>
|
||||
<Property name="first" type="URI" required={true} typeLink="/types#uri">
|
||||
URI to the first page of the collection. Query parameters are allowed.
|
||||
</Property>
|
||||
<Property name="last" type="URI" required={true} typeLink="/types#uri">
|
||||
URI to the last page of the collection. Query parameters are allowed.
|
||||
|
||||
If the collection only has one page, this should be the same as `first`.
|
||||
</Property>
|
||||
<Property name="total" type="number" required={true} numberType="u64">
|
||||
Total number of entities in the collection, across all pages.
|
||||
</Property>
|
||||
<Property name="next" type="URI" required={false} typeLink="/types#uri">
|
||||
URI to the next page of the collection. Query parameters are allowed.
|
||||
|
||||
If there is no next page, this should be `null`.
|
||||
</Property>
|
||||
<Property name="previous" type="URI" required={false} typeLink="/types#uri">
|
||||
URI to the previous page of the collection. Query parameters are allowed.
|
||||
|
||||
If there is no previous page, this should be `null`.
|
||||
</Property>
|
||||
<Property name="items" type="URI[]" required={true}>
|
||||
Collection contents. Must be an array of URIs.
|
||||
</Property>
|
||||
</Properties>
|
||||
</Col>
|
||||
|
||||
<Col sticky>
|
||||
|
||||
```jsonc {{ 'title': 'Example URI Collection' }}
|
||||
{
|
||||
"author": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771",
|
||||
"first": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=1",
|
||||
"last": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=3",
|
||||
"total": 46,
|
||||
"next": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=2",
|
||||
"previous": null,
|
||||
"items": [
|
||||
"https://versia.social/users/f8b0d4b4-d354-4798-bbc5-c2ba8acabfe3",
|
||||
"https://social.bob.com/u/2B27E62snga763"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
Loading…
Reference in a new issue