versia-pub/docs
2
0
Fork 0
mirror of https://github.com/versia-pub/docs.git synced 2025-12-06 06:18:19 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

refactor: 📝 Use References nomenclature instead of URI

Browse source
This commit is contained in:
Jesse Wierzbinski 2025-05-05 14:33:22 +02:00
parent d886b83e62
commit bcdf0ec251
No known key found for this signature in database
16 changed files with 137 additions and 90 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
app/entities/delete/page.mdx
View file

@ -24,14 +24,14 @@ Having the authorization is defined as:
<Row> <Row>
<Col> <Col>
<Properties name="Delete"> <Properties name="Delete">
<Property name="author" type="URI | null" required={true} typeLink="/types#uri"> <Property name="author" type="Reference | null" required={true} typeLink="/types#reference">
URI of the `User` who is deleting the entity. [Can be set to `null` to represent the instance](/entities/instance-metadata#the-null-author). [Reference](/types#reference) to the `User` who is deleting the entity. [Can be set to `null` to represent the instance](/entities/instance-metadata#the-null-author).
</Property> </Property>
<Property name="deleted_type" type="string" required={true}> <Property name="deleted_type" type="string" required={true}>
Type of the entity being deleted. Type of the entity being deleted.
</Property> </Property>
<Property name="deleted" type="URI" required={true} typeLink="/types#uri"> <Property name="deleted" type="Reference" required={true} typeLink="/types#reference">
URI of the entity being deleted. [Reference](/types#reference) to the entity being deleted.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

8
app/entities/follow-accept/page.mdx
View file

@ -18,11 +18,11 @@ export const metadata = {
<Row> <Row>
<Col> <Col>
<Properties name="FollowAccept"> <Properties name="FollowAccept">
<Property name="author" type="URI" required={true} typeLink="/types#uri"> <Property name="author" type="Reference" required={true} typeLink="/types#reference">
URI of the `User` considered the 'followee', i.e. the user who is being followed. [Reference](/types#reference) to the `User` considered the 'followee', i.e. the user who is being followed.
</Property> </Property>
<Property name="follower" type="URI" required={true} typeLink="/types#uri"> <Property name="follower" type="Reference" required={true} typeLink="/types#reference">
URI of the `User` considered the 'follower', i.e. the user who is trying to follow the author. [Reference](/types#reference) to the `User` considered the 'follower', i.e. the user who is trying to follow the author.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

8
app/entities/follow-reject/page.mdx
View file

@ -28,11 +28,11 @@ But it can also be used when Bob is already following Alice, in the case that:
<Row> <Row>
<Col> <Col>
<Properties name="FollowReject"> <Properties name="FollowReject">
<Property name="author" type="URI" required={true} typeLink="/types#uri"> <Property name="author" type="Reference" required={true} typeLink="/types#reference">
URI of the `User` considered the 'followee', i.e. the user who is being followed. [Reference](/types#reference) to the `User` considered the 'followee', i.e. the user who is being followed.
</Property> </Property>
<Property name="follower" type="URI" required={true} typeLink="/types#uri"> <Property name="follower" type="Reference" required={true} typeLink="/types#reference">
URI of the `User` considered the 'follower', i.e. the user who is trying to follow the author. [Reference](/types#reference) to the `User` considered the 'follower', i.e. the user who is trying to follow the author.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

8
app/entities/follow/page.mdx
View file

@ -60,11 +60,11 @@ Once a follow relationship is established, the **followee**'s instance should se
<Row> <Row>
<Col> <Col>
<Properties name="Follow"> <Properties name="Follow">
<Property name="author" type="URI" required={true} typeLink="/types#uri"> <Property name="author" type="Reference" required={true} typeLink="/types#reference">
URI of the `User` considered the 'follower'. [Reference](/types#reference) to the `User` considered the 'follower'.
</Property> </Property>
<Property name="followee" type="URI" required={true} typeLink="/types#uri"> <Property name="followee" type="Reference" required={true} typeLink="/types#reference">
URI of the `User` that is being followed. [Reference](/types#reference) to the `User` that is being followed.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

20
app/entities/note/page.mdx
View file

@ -19,8 +19,8 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
<Property name="attachments" type="ContentFormat[]" required={false} typeLink="/structures/content-format"> <Property name="attachments" type="ContentFormat[]" required={false} typeLink="/structures/content-format">
Media attachments to the note. May be any format. **Must** be remote. Media attachments to the note. May be any format. **Must** be remote.
</Property> </Property>
<Property name="author" type="URI" required={true} typeLink="/types#uri"> <Property name="author" type="Reference" required={true} typeLink="/types#reference">
URI of the `User` considered the author of the note. [Reference](/types#reference) to the `User` considered the author of the note.
</Property> </Property>
<Property name="category" type="Category" required={false}> <Property name="category" type="Category" required={false}>
Category of the note. Useful for clients to render notes differently depending on their intended purpose. Category of the note. Useful for clients to render notes differently depending on their intended purpose.
@ -50,8 +50,8 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
} }
``` ```
</Property> </Property>
<Property name="group" type="URI | &quot;public&quot; | &quot;followers&quot;" required={false} typeLink="/types#uri"> <Property name="group" type="Reference | &quot;public&quot; | &quot;followers&quot;" required={false} typeLink="/types#reference">
URI of a [Group](/extensions/groups) that the note is only visible in, or one of the following strings: [Reference](/types#reference) to a [Group](/extensions/groups) that the note is only visible in, or one of the following strings:
- `public`: The note is visible to anyone. - `public`: The note is visible to anyone.
- `followers`: The note is visible only to the author's followers. - `followers`: The note is visible only to the author's followers.
@ -64,8 +64,8 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
<Property name="is_sensitive" type="boolean" required={false}> <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. Whether the note contains "sensitive content". This can be used with `subject` as a "content warning" feature.
</Property> </Property>
<Property name="mentions" type="URI[]" required={false} typeLink="/types#uri"> <Property name="mentions" type="Reference[]" required={false} typeLink="/types#reference">
URIs of [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. [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>
<Property name="previews" type="LinkPreview[]" required={false}> <Property name="previews" type="LinkPreview[]" required={false}>
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. 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.
@ -84,11 +84,11 @@ Notes represent a piece of content on a Versia instance. They can be posted by [
Implementations should make sure not to trust the previews, as they could be faked by malicious remote instances. This is not a very good attack vector, but it is still possible to redirect users to malicious links. Implementations should make sure not to trust the previews, as they could be faked by malicious remote instances. This is not a very good attack vector, but it is still possible to redirect users to malicious links.
</Note> </Note>
</Property> </Property>
<Property name="quotes" type="URI" required={false} typeLink="/types#uri"> <Property name="quotes" type="Reference" required={false} typeLink="/types#reference">
URI of the note that this note is quoting, if any. Quoting is similar to replying, but does not notify the author of the quoted note. Inspired by Twitter's "quote tweet" feature. [Reference](/types#reference) to the note that this note is quoting, if any. Quoting is similar to replying, but does not notify the author of the quoted note. Inspired by Twitter's "quote tweet" feature.
</Property> </Property>
<Property name="replies_to" type="URI" required={false} typeLink="/types#uri"> <Property name="replies_to" type="Reference" required={false} typeLink="/types#reference">
URI of the note that this note is a reply to, if any. [Reference](/types#reference) to the note that this note is a reply to, if any.
</Property> </Property>
<Property name="subject" type="string" required={false}> <Property name="subject" type="string" required={false}>
A subject for the note. Useful for clients to display a "content warning" or "spoiler" feature, such as on Mastodon. Must be a plaintext string (`text/plain`). A subject for the note. Useful for clients to display a "content warning" or "spoiler" feature, such as on Mastodon. Must be a plaintext string (`text/plain`).

8
app/entities/unfollow/page.mdx
View file

@ -33,11 +33,11 @@ Sometimes, [Users](/entities/user) want to unsubscribe from each other to stop s
<Row> <Row>
<Col> <Col>
<Properties name="Unfollow"> <Properties name="Unfollow">
<Property name="author" type="URI" required={true} typeLink="/types#uri"> <Property name="author" type="Reference" required={true} typeLink="/types#reference">
URI of the `User` considered the 'follower', i.e. the user who is unsubscribing from the followee. [Reference](/types#reference) to the `User` considered the 'follower', i.e. the user who is unsubscribing from the followee.
</Property> </Property>
<Property name="followee" type="URI" required={true} typeLink="/types#uri"> <Property name="followee" type="Reference" required={true} typeLink="/types#reference">
URI of the `User` considered the 'followee', i.e. the user who is being unsubscribed from. [Reference](/types#reference) to the `User` considered the 'followee', i.e. the user who is being unsubscribed from.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

40
app/extensions/groups/page.mdx
View file

@ -93,11 +93,11 @@ Indicates that a [User](/entities/user) wishes to subscribe to a group.
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:groups/Subscribe`. Must be `pub.versia:groups/Subscribe`.
</Property> </Property>
<Property name="subscriber" type="URI" required={true} typeLink="/types#uri"> <Property name="subscriber" type="Reference" required={true} typeLink="/types#reference">
URI of the [User](/entities/user) subscribing to the group. [Reference](/types#reference) to the [User](/entities/user) subscribing to the group.
</Property> </Property>
<Property name="group" type="URI" required={true} typeLink="/types#uri"> <Property name="group" type="Reference" required={true} typeLink="/types#reference">
URI of the group to subscribe to. [Reference](/types#reference) to the group to subscribe to.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>
@ -131,11 +131,11 @@ Indicates that a [User](/entities/user) wishes to unsubscribe from a group.
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:groups/Unsubscribe`. Must be `pub.versia:groups/Unsubscribe`.
</Property> </Property>
<Property name="subscriber" type="URI" required={true} typeLink="/types#uri"> <Property name="subscriber" type="Reference" required={true} typeLink="/types#reference">
URI of the [User](/entities/user) unsubscribing from the group. [Reference](/types#reference) to the [User](/entities/user) unsubscribing from the group.
</Property> </Property>
<Property name="group" type="URI" required={true} typeLink="/types#uri"> <Property name="group" type="Reference" required={true} typeLink="/types#reference">
URI of the group to unsubscribe from. [Reference](/types#reference) to the group to unsubscribe from.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>
@ -169,11 +169,11 @@ Indicates that a [Group](#entity-definition) has accepted a [User](/entities/use
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:groups/SubscribeAccept`. Must be `pub.versia:groups/SubscribeAccept`.
</Property> </Property>
<Property name="subscriber" type="URI" required={true} typeLink="/types#uri"> <Property name="subscriber" type="Reference" required={true} typeLink="/types#reference">
URI of the [User](/entities/user) subscribing to the group. [Reference](/types#reference) to the [User](/entities/user) subscribing to the group.
</Property> </Property>
<Property name="group" type="URI" required={true} typeLink="/types#uri"> <Property name="group" type="Reference" required={true} typeLink="/types#reference">
URI of the group that accepted the subscription. [Reference](/types#reference) to the group that accepted the subscription.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>
@ -207,11 +207,11 @@ Indicates that a [Group](#entity-definition) has rejected a [User](/entities/use
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:groups/SubscribeReject`. Must be `pub.versia:groups/SubscribeReject`.
</Property> </Property>
<Property name="subscriber" type="URI" required={true} typeLink="/types#uri"> <Property name="subscriber" type="Reference" required={true} typeLink="/types#reference">
URI of the [User](/entities/user) subscribing to the group. [Reference](/types#reference) to the [User](/entities/user) subscribing to the group.
</Property> </Property>
<Property name="group" type="URI" required={true} typeLink="/types#uri"> <Property name="group" type="Reference" required={true} typeLink="/types#reference">
URI of the group that rejected the subscription. [Reference](/types#reference) to the group that rejected the subscription.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>
@ -253,11 +253,11 @@ The `GroupFederate` entity allows a group to federate a note to all of its membe
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:groups/Federate`. Must be `pub.versia:groups/Federate`.
</Property> </Property>
<Property name="note" type="URI" required={true} typeLink="/types#uri"> <Property name="note" type="Reference" required={true} typeLink="/types#reference">
URI of the note to federate. [Reference](/types#reference) to the note to federate.
</Property> </Property>
<Property name="group" type="URI" required={true} typeLink="/types#uri"> <Property name="group" type="Reference" required={true} typeLink="/types#reference">
URI of the group federating the note. [Reference](/types#reference) to the group federating the note.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

16
app/extensions/likes/page.mdx
View file

@ -22,11 +22,11 @@ Likes are a way for users to show appreciation for a note, like Twitter's "heart
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:likes/Like`. Must be `pub.versia:likes/Like`.
</Property> </Property>
<Property name="author" type="URI" required={true} typeLink="/types#uri"> <Property name="author" type="Reference" required={true} typeLink="/types#reference">
Creator of the Like. [Reference](/types#reference) to the creator of the Like.
</Property> </Property>
<Property name="liked" type="URI" required={true} typeLink="/types#uri"> <Property name="liked" type="Reference" required={true} typeLink="/types#reference">
URI of the note being liked. Must link to a [Note](/entities/note). [Reference](/types#reference) to the note being liked.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>
@ -58,11 +58,11 @@ Dislikes are a way for users to show disapproval for a note, like YouTube's "dis
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:likes/Dislike`. Must be `pub.versia:likes/Dislike`.
</Property> </Property>
<Property name="author" type="URI" required={true} typeLink="/types#uri"> <Property name="author" type="Reference" required={true} typeLink="/types#reference">
Creator of the Dislike. [Reference](/types#reference) to the creator of the Dislike.
</Property> </Property>
<Property name="disliked" type="URI" required={true} typeLink="/types#uri"> <Property name="disliked" type="Reference" required={true} typeLink="/types#reference">
URI of the note being disliked. Must link to a [Note](/entities/note). [Reference](/types#reference) to the note being disliked.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

16
app/extensions/migration/page.mdx
View file

@ -40,11 +40,11 @@ Migration happens in three steps:
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:migration/Migration`. Must be `pub.versia:migration/Migration`.
</Property> </Property>
<Property name="author" type="URI" typeLink="/types#uri" required={true}> <Property name="author" type="Reference" typeLink="/types#reference" required={true}>
URI of the [User](/entities/user) who is migrating. [Reference](/types#reference) to the [User](/entities/user) who is migrating.
</Property> </Property>
<Property name="destination" type="URI" required={true} typeLink="/types#uri"> <Property name="destination" type="Reference" required={true} typeLink="/types#reference">
URI of the destination [User](/entities/user) on the new instance. [Reference](/types#reference) to the destination [User](/entities/user) on the new instance.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>
@ -71,11 +71,11 @@ The following extensions to [User](/entities/user) are used by the migration ext
<Row> <Row>
<Col> <Col>
<Properties name="MigrationExtension"> <Properties name="MigrationExtension">
<Property name="previous" type="URI" required={true} typeLink="/types#uri"> <Property name="previous" type="Reference" required={true} typeLink="/types#reference">
If this user has migrated from another instance, this property **MUST** be set to the URI of the user on the previous instance. If this user has migrated from another instance, this property **MUST** be a [Reference](/types#reference) to the user on the previous instance.
</Property> </Property>
<Property name="new" type="URI" required={false} typeLink="/types#uri"> <Property name="new" type="Reference" required={false} typeLink="/types#reference">
If this user has migrated to another instance, this property **MUST** be set to the URI of the user on the new instance. If this user has migrated to another instance, this property **MUST** be a [Reference](/types#reference) to the URI of the user on the new instance.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

8
app/extensions/polls/page.mdx
View file

@ -97,11 +97,11 @@ If a vote is cast to a poll that is closed, the vote should be rejected with a `
<Property name="type" type="string" required="true"> <Property name="type" type="string" required="true">
Must be `pub.versia:polls/Vote`. Must be `pub.versia:polls/Vote`.
</Property> </Property>
<Property name="author" type="URI" required="true" typeLink="/types#uri"> <Property name="author" type="Reference" required="true" typeLink="/types#reference">
URI to the user who cast the vote. [Reference](/types#reference) of the user who cast the vote.
</Property> </Property>
<Property name="poll" type="URI" required="true" typeLink="/types#uri"> <Property name="poll" type="Reference" required="true" typeLink="/types#reference">
URI to the poll that the user voted on. Must link to a [Note](/entities/note) with a valid poll. [Reference](/types#reference) to the note with poll that the user voted on.
</Property> </Property>
<Property name="option" type="number" required="true" numberType="u64"> <Property name="option" type="number" required="true" numberType="u64">
Index of the option that the user voted for. This should be a valid index into the `options` array of the poll. Index of the option that the user voted for. This should be a valid index into the `options` array of the poll.

8
app/extensions/reactions/page.mdx
View file

@ -19,11 +19,11 @@ User reactions are (like every other entity) federated to all followers, and can
<Property name="type" type="string" required> <Property name="type" type="string" required>
Must be `pub.versia:reactions/Reaction`. Must be `pub.versia:reactions/Reaction`.
</Property> </Property>
<Property name="author" type="URI" required typeLink="/types#uri"> <Property name="author" type="Reference" required typeLink="/types#reference">
URI of the [User](/entities/user) that is reacting. [Reference](/types#reference) to the [User](/entities/user) that is reacting.
</Property> </Property>
<Property name="object" type="URI" required typeLink="/types#uri"> <Property name="object" type="Reference" required typeLink="/types#reference">
URI of the [Note](/entities/note) attached to the reaction. [Reference](/types#reference) to the [Note](/entities/note) attached to the reaction.
</Property> </Property>
<Property name="content" type="string" required> <Property name="content" type="string" required>
Emoji content of reaction. May also be arbitrary text, or [Custom Emoji](/extensions/custom-emojis) if supported. Emoji content of reaction. May also be arbitrary text, or [Custom Emoji](/extensions/custom-emojis) if supported.

8
app/extensions/reports/page.mdx
View file

@ -21,11 +21,11 @@ When an instance receives a report, it *should* be reviewed by a moderator or ad
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:reports/Report`. Must be `pub.versia:reports/Report`.
</Property> </Property>
<Property name="author" type="URI" required={false} typeLink="/types#uri"> <Property name="author" type="Reference" required={false} typeLink="/types#reference">
URI of the reporting [User](/entities/user). Optional if the report is anonymous. [Reference](/types#reference) to the reporting [User](/entities/user). Optional if the report is anonymous.
</Property> </Property>
<Property name="reported" type="URI[]" required={true} typeLink="/types#uri"> <Property name="reported" type="Reference[]" required={true} typeLink="/types#reference">
URIs of the content being reported. [References](/types#reference) to the content being reported.
</Property> </Property>
<Property name="tags" type="string[]" required={true}> <Property name="tags" type="string[]" required={true}>
Report tags. Should be concise and clear, such as `spam`, `harassment`, `misinformation`, etc. Used for categorization. Report tags. Should be concise and clear, such as `spam`, `harassment`, `misinformation`, etc. Used for categorization.

8
app/extensions/share/page.mdx
View file

@ -21,11 +21,11 @@ When a user shares a note, the note's original author **must** receive the entit
<Property name="type" type="string" required={true}> <Property name="type" type="string" required={true}>
Must be `pub.versia:share/Share`. Must be `pub.versia:share/Share`.
</Property> </Property>
<Property name="author" type="URI" required={true} typeLink="/types#uri"> <Property name="author" type="Reference" required={true} typeLink="/types#referece">
Creator of the Share. [Reference](/types#reference) to the creator of the Share.
</Property> </Property>
<Property name="shared" type="URI" required={true} typeLink="/types#uri"> <Property name="shared" type="Reference" required={true} typeLink="/types#reference">
URI of the note being shared. Must link to a [Note](/entities/note). [Reference](/types#reference) to the note being shared.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

4
app/extensions/vanity/page.mdx
View file

@ -72,8 +72,8 @@ All properties are optional.
<Property name="timezone" type="string" required={false}> <Property name="timezone" type="string" required={false}>
User's timezone. Should be a valid [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string. User's timezone. Should be a valid [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string.
</Property> </Property>
<Property name="aliases" type="URI[]" required={false} typeLink="/types#uri"> <Property name="aliases" type="References[]" required={false} typeLink="/types#reference">
Versia profiles that should be considered aliases of this profile. [References](/types#reference) to Versia profiles that should be considered aliases (or "alt accounts") of this profile.
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

12
app/structures/collection/page.mdx
View file

@ -16,8 +16,8 @@ Collections are a way to represent paginated groups of entities. They are used e
<Row> <Row>
<Col> <Col>
<Properties name="Collection"> <Properties name="Collection">
<Property name="author" type="URI | null" required={true} typeLink="/types#uri"> <Property name="author" type="Reference | null" required={true} typeLink="/types#reference">
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). [Reference](/types#reference) to the 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>
<Property name="total" type="number" required={true} numberType="u64"> <Property name="total" type="number" required={true} numberType="u64">
Total number of entities in the collection, across all pages. Total number of entities in the collection, across all pages.
@ -64,14 +64,14 @@ URI Collections are identical to regular collections, but they contain only URIs
<Row> <Row>
<Col> <Col>
<Properties name="URICollection"> <Properties name="URICollection">
<Property name="author" type="URI | null" required={true} typeLink="/types#uri"> <Property name="author" type="Reference | null" required={true} typeLink="/types#reference">
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). [Reference](/types#reference) to the 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>
<Property name="total" type="number" required={true} numberType="u64"> <Property name="total" type="number" required={true} numberType="u64">
Total number of entities in the collection, across all pages. Total number of entities in the collection, across all pages.
</Property> </Property>
<Property name="items" type="URI[]" required={true}> <Property name="items" type="Reference[]" required={true}>
Collection contents. Must be an array of URIs. Collection contents. Must be an array of [References](/types#reference).
</Property> </Property>
</Properties> </Properties>
</Col> </Col>

47
app/types/page.mdx
View file

@ -1,3 +1,50 @@
## Reference
```typescript
type Hostname = string;
type Id = Entity["id"];
type Reference = `${Hostname}:${Id}` | `${Id}`;
```
A **reference** is a way to refer to any entity within the Versia network. It is a string composed of the following parts:
- The entity's instance's hostname. Optional if that same instance is the creator of the entity.
- Punycode encoding is used for internationalized domain names (IDNs).
- Example: `example.com`, `example.com:3000`, `xn--ls8h.xn--ls8h`.
- A colon (`:`) separator, if the hostname is present.
- The entity's unique identifier. This is the `id` property of the entity.
<Warning>
If the hostname is an IPv6 address, it must be enclosed in square brackets.
For example: `[2001:db8::1]:3000`.
</Warning>
### Examples
These two examples are equivalent if the instance is `example.com`:
```jsonc
{
"type": "Follow",
"id": "3e7e4750-afd4-4d99-a256-02f0710a0520",
"author": "6e0204a2-746c-4972-8602-c4f37fc63bbe", // [!code focus]
"created_at": "2021-01-01T00:00:00.000Z",
"followee": "test.org:02e1e3b2-cb1f-4e4a-b82e-98866bee5de7"
}
```
```jsonc
{
"type": "Follow",
"id": "3e7e4750-afd4-4d99-a256-02f0710a0520",
"author": "example.com:6e0204a2-746c-4972-8602-c4f37fc63bbe", // [!code focus]
"created_at": "2021-01-01T00:00:00.000Z",
"followee": "test.org:02e1e3b2-cb1f-4e4a-b82e-98866bee5de7"
}
```
## RFC3339 ## RFC3339