mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 14:28:20 +01:00
94 lines
3.9 KiB
Plaintext
94 lines
3.9 KiB
Plaintext
export const metadata = {
|
|
title: 'Entities',
|
|
description:
|
|
'Entities are simple JSON objects that represent the core data structures in Versia.',
|
|
}
|
|
|
|
# Entities
|
|
|
|
Entities are the foundation of the Versia protocol. They are similar to: {{ className: 'lead' }}
|
|
|
|
- [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.
|
|
|
|
Any field in an entity not marked as `required` may be set to `null`. These fields **must not** be omitted: they must be present with a `null` value if not set.
|
|
|
|
<Row>
|
|
<Col>
|
|
|
|
<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 with the following character sets:
|
|
|
|
- `a-z`
|
|
- `A-Z`
|
|
- `0-9`
|
|
- `-`, `_`
|
|
|
|
Not present on [Transient Entities](#transient-entities).
|
|
</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="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. 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}>
|
|
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.
|
|
|
|
Each custom property must be namespaced with the organization's reversed domain name, followed by the property name. Extensions should be used sparingly and only when necessary.
|
|
</Property>
|
|
</Properties>
|
|
</Col>
|
|
<Col sticky>
|
|
|
|
```jsonc {{ 'title': 'Example Entity' }}
|
|
{
|
|
"id": "3e7e4750-afd4-4d99-a256-02f0710a0520",
|
|
"type": "pub.versia:likes/Like",
|
|
"created_at": "2021-01-01T00:00:00.000Z",
|
|
"author": "6e0204a2-746c-4972-8602-c4f37fc63bbe",
|
|
"liked": "otherexample.org:fmKZ763jzIU8"
|
|
}
|
|
```
|
|
|
|
```jsonc {{ 'title': 'With Extensions' }}
|
|
{
|
|
"id": "f0aacf0b-df7a-4ee5-a2ba-6c4acafd8642",
|
|
"type": "org.space:Zlorbs/Zlorb",
|
|
"created_at": "2023-04-13T08:00:00Z",
|
|
"extensions": { // [!code focus:100]
|
|
"org.space:zlorbs": {
|
|
"zlorb_type": "giant",
|
|
"zlorb_size": "huge"
|
|
},
|
|
"pub.versia:location": {
|
|
"latitude": 37.7749,
|
|
"longitude": -122.4194
|
|
}
|
|
}
|
|
}
|
|
```
|
|
</Col>
|
|
</Row>
|
|
|
|
## Transient Entities
|
|
|
|
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. |