mirror of
https://github.com/versia-pub/docs.git
synced 2026-03-13 02:49:16 +01:00
docs: ♻️ Rewrite various docs pages, add null fields everywhere they were missing, make some Note and User fields mandatory
This commit is contained in:
Jesse Wierzbinski
parent
e6f7a27d3e
commit
e9b5ccd76c
31 changed files with 412 additions and 148 deletions
|
|
@ -5,14 +5,14 @@ export const metadata = {
|
|||
|
||||
# Delete
|
||||
|
||||
Signals the deletion of an entity. It is a [**Transient Entity**](/entities#transient-entities). {{ className: 'lead' }}
|
||||
Signals the deletion of an entity. {{ className: 'lead' }}
|
||||
|
||||
## Authorization
|
||||
|
||||
Implementations **must** ensure that the author of the `Delete` entity has the authorization to delete the target entity.
|
||||
|
||||
Having the authorization is defined as:
|
||||
- The author is the creator of the target entity (including [delegation](/federation/delegation)).
|
||||
- The author is the creator of the target entity (including [delegation](/extensions/delegation)).
|
||||
- The author is the instance.
|
||||
|
||||
## Entity Definition
|
||||
|
|
|
|||
|
|
@ -48,8 +48,8 @@ Contains metadata about a Versia instance, such as capabilities and endpoints. {
|
|||
<Property name="description" type="string" required={false}>
|
||||
Long description of the instance, for humans. Should be around 100-200 words.
|
||||
</Property>
|
||||
<Property name="host" type="string" required={true}>
|
||||
Hostname of the instance. Includes the port if it is not the default (i.e. `443` for HTTPS).
|
||||
<Property name="domain" type="Domain" typeLink="/api/basics#domain" required={true}>
|
||||
Domain of the instance, used for federation.
|
||||
</Property>
|
||||
<Property name="public_key" type="PublicKey" required={true}>
|
||||
Public key of the instance.
|
||||
|
|
@ -96,7 +96,7 @@ Contains metadata about a Versia instance, such as capabilities and endpoints. {
|
|||
]
|
||||
},
|
||||
"description": "Server for Jim's Jolly Jimjams, a social network for fans of Jimjams.",
|
||||
"host": "social.jimjams.com",
|
||||
"domain": "social.jimjams.com",
|
||||
"logo": {
|
||||
"image/png": {
|
||||
"content": "https://social.jimjams.com/files/logo.png"
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
|
|||
<Row>
|
||||
<Col>
|
||||
<Properties name="Note">
|
||||
<Property name="attachments" type="ContentFormat[]" required={false} typeLink="/structures/content-format">
|
||||
<Property name="attachments" type="ContentFormat[]" required={true} typeLink="/structures/content-format">
|
||||
Media attachments to the note. May be any format. **Must** be remote.
|
||||
</Property>
|
||||
<Property name="author" type="Reference" required={true} typeLink="/types#reference">
|
||||
|
|
@ -61,13 +61,13 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
|
|||
If the implementation does not support the [Groups Extension](/extensions/groups), any value other than `public` or `followers` should be treated as `null`.
|
||||
</Note>
|
||||
</Property>
|
||||
<Property name="is_sensitive" type="boolean" required={false}>
|
||||
<Property name="is_sensitive" type="boolean" required={true}>
|
||||
Whether the note contains "sensitive content". This can be used with `subject` as a "content warning" feature.
|
||||
</Property>
|
||||
<Property name="mentions" type="Reference[]" required={false} typeLink="/types#reference">
|
||||
<Property name="mentions" type="Reference[]" required={true} typeLink="/types#reference">
|
||||
[References](/types#reference) to [Users](/entities/user) that should be notified of the note. Similar to Twitter's `@` mentions. The note may also contain mentions in the content, however only the mentions in this field should trigger notifications.
|
||||
</Property>
|
||||
<Property name="previews" type="LinkPreview[]" required={false}>
|
||||
<Property name="previews" type="LinkPreview[]" required={true}>
|
||||
Previews for any links in the publication. This is to avoid the [stampeding mastodon problem](https://github.com/mastodon/mastodon/issues/23662) where a link preview is fetched by every instance that sees the publication, creating an accidental DDOS attack.
|
||||
|
||||
```typescript
|
||||
|
|
@ -108,6 +108,9 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
|
|||
"content": "https://cdn.versia.social/29e810bf4707fef373d886af322089d5db300fce66e4e073efc26827f10825f6/image.webp",
|
||||
"remote": true,
|
||||
"thumbhash": "1QcSHQRnh493V4dIh4eXh1h4kJUI",
|
||||
"description": null,
|
||||
"fps": null,
|
||||
"duration": null,
|
||||
"height": 960,
|
||||
"size": 221275,
|
||||
"hash": {
|
||||
|
|
@ -120,6 +123,12 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
|
|||
"text/plain": {
|
||||
"content": "https://cdn.lysand.org/68c02dd11c179ef4d170b05393f6e72133dd0ad733f40d41b42363d8784e8d5d/fire.txt",
|
||||
"remote": true,
|
||||
"description": null,
|
||||
"thumbhash": null,
|
||||
"width": null,
|
||||
"height": null,
|
||||
"fps": null,
|
||||
"duration": null
|
||||
"size": 8,
|
||||
"hash": {
|
||||
"sha256": "68c02dd11c179ef4d170b05393f6e72133dd0ad733f40d41b42363d8784e8d5d"
|
||||
|
|
@ -150,7 +159,10 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
|
|||
"group": "public",
|
||||
"is_sensitive": false,
|
||||
"mentions": [],
|
||||
"subject": "Versia development"
|
||||
"subject": "Versia development",
|
||||
"previews": [],
|
||||
"quotes": null,
|
||||
"replies_to": null
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -6,9 +6,12 @@ export const metadata = {
|
|||
|
||||
# Entities
|
||||
|
||||
Entities are the foundation of the Versia protocol. A similar concept to entities are the [ActivityStreams](https://www.w3.org/TR/activitystreams-core/) objects, which are used to represent activities in the [ActivityPub](https://www.w3.org/TR/activitypub/) protocol. {{ className: 'lead' }}
|
||||
Entities are the foundation of the Versia protocol. They are similar to: {{ className: 'lead' }}
|
||||
|
||||
## Entity Definition
|
||||
- [ActivityStreams](https://www.w3.org/TR/activitystreams-core/) objects
|
||||
- [Matrix](https://matrix.org/) events.
|
||||
|
||||
## Definition
|
||||
|
||||
An entity is a simple JSON object that represents a core data structure in Versia. Entities are used to represent various types of data, such as users, notes, and more. Each entity has a unique `id` property that is used to identify it within the instance.
|
||||
|
||||
|
|
@ -31,11 +34,11 @@ Any field in an entity not marked as `required` may be set to `null`. These fiel
|
|||
<Property name="type" type="string" required={true}>
|
||||
Type of the entity. Custom types must follow [Extension Naming](/extensions#naming).
|
||||
</Property>
|
||||
<Property name="created_at" type="RFC3339" required={true} typeLink="/types#rfc3339">
|
||||
<Property name="created_at" type="RFC3339" required={true} typeLink="/types#rfc-3339">
|
||||
Date and time when the entity was created. Must be an [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp.
|
||||
|
||||
<Note>
|
||||
Handling of dates that are valid but obviously incorrect (e.g. in the future) is left to the Implementation's discretion.
|
||||
Handling of dates that are valid but obviously incorrect (e.g. in the future) is left to the Implementation's discretion. Sending a [Note](/entities/note) created on `13-12-1337` is very funny, but don't be surprised if it is rejected.
|
||||
</Note>
|
||||
</Property>
|
||||
<Property name="$schema" type="string" required={false}>
|
||||
|
|
@ -86,14 +89,6 @@ Any field in an entity not marked as `required` may be set to `null`. These fiel
|
|||
|
||||
## Transient Entities
|
||||
|
||||
Some entities are transient, meaning they cannot be refetched using the [Federation API](/api/endpoints). These entities are used for actions that do not require a permanent record, such as deletions or migrations. Transient Entities do not have an `id` field.
|
||||
Some entities are **transient**, meaning they cannot be fetched using the [Federation API](/api/endpoints). These entities are used for actions that do not require a permanent record, such as deletions or migrations. Transient Entities do not have an `id` field.
|
||||
|
||||
Implementations **must not** rely on other implementations to store transient entities in their database.
|
||||
|
||||
## Serialization
|
||||
|
||||
When serialized to a string, the JSON representation of an entity must follow the following rules:
|
||||
- Keys must be sorted lexicographically.
|
||||
- Must use UTF-8 encoding.
|
||||
- Must be **signed** using the the [instance's private key](/entities/instance-metadata).
|
||||
- Must use Unix-style `\n` line endings (LF).
|
||||
Implementations **must not** rely on other implementations to store transient entities in their database.
|
||||
|
|
@ -35,7 +35,7 @@ Usernames can be changed by the user, so it is recommended to use `id` for long-
|
|||
|
||||
### Instance
|
||||
|
||||
Instance **must** be the host of the instance the user is on (hostname with optional port).
|
||||
Instance **must** be the [Domain](/api/basics#domain) that the user is on.
|
||||
|
||||
## Entity Definition
|
||||
|
||||
|
|
@ -52,7 +52,7 @@ Instance **must** be the host of the instance the user is on (hostname with opti
|
|||
<Property name="display_name" type="string" required={false}>
|
||||
Display name, as shown to other users. May contain emojis and any Unicode character.
|
||||
</Property>
|
||||
<Property name="fields" type="Field[]" required={false}>
|
||||
<Property name="fields" type="Field[]" required={true}>
|
||||
Custom key/value pairs. For example, metadata like socials or pronouns. Must be text format (`text/*`).
|
||||
|
||||
```typescript
|
||||
|
|
@ -70,11 +70,11 @@ Instance **must** be the host of the instance the user is on (hostname with opti
|
|||
<Property name="header" type="ContentFormat" required={false} typeLink="/structures/content-format">
|
||||
A header image for the user's profile. Also known as a cover photo or a banner. Must be an image format (`image/*`).
|
||||
</Property>
|
||||
<Property name="manually_approves_followers" type="boolean" required={false}>
|
||||
If `true`, the user must approve any new followers manually. If `false`, followers are automatically approved. This does not affect federation, and is meant to be used for clients to display correct UI. Defaults to `false`.
|
||||
<Property name="manually_approves_followers" type="boolean" required={true}>
|
||||
If `true`, the user must approve any new followers manually. If `false`, followers are automatically approved. This does not affect federation, and is meant to be used for clients to display correct UI.
|
||||
</Property>
|
||||
<Property name="indexable" type="boolean" required={false}>
|
||||
User consent to be indexed by search engines. If `false`, the user's profile should not be indexed. Defaults to `true`.
|
||||
<Property name="indexable" type="boolean" required={true}>
|
||||
User consent to be indexed by search engines. If `false`, the user's profile should not be indexed.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue