mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 14:28:20 +01:00
Finish v1.1 rewrite
This commit is contained in:
Jesse Wierzbinski
parent
fee03886e8
commit
4e0d104122
|
|
@ -73,7 +73,7 @@ The server **MUST** respond with a [Collection](../structures/collection) object
|
|||
"type": "Collection",
|
||||
"first": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19/reactions?page=1",
|
||||
"last": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19/reactions?page=1",
|
||||
"totalCount": 1,
|
||||
"total_count": 1,
|
||||
// "author": ... (for signatures)
|
||||
"items": [
|
||||
{
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ Notably, the Lysand protocol does not include a `Block` action. This is because
|
|||
|
||||
This approach helps prevent potential misuse of the protocol to determine if a user has been blocked by another, thereby addressing a significant privacy concern.
|
||||
|
||||
## Fielkds
|
||||
## Fields
|
||||
|
||||
### Author
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
# Announce
|
||||
|
||||
An `Announce` action is an action that represents a user announcing an object. It is used to share an object with the user's followers. This is similar to "retweeting" on Twitter.
|
||||
The `Announce` action signifies a user's intent to broadcast or share an object with their followers. This action is analogous to the "retweet" function on Twitter.
|
||||
|
||||
An `Announce` object **MUST** have an `object` field that contains the URI of the object that the user is announcing. The object **MUST** be a `Publication` object.
|
||||
Here's an example of an `Announce` action:
|
||||
|
||||
Example:
|
||||
```json5
|
||||
{
|
||||
"type": "Announce",
|
||||
|
|
@ -15,3 +14,31 @@ Example:
|
|||
"object": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19"
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
### Author
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
URI of the [Actor](./actors) who initiated the action.
|
||||
|
||||
### Object
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| object | String | Yes |
|
||||
|
||||
URI of the object being announced. Must be of type [Note](./note)
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Announce extends Entity {
|
||||
type: "Announce";
|
||||
author: string;
|
||||
object: string;
|
||||
}
|
||||
```
|
||||
|
|
@ -1,8 +1,6 @@
|
|||
# Dislike
|
||||
|
||||
A `Dislike` action is an action that represents a user disliking an object. It is one of the most common type of action.
|
||||
|
||||
A `Dislike` object **MUST** have an `object` field that contains the URI of the object that the user is disliking. The object **MUST** be a `Publication` object.
|
||||
The Dislike action signifies a user's negative sentiment towards an object. It is a frequently used action in the Lysand protocol.
|
||||
|
||||
Example:
|
||||
```json5
|
||||
|
|
@ -15,3 +13,31 @@ Example:
|
|||
"object": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19"
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
### Author
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
URI of the [Actor](./actors) who initiated the action.
|
||||
|
||||
### Object
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| object | String | Yes |
|
||||
|
||||
URI of the object being disliked. Must be of type [Note](./note)
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Dislike extends Entity {
|
||||
type: "Dislike";
|
||||
author: string;
|
||||
object: string;
|
||||
}
|
||||
```
|
||||
|
|
@ -1,8 +1,6 @@
|
|||
# Follow Accept
|
||||
|
||||
A `FollowAccept` action is an action that represents a user accepting a follow request from another user. By accepting a follow request, the user will be able to see the other user's posts in their feed.
|
||||
|
||||
A `FollowAccept` object **MUST** have an `follower` field that contains the URI of the user that the user is accepting a follow request from.
|
||||
A FollowAccept action symbolizes a user's consent to a follow request from another user. Upon acceptance, the user will start receiving the other user's posts in their feed.
|
||||
|
||||
Example:
|
||||
```json5
|
||||
|
|
@ -14,4 +12,32 @@ Example:
|
|||
"created_at": "2021-01-01T00:00:00.000Z",
|
||||
"follower": "https://example.com/users/02e1e3b2-cb1f-4e4a-b82e-98866bee5de7"
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
### Author
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
URI of the [Actor](./actors) who was being follow requested
|
||||
|
||||
### Follower
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| follower | String | Yes |
|
||||
|
||||
URI of the [User](./user) who tried to follow the author
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface FollowAccept extends Entity {
|
||||
type: "FollowAccept";
|
||||
author: string;
|
||||
follower: string;
|
||||
}
|
||||
```
|
||||
|
|
@ -1,8 +1,6 @@
|
|||
# Follow Reject
|
||||
|
||||
A `FollowReject` action is an action that represents a user rejecting a follow request from another user. By rejecting a follow request, the user will not be able to see the other user's posts in their feed.
|
||||
|
||||
A `FollowReject` object **MUST** have an `follower` field that contains the URI of the user that the user is rejecting a follow request from.
|
||||
A FollowReject action signifies a user's decision to decline a follow request from another user. This rejection prevents the requesting user's posts from appearing in the recipient's feed.
|
||||
|
||||
Example:
|
||||
```json5
|
||||
|
|
@ -15,3 +13,31 @@ Example:
|
|||
"follower": "https://example.com/users/02e1e3b2-cb1f-4e4a-b82e-98866bee5de7"
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
### Author
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
URI of the [Actor](./actors) who was being follow requested.
|
||||
|
||||
### Follower
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| follower | String | Yes |
|
||||
|
||||
URI of the [User](./user) who tried to follow the author.
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface FollowReject extends Entity {
|
||||
type: "FollowReject";
|
||||
author: string;
|
||||
follower: string;
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
# Follow
|
||||
|
||||
A `Follow` action is an action that represents a user following another user. By following another user, the user will be able to see the other user's posts in their feed.
|
||||
|
||||
A `Follow` object **MUST** have an `followee` field that contains the URI of the user that the user is following.
|
||||
A Follow action embodies a user's intent to follow another user. Upon successful execution of this action, the follower will start receiving the followed user's posts in their feed. This action facilitates the creation of a personalized content stream for each user.
|
||||
|
||||
Example:
|
||||
```json5
|
||||
|
|
@ -15,3 +13,31 @@ Example:
|
|||
"followee": "https://example.com/users/02e1e3b2-cb1f-4e4a-b82e-98866bee5de7"
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
### Author
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
URI of the [Actor](./actors) who initiated the action.
|
||||
|
||||
### Followee
|
||||
|
||||
| Name | Type | Required |
|
||||
| :------- | :----- | :------- |
|
||||
| followee | String | Yes |
|
||||
|
||||
URI of the [User](./user) who is being follow requested.
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Follow extends Entity {
|
||||
type: "Follow";
|
||||
author: string;
|
||||
followee: string;
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
# Like
|
||||
|
||||
A `Like` action is an action that represents a user liking/favouriting an object. It is one of the most common type of action.
|
||||
|
||||
A `Like` object **MUST** have an `object` field that contains the URI of the object that the user is liking. The object **MUST** be a `Publication` object.
|
||||
The Dislike action signifies a user's positive sentiment towards an object, akin to a favourite. It is a frequently used action in the Lysand protocol.
|
||||
|
||||
Example:
|
||||
```json5
|
||||
|
|
@ -14,4 +12,32 @@ Example:
|
|||
"created_at": "2021-01-01T00:00:00.000Z",
|
||||
"object": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19"
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
### Author
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
URI of the [Actor](./actors) who initiated the action.
|
||||
|
||||
### Object
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| object | String | Yes |
|
||||
|
||||
URI of the object being liked. Must be of type [Note](./note)
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Like extends Entity {
|
||||
type: "Like";
|
||||
author: string;
|
||||
object: string;
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,5 +1,13 @@
|
|||
# Note
|
||||
|
||||
A `Note` object is a simple object that represents a post or publication. It is the most common type of object.
|
||||
A `Note` object symbolizes a basic post or publication within the Lysand protocol. It is the most frequently used object type.
|
||||
|
||||
`Note` objects inherit from all Publication properties.
|
||||
`Note` objects extend all properties from the [Publication](./publications) object, thereby inheriting its characteristics and behaviors.
|
||||
|
||||
### Types
|
||||
|
||||
```typescript
|
||||
interface Note extends Publication {
|
||||
type: "Note";
|
||||
}
|
||||
```
|
||||
|
|
@ -1,16 +1,16 @@
|
|||
# Patch
|
||||
|
||||
A `Patch` object is an object that represents a change to a `Note`. It is used to update a `Note`, such as when a spelling mistake is made and needs to be corrected.
|
||||
A `Patch` object represents a modification to a [Note](./note). It is primarily used to update a [Note](./note), for instance, to correct a typographical error.
|
||||
|
||||
`Patch` objects are not meant to be displayed to the user, and are only meant to be used internally by the server.
|
||||
`Patch` objects are intended for internal server use and are not designed to be displayed to the user.
|
||||
|
||||
`Patch` objects **MUST** have a different `id` as the object that they are patching, and **MUST** have a `patched_at` field that contains the date and time that the object was patched. The `id` of the object that is being patched **MUST** be stored in the `patched_id` field.
|
||||
Each subsequent patch is applied to the original object, not the preceding patch. The server is responsible for presenting the most recent patch stored to the client.
|
||||
|
||||
Subsequent patches are applied to the original object, not to the previous patch. It is up to the server to display the most recent patch it has in storage to the client.
|
||||
> [!NOTE]
|
||||
> A `Patch` object should replace the object it is patching when displayed to the client. Therefore, if a Patch object lacks some fields from the previous object, these fields should be removed in the edit.
|
||||
|
||||
> **Note:**: A `Patch` object must replace the object that it is patching when displayed to the client. As such, if a Patch object is missing some fields from the previous object, these fields should not be displayed to the user
|
||||
Here is a sample `Patch` for the aforementioned object:
|
||||
|
||||
Here is an example `Patch` for the aforementioned object:
|
||||
```json5
|
||||
{
|
||||
"type": "Patch",
|
||||
|
|
@ -28,4 +28,38 @@ Here is an example `Patch` for the aforementioned object:
|
|||
}
|
||||
```
|
||||
|
||||
`Patch`es inherit all other properties from Publications.
|
||||
## Fields
|
||||
|
||||
### ID
|
||||
|
||||
This ID must be distinct from the original Note object, but it does not replace the original Note object's ID. It serves to identify the Patch object.
|
||||
|
||||
### Patched ID
|
||||
|
||||
| Name | Type | Required |
|
||||
| :--------- | :----- | :------- |
|
||||
| patched_id | String | Yes |
|
||||
|
||||
This is the URI of the object being patched. It must be a [Note](./note).
|
||||
|
||||
### Patched At
|
||||
|
||||
| Name | Type | Required |
|
||||
| :--------- | :----- | :------- |
|
||||
| patched_at | String | Yes |
|
||||
|
||||
This is the date and time when the object was patched. It must be in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
|
||||
|
||||
### Other
|
||||
|
||||
`Patch` objects inherit all other properties from [Publications](./publications).
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Patch extends Publication {
|
||||
type: "Patch";
|
||||
patched_id: string;
|
||||
patched_at: string;
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -10,27 +10,24 @@ Here is an example publication:
|
|||
"uri": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19",
|
||||
"author": "https://example.com/users/6e0204a2-746c-4972-8602-c4f37fc63bbe",
|
||||
"created_at": "2021-01-01T00:00:00.000Z",
|
||||
"contents": [
|
||||
{
|
||||
"content": "Hello, world!",
|
||||
"content_type": "text/plain"
|
||||
"content": {
|
||||
"text/plain": {
|
||||
"content": "Hello, world!"
|
||||
},
|
||||
{
|
||||
"content": "Hello, <b>world</b>!",
|
||||
"content_type": "text/html"
|
||||
"text/html": {
|
||||
"content": "Hello, <b>world</b>!"
|
||||
}
|
||||
],
|
||||
},
|
||||
"visibility": "public",
|
||||
"attachments": [
|
||||
[
|
||||
{
|
||||
"content": "https://cdn.example.com/attachments/ece2f9d9-27d7-457d-b657-4ce9172bdcf8.png",
|
||||
"content_type": "image/png"
|
||||
{
|
||||
"image/png": {
|
||||
"content": "https://cdn.example.com/attachments/ece2f9d9-27d7-457d-b657-4ce9172bdcf8.png"
|
||||
},
|
||||
{
|
||||
"content": "https://cdn.example.com/attachments/ece2f9d9-27d7-457d-b657-4ce9172bdcf8.webp",
|
||||
"content_type": "image/webp"
|
||||
"image/webp": {
|
||||
"content": "https://cdn.example.com/attachments/ece2f9d9-27d7-457d-b657-4ce9172bdcf8.webp"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"replies_to": "https://test.com/publications/0b6ecf49-2959-4590-afb6-232f57036fa6",
|
||||
"mentions": [
|
||||
|
|
@ -39,80 +36,92 @@ Here is an example publication:
|
|||
}
|
||||
```
|
||||
|
||||
## Type
|
||||
## Fields
|
||||
|
||||
### Type
|
||||
|
||||
Currently available types are:
|
||||
- [`Note`](/objects/note)
|
||||
- [`Patch`](/objects/patch)
|
||||
- [`Note`](./note)
|
||||
- [`Patch`](./patch)
|
||||
|
||||
## Author
|
||||
### Author
|
||||
|
||||
The `author` field on a Publication is a string that represents the URI of the user that created the object. It is used to identify the author of the Publication.
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
The `author` field is required on all publications.
|
||||
URI of the user that created the object.
|
||||
|
||||
## Contents
|
||||
### Content
|
||||
|
||||
The `contents` field on a Publication is an array that contains a list of `ContentFormat` objects.
|
||||
| Name | Type | Required |
|
||||
| :------ | :------------ | :------- |
|
||||
| content | ContentFormat | No |
|
||||
|
||||
The `contents` field is not required on all publications. If it is not provided, it is assumed that the publication does not have any content.
|
||||
Content of the Publication, such as note text for [Notes](./note). If it is not provided, it is assumed that the publication does not have any content.
|
||||
|
||||
It is recommended that servers limit the length of the content from 500 to a couple thousand characters, but it is up to the server to decide how long the content can be. The protocol does not have an upper limit for the length of the content.
|
||||
|
||||
The `contents` field **MUST** be a text format, such as `text/plain` or `text/html`. The `contents` field **MUST NOT** be a binary format, such as `image/png` or `video/mp4`. Platforms such as video sharing sites should use the `attachments` field for media instead.
|
||||
The `content` field **MUST** be a text format, such as `text/plain` or `text/html`. The `content` field **MUST NOT** be a binary format, such as `image/png` or `video/mp4`. Platforms such as video sharing sites should use the `attachments` field for media instead.
|
||||
|
||||
An example value for the `contents` field would be:
|
||||
An example value for the `content` field would be:
|
||||
```json5
|
||||
{
|
||||
// ...
|
||||
"contents": [
|
||||
{
|
||||
"content": "Hello, world!",
|
||||
"content_type": "text/plain"
|
||||
"content": {
|
||||
"text/plain": {
|
||||
"content": "Hello, world!"
|
||||
},
|
||||
{
|
||||
"content": "Hello, <b>world</b>!",
|
||||
"content_type": "text/html"
|
||||
"text/html": {
|
||||
"content": "Hello, <b>world</b>!"
|
||||
}
|
||||
]
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** Lysand heavily recommends that servers support the `text/html` content type, as it is the richest content type that is supported by most clients.
|
||||
|
||||
> **Note**: Lysand also recommends that servers always include a `text/plain` version of each object, as it is the most basic content type that is supported by all clients, such as command line clients.
|
||||
> [!NOTE]
|
||||
> Lysand heavily recommends that servers support the `text/html` content type, as it is the richest content type that is supported by most clients.
|
||||
>
|
||||
> Lysand also recommends that servers always include a `text/plain` version of each object, as it is the most basic content type that is supported by all clients, such as command line clients.
|
||||
|
||||
It is up to the client to choose which content format to display to the user. The client may choose to display the first content format that it supports, or it may choose to display the content format that it thinks is the most appropriate.
|
||||
|
||||
Lysand recommends that clients display the richest content format that they support, such as HTML or more exotic formats such as MFM.
|
||||
|
||||
## Attachments
|
||||
### Attachments
|
||||
|
||||
The `attachments` field on a Publication is an array that contains arrays of `ContentFormat` structures. It is used to attach files to a publication.
|
||||
| Name | Type | Required |
|
||||
| :---------- | :--------------------- | :------- |
|
||||
| attachments | Array of ContentFormat | No |
|
||||
|
||||
The `attachments` field is not required on all publications. If it is not provided, it is assumed that the publication does not have any attachments.
|
||||
Contains list of attachments for the publication in [ContentFormat](../structures/content-format) structure. f it is not provided, it is assumed that the publication does not have any attachments.
|
||||
|
||||
It is recommended that servers limit the number of attachments to 20, but it is up to the server to decide how many attachments a publication can have. The protocol does not have an upper limit for the number of attachments.
|
||||
|
||||
The `attachments` field **MAY** be in any format, such as `image/png`, `image/webp`, `video/mp4`, or `audio/mpeg`. It is up to the server to decide which formats are allowed.
|
||||
|
||||
> **Note:** Lysand recommends that servers let users upload any file as an attachment, but clients should warn users before downloading potentially malicious files, such as `.exe` files.
|
||||
> [!NOTE]
|
||||
> Lysand recommends that servers let users upload any file as an attachment, but clients should warn users before downloading potentially malicious files, such as `.exe` files.
|
||||
|
||||
## Replies To
|
||||
### Replies To
|
||||
|
||||
The `replies_to` field on a Publication is the URI of the `Note` that the publication is replying to. It is used to determine the reply chain of an object.
|
||||
| Name | Type | Required |
|
||||
| :--------- | :----- | :------- |
|
||||
| replies_to | String | No |
|
||||
|
||||
The `replies_to` field is not required on all publications. If it is not provided, it is assumed that the object is not replying to any other object.
|
||||
URI of the `Note` that the publication is replying to, if any. Used to determine the reply chain of an object.
|
||||
|
||||
## Quotes
|
||||
### Quotes
|
||||
|
||||
The `quotes` field on a Publication is the URI of the `Note` that the publication is quoting. It is used to determine the quote chain of an object.
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| quotes | String | No |
|
||||
|
||||
URI of the `Note` that the publication is quoting, if any. It is used to determine the quote chain of an object.
|
||||
|
||||
Quoting is similar to replying, but it does not (by default) notify the user that they were quoted. It is meant to be used to comment or add context to another publication.
|
||||
|
||||
The `quotes` field is not required on all publications. If it is not provided, it is assumed that the object is not quoting any other object.
|
||||
|
||||
Example of quoting:
|
||||
```json5
|
||||
{
|
||||
|
|
@ -124,11 +133,13 @@ Example of quoting:
|
|||
|
||||
Quoting **SHOULD BE** rendered differently from replying, such as by adding a quote block to the publication or including the quoted post in the publication.
|
||||
|
||||
## Mentions
|
||||
### Mentions
|
||||
|
||||
The `mentions` field on a Publication is an array that contains a list of URIs that represent the users that the publication is mentioning. It is used to determine which users are mentioned in a publication.
|
||||
| Name | Type | Required |
|
||||
| :------- | :-------------- | :------- |
|
||||
| mentions | Array of String | No |
|
||||
|
||||
The `mentions` field is not required on all publications. If it is not provided, it is assumed that the publication is not mentioning any other users.
|
||||
URIs of users that the publication is mentioning. (such as `@username@server.social` in a note). If it is not provided, it is assumed that the publication is not mentioning any other users.
|
||||
|
||||
An example value for `mentions` would be:
|
||||
```json5
|
||||
|
|
@ -141,19 +152,21 @@ An example value for `mentions` would be:
|
|||
}
|
||||
```
|
||||
|
||||
## Subject
|
||||
### Subject
|
||||
|
||||
The `subject` field on a Publication is a **string** that represents the subject of the publication. It may be used as a content warning or spoiler warning.
|
||||
| Name | Type | Required |
|
||||
| :------ | :----- | :------- |
|
||||
| subject | String | No |
|
||||
|
||||
The `subject` field is not required on all publications. If it is not provided, it is assumed that the publication does not have a subject.
|
||||
Subject of the publication. May be used as a content warning or spoiler warning. If not provided or is empty, there is no subject.
|
||||
|
||||
It is recommended that servers limit the length of the subject from 1 to 300 characters, but it is up to the server to decide how long the subject can be. The protocol does not have an upper limit for the length of the subject.
|
||||
|
||||
The `subject` field **MUST NOT** be a `ContentFormat` object. It **MUST** be a string, and **MUST** be plain text. It **MUST NOT** contain any HTML or other markup.
|
||||
|
||||
> See [ContentFormat](/structures/content-format) for more information on `ContentFormat` objects.
|
||||
See [ContentFormat](/structures/content-format) for more information on `ContentFormat` objects.
|
||||
|
||||
> Client extensions are welcome to add support for HTML or other markup in the `subject` field, but it is not recommended.
|
||||
Client extensions are welcome to add support for HTML or other markup in the `subject` field, but it is not made this way by design (although [Custom Emojis](../extensions/custom-emojis) are supported)
|
||||
|
||||
An example value for `subject` would be:
|
||||
```json5
|
||||
|
|
@ -164,11 +177,13 @@ An example value for `subject` would be:
|
|||
}
|
||||
```
|
||||
|
||||
## Is Sensitive
|
||||
### Is Sensitive
|
||||
|
||||
The `is_sensitive` field on a Publication is a **boolean** that represents whether or not the publication is sensitive. It may be used as a content warning or spoiler warning.
|
||||
| Name | Type | Required |
|
||||
| :----------- | :----- | :------- |
|
||||
| is_sensitive | String | No |
|
||||
|
||||
The `is_sensitive` field is not required on all publications. If it is not provided, it is assumed that the publication is not sensitive.
|
||||
Whether or not the publication contains sensitive content, whether in the content or in attachments or emojis. May be used as a content warning or spoiler warning. If not provided, it is assumed that the publication is not sensitive.
|
||||
|
||||
An example value for `is_sensitive` would be:
|
||||
```json5
|
||||
|
|
@ -177,4 +192,45 @@ An example value for `is_sensitive` would be:
|
|||
"is_sensitive": true
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Visibility
|
||||
|
||||
| Name | Type | Required |
|
||||
| :--------- | :--------- | :------- |
|
||||
| visibility | Visibility | Yes |
|
||||
|
||||
Can be `public`, `unlisted`, `followers`, or `direct`. If not provided, it is assumed that the publication is public.
|
||||
|
||||
- `public`: The publication is visible to everyone, including anonymous users.
|
||||
- `unlisted`: The publication is visible to everyone, but it should not appear in public timelines or search results.
|
||||
- `followers`: The publication is visible to followers only.
|
||||
- `direct`: The publication is a direct message, and is visible only to the mentioned users.
|
||||
|
||||
Servers **MUST** respect the visibility of the publication and **MUST NOT** show the publication to users who are not allowed to see it.
|
||||
|
||||
## Types
|
||||
|
||||
```typescript
|
||||
interface Publication {
|
||||
type: "Note" | "Patch";
|
||||
author: string;
|
||||
content?: ContentFormat;
|
||||
attachments?: ContentFormat[];
|
||||
replies_to?: string;
|
||||
quotes?: string;
|
||||
mentions?: string[];
|
||||
subject?: string;
|
||||
is_sensitive?: boolean;
|
||||
visibility: Visibility;
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
enum Visibility {
|
||||
Public = "public",
|
||||
Unlisted = "unlisted",
|
||||
Followers = "followers",
|
||||
Direct = "direct"
|
||||
}
|
||||
```
|
||||
|
|
@ -23,3 +23,21 @@ Example:
|
|||
"object": "https://example.com/publications/f08a124e-fe90-439e-8be4-15a428a72a19"
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
### Author
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| author | String | Yes |
|
||||
|
||||
URI of the [Actor](./actors) who initiated the action.
|
||||
|
||||
### Object
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| object | String | Yes |
|
||||
|
||||
URI of the object being undone. The object **MUST** be an [Action](./actions) or a [Note](./note). To undo [Patch](./patch) objects, use a subsequent [Patch](./patch) or delete the original [Note](./note).
|
||||
|
|
@ -73,17 +73,17 @@ All text fields can incorporate [Custom Emojis](../extensions/custom-emojis) as
|
|||
|
||||
The `type` of a `User` is invariably `User`.
|
||||
|
||||
### ID
|
||||
|
||||
The `id` field on an Actor is a UUID that signifies the unique identifier of the actor as a string. It is utilized to identify the actor, and **MUST** be unique across all actors of the server.
|
||||
|
||||
### Public Key
|
||||
|
||||
The `public_key` field on an Actor is an [`ActorPublicKeyData`](../cryptography/keys) object. It is employed to authenticate the actor's identity. The key **MUST** be encoded in base64.
|
||||
| Name | Type | Required |
|
||||
| :--------- | :----------------------------------------- | :------- |
|
||||
| public_key | [ActorPublicKeyData](../cryptography/keys) | Yes |
|
||||
|
||||
Author public key. Used to authenticate the actor's identity for their posts. The key **MUST** be encoded in base64.
|
||||
|
||||
All actors **MUST** have a `public_key` field. All servers **SHOULD** authenticate the actor's identity using the `public_key` field, which is used to encode any HTTP requests emitted on behalf of the actor.
|
||||
|
||||
> For more information on cryptographic signing, please see the [Signing](/cryptography/signing) page.
|
||||
For more information on cryptographic signing, please see the [Signing](/cryptography/signing) page.
|
||||
|
||||
Example of encoding the key in TypeScript:
|
||||
```ts
|
||||
|
|
@ -93,9 +93,11 @@ const publicKey = btoa(String.fromCharCode(...new Uint8Array(await crypto.subtle
|
|||
|
||||
### Display Name
|
||||
|
||||
The `display_name` field on an Actor is a string that signifies the actor's display name. It is used to present the actor's name to the user.
|
||||
| Name | Type | Required |
|
||||
| :----------- | :----- | :------- |
|
||||
| display_name | String | No |
|
||||
|
||||
The `display_name` field is optional. If it is not provided, it is assumed that the actor does not have a display name, and the actor's username should be used instead.
|
||||
User's display name. If it is not provided, it is assumed that the actor does not have a display name, and the actor's username should be used instead as a fallback.
|
||||
|
||||
Display names **MUST** be treated as mutable, and **MUST NOT** be used to identify the actor.
|
||||
|
||||
|
|
@ -103,15 +105,17 @@ It is recommended that servers limit the display name length from 1 to 50 charac
|
|||
|
||||
### Username
|
||||
|
||||
The `username` field on an Actor is a string that signifies the actor's username. It is used to loosely identify the actor, and **MUST** be unique across all actors of a server.
|
||||
| Name | Type | Required |
|
||||
| :------- | :----- | :------- |
|
||||
| username | String | Yes |
|
||||
|
||||
The `username` field is mandatory on all actors.
|
||||
Actor's username (`@cpluspatch` for example). It is used to loosely identify the actor, and **MUST** be unique across all actors of a server.
|
||||
|
||||
The `username` field **MUST NOT** be used to identify the actor internally or across the protocol. It is only meant to be used as a display name, and as such is mutable by the user.
|
||||
|
||||
The `username` field **MUST** be a string that contains only alphanumeric characters, underscores, and dashes. It **MUST NOT** contain any spaces or other special characters.
|
||||
The `username` field **MUST** be a string that contains only alphanumeric lowercase characters, underscores, and dashes. It **MUST NOT** contain any spaces or other special characters.
|
||||
|
||||
It **MUST** match this regex: `/^[a-zA-Z0-9_-]+$/`
|
||||
It **MUST** match this regex: `/^[a-z0-9_-]+$/`
|
||||
|
||||
It is recommended that servers limit the username length from 1 to 20 characters, but the server has the discretion to decide the username length. The protocol does not impose an upper limit for the username length.
|
||||
|
||||
|
|
@ -123,7 +127,11 @@ Since user search is done via the username, servers could implement a username h
|
|||
|
||||
### Indexable
|
||||
|
||||
The `indexable` field on an Actor is a boolean that signifies whether or not the actor should be indexed by search engines. This field is mandatory and must be included.
|
||||
| Name | Type | Required |
|
||||
| :-------- | :------ | :------- |
|
||||
| indexable | Boolean | Yes |
|
||||
|
||||
Whether or not the actor should be indexed by search engines.
|
||||
|
||||
Servers and search engines should respect the `indexable` field, and **SHOULD NOT** index the actor if the `indexable` field is set to `false`. This is to protect the privacy of users that do not want to be indexed by search engines.
|
||||
|
||||
|
|
@ -133,9 +141,11 @@ This field should also trigger a change in the `robots.txt` file of the server,
|
|||
|
||||
### Avatar
|
||||
|
||||
The `avatar` field on an Actor is a [ContentFormat](../structures/content-format) object. It is intended to serve as a profile picture for users.
|
||||
| Name | Type | Required |
|
||||
| :----- | :------------ | :------- |
|
||||
| avatar | ContentFormat | No |
|
||||
|
||||
The `avatar` field is optional. If it is not provided, it is assumed that the actor does not have an avatar.
|
||||
Profile picture for users. If it is not provided, it is assumed that the actor does not have an avatar.
|
||||
|
||||
The avatar content_type **MUST** be an image format, such as `image/png` or `image/jpeg`. The avatar content_type **MUST NOT** be a video format, such as `video/mp4` or `video/webm`.
|
||||
|
||||
|
|
@ -145,9 +155,11 @@ Clients should display the most modern format that they support, such as WebP, A
|
|||
|
||||
### Header
|
||||
|
||||
The `header` field on an Actor is a [ContentFormat](../structures/content-format) object. It is intended to serve as a banner for users.
|
||||
| Name | Type | Required |
|
||||
| :----- | :------------ | :------- |
|
||||
| header | ContentFormat | No |
|
||||
|
||||
The `header` field is optional. If it is not provided, it is assumed that the actor does not have a header.
|
||||
Banner for users. If it is not provided, it is assumed that the actor does not have a header.
|
||||
|
||||
The header content_type **MUST** be an image format, such as `image/png` or `image/jpeg` (animated images are permitted). The header content_type **MUST NOT** be a video format, such as `video/mp4` or `video/webm`.
|
||||
|
||||
|
|
@ -157,11 +169,11 @@ Clients should display the most modern format that they support, such as WebP, A
|
|||
|
||||
### Bio
|
||||
|
||||
The `bio` field on an Actor is a [ContentFormat](../structures/content-format) object.
|
||||
| Name | Type | Required |
|
||||
| :--- | :------------ | :------- |
|
||||
| bio | ContentFormat | No |
|
||||
|
||||
The `bio` field is optional. If it is not provided, it is assumed that the actor does not have a bio.
|
||||
|
||||
The `bio` field is used to display a short description of the actor to the user. It is recommended that servers limit the bio length from 500 to a couple thousand characters, but the server has the discretion to decide the bio length. The protocol does not impose an upper limit for the bio length.
|
||||
Used to display a short description of the actor to cleints. It is recommended that servers limit the bio length from 500 to a couple thousand characters, but the server has the discretion to decide the bio length. The protocol does not impose an upper limit for the bio length.
|
||||
|
||||
The `bio` **MUST** be a text format, such as `text/plain` or `text/html`. The `bio` **MUST NOT** be a binary format, such as `image/png` or `video/mp4`.
|
||||
|
||||
|
|
@ -190,9 +202,11 @@ It is up to the client to choose which content format to display to the user. Th
|
|||
|
||||
### Fields
|
||||
|
||||
The `fields` field on an Actor is an array that contains a list of `Field` objects. It is used to display custom fields of key-value pairs to the user, such as additional metadata.
|
||||
| Name | Type | Required |
|
||||
| :----- | :------------- | :------- |
|
||||
| fields | Array of Field | No |
|
||||
|
||||
The `fields` field is optional. If it is not provided, it is assumed that the actor does not have any fields.
|
||||
Custom key-value pairs for clients, such as additional metadata. If not provided, it is assumed that the actor does not have any fields.
|
||||
|
||||
An example value for the `fields` field would be:
|
||||
```json5
|
||||
|
|
@ -231,32 +245,60 @@ The `key` and `value` fields **MUST** be text formats, such as `text/plain` or `
|
|||
|
||||
### Featured
|
||||
|
||||
| Name | Type | Required |
|
||||
| :------- | :----- | :------- |
|
||||
| featured | String | Yes |
|
||||
|
||||
Please refer to [Featured Publications](../federation/endpoints) for more information.
|
||||
|
||||
### Followers
|
||||
|
||||
| Name | Type | Required |
|
||||
| :-------- | :----- | :------- |
|
||||
| followers | String | Yes |
|
||||
|
||||
Please refer to [User Followers](../federation/endpoints) for more information.
|
||||
|
||||
### Following
|
||||
|
||||
| Name | Type | Required |
|
||||
| :-------- | :----- | :------- |
|
||||
| following | String | Yes |
|
||||
|
||||
Please refer to [User Following](../federation/endpoints) for more information.
|
||||
|
||||
### Likes
|
||||
|
||||
| Name | Type | Required |
|
||||
| :---- | :----- | :------- |
|
||||
| likes | String | Yes |
|
||||
|
||||
Please refer to [User Likes](../federation/endpoints) for more information.
|
||||
|
||||
### Dislikes
|
||||
|
||||
| Name | Type | Required |
|
||||
| :------- | :----- | :------- |
|
||||
| dislikes | String | Yes |
|
||||
|
||||
Please refer to [User Dislikes](../federation/endpoints) for more information.
|
||||
|
||||
### Inbox
|
||||
|
||||
| Name | Type | Required |
|
||||
| :---- | :----- | :------- |
|
||||
| inbox | String | Yes |
|
||||
|
||||
The `inbox` field on an Actor is a string that displays the URI of the actor's inbox. It is used to identify the actor's inbox for federation.
|
||||
|
||||
Please refer to [Inbox](../federation/endpoints) for more information.
|
||||
|
||||
### Outbox
|
||||
|
||||
| Name | Type | Required |
|
||||
| :----- | :----- | :------- |
|
||||
| outbox | String | Yes |
|
||||
|
||||
The `outbox` field on an Actor is a string that displays the URI of the actor's outbox. It is used to identify the actor's outbox for federation.
|
||||
|
||||
Please refer to [Outbox](../federation/endpoints) for more information.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Here's how a Collections can be represented in TypeScript:
|
|||
interface Collections<T> {
|
||||
first: string;
|
||||
last: string;
|
||||
totalCount: number;
|
||||
total_count: number;
|
||||
author: string;
|
||||
next?: string;
|
||||
prev?: string;
|
||||
|
|
@ -20,7 +20,7 @@ Collections are intended to be served in a paginated format, with a set of items
|
|||
|
||||
Collections **MUST** include:
|
||||
- A `first` field that holds the URI of the first page of collection items, and a `last` field that holds the URI of the last page of collection items. In the case that there is only one page, `first` and `last` should be the same.
|
||||
- A `totalCount` field that holds the total number of items in the set, across all pages.
|
||||
- A `total_count` field that holds the total number of items in the set, across all pages.
|
||||
- A `next` field that holds the URI of the next set of items, and a `prev` field that holds the URI of the previous set of items. These fields are optional if the user is on the first or last set of items.
|
||||
- An `items` field that holds a paginated array of items in the set. (for example, a series of publications or a group of users)
|
||||
- An `author` field that holds the URI of the entity that created the set (such as the [Actor](../objects/actors) that creates posts). This is used to identify the creator of the set for signing. If the set is generated by the server and not by a specific user (such as the Endorsement set with the [ServerEndorsement Extension](/extensions/server-endorsement)), the `author` should be the server actor's URI.
|
||||
|
|
|
|||
Loading…
Reference in a new issue