Release Versia Protocol 0.5

.github/workflows/mirror.yml

@@ -0,0 +1,8 @@
+name: Mirror to Codeberg
+on: [push]
+
+jobs:
+  mirror:
+    name: Mirror
+    uses: versia-pub/.github/.github/workflows/mirror.yml@main
+    secrets: inherit

app/changelog/page.mdx

@@ -6,9 +6,35 @@ export const metadata = {
 
 # Changelog
 
-This page lists changes since Working Draft 03. {{ className: 'lead' }}
+This page lists changes since Working Draft 3. {{ className: 'lead' }}
 
-## Since WD 03
+## Since WD 4
+
+- Removed URI from [Report](/extensions/reports), and replaced `reason` with `tags`.
+- Docs now use the term "Transient Entity" where appropriate.
+- Mandated Unix-style `\n` line endings in all text fields.
+- Renamed the following headers, as per [RFC 6648](https://tools.ietf.org/html/rfc6648):
+  - `X-Signature` to `Versia-Signature`
+  - `X-Signed-By` to `Versia-Signed-By`
+- Removed the nonce from the [signature system](/signatures), replaced with `Versia-Signed-At` (timestamps).
+- Standardize rate limits with [IETF draft draft-polli-ratelimit-headers-02](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html).
+- Properly documented [Group](/extensions/groups) federation and subscribing.
+- Moved [Groups](/extensions/groups) to an extension, as they were getting too complex for the core protocol.
+  - The [Note](/entities/note) `group` field documentation has been updated to reflect this.
+- Added [Versia Links](/links).
+- Switched from ISO 8601 to [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) for timestamps.
+    - 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`).
+- Add `collections` field to [Notes](/entities/note).
+    - [Likes Extension](/extensions/likes), [Reactions Extension](/extensions/reactions) and [Share Extension](/extensions/share) now use this field, instead of a custom field in `extensions`.
+- Allowed uppercase characters in [User](/entities/user) `username`.
+    - These are now case-insensitive.
+- Added `timezone` field to [Vanity Extension](/extensions/vanity).
+
+## Since WD 3
 
 - Rewrote the signature system from scratch to be simpler and not depend on dates.
 - Moved Likes and Dislikes to an extension.

app/entities/delete/page.mdx

@@ -5,7 +5,7 @@ export const metadata = {
 
 # Delete
 
-Signals the deletion of an entity. {{ className: 'lead' }}
+Signals the deletion of an entity. It is a [**Transient Entity**](/entities#transient-entities). {{ className: 'lead' }}
 
 ## Authorization
 
@@ -19,9 +19,9 @@ Having the authorization is defined as:
 
 <Row>
     <Col>
-        <Properties>
+        <Properties name="Delete">
             <Property name="uri" type="null" required={false}>
-                This entity does not have a URI.
+                This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
             </Property>
             <Property name="author" type="URI | null" required={true} typeLink="/types#uri">
                 URI of the `User` who is deleting the entity. [Can be set to `null` to represent the instance](/entities/instance-metadata#the-null-author).

app/entities/follow-accept/page.mdx

@@ -13,9 +13,9 @@ export const metadata = {
 
 <Row>
     <Col>
-        <Properties>
+        <Properties name="FollowAccept">
             <Property name="uri" type="null" required={false}>
-                This entity does not have a URI.
+                This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
             </Property>
             <Property name="author" type="URI" required={true} typeLink="/types#uri">
                 URI of the `User` considered the 'followee', i.e. the user who is being followed.

app/entities/follow-reject/page.mdx

@@ -23,9 +23,9 @@ But it can also be used when Bob is already following Alice, in the case that:
 
 <Row>
     <Col>
-        <Properties>
+        <Properties name="FollowReject">
             <Property name="uri" type="null" required={false}>
-                This entity does not have a URI.
+                This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
             </Property>
             <Property name="author" type="URI" required={true} typeLink="/types#uri">
                 URI of the `User` considered the 'followee', i.e. the user who is being followed.

app/entities/follow/page.mdx

@@ -55,9 +55,9 @@ Once a follow relationship is established, the **followee**'s instance should se
 
 <Row>
     <Col>
-        <Properties>
+        <Properties name="Follow">
             <Property name="uri" type="null" required={false}>
-                This entity does not have a URI.
+                This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
             </Property>
             <Property name="author" type="URI" required={true} typeLink="/types#uri">
                 URI of the `User` considered the 'follower'.

app/entities/instance-metadata/page.mdx

@@ -17,7 +17,7 @@ Check the entity's documentation page to see if it supports this (it will be not
 
 <Row>
     <Col>
-        <Properties>
+        <Properties name="InstanceMetadata">
             <Property name="id" type="null">
                 This entity does not have an ID.
             </Property>
@@ -74,7 +74,7 @@ Check the entity's documentation page to see if it supports this (it will be not
                 ```
 
                 - `algorithm`: Algorithm used for the public key. Can only be `ed25519` for now.
-                - `key`: Instance public key, in SPKI-encoded base64 (from raw bytes, not a PEM format).
+                - `key`: Instance public key, in [SPKI-encoded base64](/signatures#exporting-the-public-key).
             </Property>
             <Property name="moderators" type="URI" required={false}>
                 URI to [Collection](/structures/collection) of instance moderators.
@@ -112,7 +112,8 @@ Check the entity's documentation page to see if it supports this (it will be not
         "compatibility": {
             "versions": [
                 "0.3.0",
-                "0.4.0"
+                "0.4.0",
+                "0.5.0"
             ],
             "extensions": [
                 "pub.versia:reactions",

app/entities/note/page.mdx

@@ -15,7 +15,7 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
 
 <Row>
     <Col>
-        <Properties>
+        <Properties name="Note">
             <Property name="attachments" type="ContentFormat[]" required={false} typeLink="/structures/content-format">
                 Media attachments to the note. May be any format. **Must** be remote.
             </Property>
@@ -36,6 +36,28 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
                     | "messaging"; // Like Discord, Element (Matrix), Signal
                 ```
             </Property>
+            <Property name="collections" type="NoteCollections" required={true}>
+                Collections related to the note. Must contain at least `replies` and `quotes`.
+
+                ```typescript
+                type URI = string;
+
+                type NoteCollections = {
+                    replies: URI;
+                    quotes: URI;
+                    // Same format as type on Extensions
+                    [key: ExtensionsKey]: URI;
+                }
+                ```
+
+                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.
+
+                ### Replies
+                All replies to this note (have this note as their `replies_to`). [URI Collection](/structures/collection#uri-collection) of [Note](/entities/note) entities.
+
+                ### Quotes
+                All quotes of this note (have this note as their `quotes`). [URI Collection](/structures/collection#uri-collection) of [Note](/entities/note) entities.
+            </Property>
             <Property name="content" type="ContentFormat" required={false} typeLink="/structures/content-format">
                 The content of the note. Must be text format (`text/html`, `text/markdown`, etc). Must not be remote.
             </Property>
@@ -51,11 +73,15 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
                 ```
             </Property>
             <Property name="group" type="URI | &quot;public&quot; | &quot;followers&quot;" required={false} typeLink="/types#uri">
-                URI of a [Group](/entities/group) that the note is only visible in, or one of the following strings:
+                URI of a [Group](/extensions/groups) that the note is only visible in, or one of the following strings:
                 - `public`: The note is visible to anyone.
                 - `followers`: The note is visible only to the author's followers.
 
-                If not provided, the note is only visible to the author and those mentioned in the note.
+                If not provided, the note is only visible to the author and those mentioned in the note. If missing, the note is only visible to any mentioned users.
+
+                <Note>
+                    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}>
                 Whether the note contains "sensitive content". This can be used with `subject` as a "content warning" feature.
@@ -126,6 +152,13 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
         ],
         "author": "https://versia.social/users/018eb863-753f-76ff-83d6-fd590de7740a",
         "category": "microblog",
+        "collections": {
+            "replies": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/replies",
+            "quotes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/quotes",
+            "pub.versia:likes/Likes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/likes",
+            "pub.versia:likes/Dislikes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/dislikes",
+            "pub.versia:reactions/Reactions": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/reactions"
+        },
         "content": {
             "text/html": {
                 "content": "<p>In the next versia-fe update: account settings, finally!</p>"

app/entities/page.mdx

@@ -17,15 +17,15 @@ Any field in an entity not marked as `required` may be omitted or set to `null`.
 <Row>
   <Col>
 
-    <Properties>
+    <Properties name="Entity">
         <Property name="id" type="string" required={true}>
             Unique identifier for the entity. Must be unique within the instance. Can be any string. Max of 512 UTF-8 characters.
         </Property>
         <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="ISO8601" required={true} typeLink="/types#iso-8601">
-            Date and time when the entity was created. Must be an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted string.
+        <Property name="created_at" type="RFC3339" required={true} typeLink="/types#rfc3339">
+            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.
@@ -34,7 +34,16 @@ Any field in an entity not marked as `required` may be omitted or set to `null`.
         <Property name="uri" type="URI" required={true} typeLink="/types#uri">
             URI of the entity. Should be unique and resolve to the entity. Must be an absolute URI.
 
-            **Some entity types may not need a URI. This will be specified in the entity's documentation.**
+            <Note>
+                [**Transient Entities**](/entities#transient-entities) do not require a URI.
+            </Note>
+        </Property>
+        <Property name="$schema" type="string" required={false}>
+            URL of any JSON Schema that the entity adheres to.
+
+            <Note>
+                This is for human use only, and not to be used by either clients or servers as a way to validate the entity.
+            </Note>
         </Property>
         <Property name="extensions" type="Extensions" required={false} typeLink="/types#extensions">
             Extensions to the entity. Use this to add custom properties to the entity.
@@ -77,9 +86,16 @@ Any field in an entity not marked as `required` may be omitted or set to `null`.
     </Col>
 </Row>
 
+## Transient Entities
+
+Some entities are transient, meaning they do not have a URI. These entities are used for actions that do not require a permanent record, such as deletions or migrations.
+
+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 should follow the following rules:
+When serialized to a string, the JSON representation of an entity must follow the following rules:
 - Keys must be sorted lexicographically.
-- Should use UTF-8 encoding.
+- Must use UTF-8 encoding.
 - Must be **signed** using the relevant [User](/entities/user)'s private key, or the [instance's private key](/entities/instance-metadata) if the entity is not associated with a particular user.
+- Must use Unix-style `\n` line endings (LF).

app/entities/unfollow/page.mdx

@@ -28,9 +28,9 @@ Sometimes, [Users](/entities/user) want to unsubscribe from each other to stop s
 
 <Row>
     <Col>
-        <Properties>
+        <Properties name="Unfollow">
             <Property name="uri" type="null" required={false}>
-                This entity does not have a URI.
+                This is a [**Transient Entity**](/entities#transient-entities) and does not have a URI.
             </Property>
             <Property name="author" type="URI" required={true} typeLink="/types#uri">
                 URI of the `User` considered the 'follower', i.e. the user who is unsubscribing from the followee.