mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
93 lines
4.1 KiB
Plaintext
93 lines
4.1 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. 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' }}
|
|
|
|
## Entity 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 omitted or set to `null`.
|
|
|
|
<Row>
|
|
<Col>
|
|
|
|
<Properties>
|
|
<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="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.
|
|
</Note>
|
|
</Property>
|
|
<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.**
|
|
</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": "9a8928b6-2526-4979-aab1-ef2f88cd5700",
|
|
"type": "Delete",
|
|
"created_at": "2022-01-01T12:00:00Z",
|
|
"author": "https://bongo.social/users/63a00ab3-39b1-49eb-b88e-ed65d2361f3e",
|
|
"deleted_type": "Note",
|
|
"deleted": "https://bongo.social/notes/54059ce2-9332-46fa-bf6a-598b5493b81b",
|
|
}
|
|
```
|
|
|
|
```jsonc {{ 'title': 'With Extensions' }}
|
|
{
|
|
"id": "f0aacf0b-df7a-4ee5-a2ba-6c4acafd8642",
|
|
"type": "org.space:Zlorbs/Zlorb",
|
|
"created_at": "2023-04-13T08:00:00Z",
|
|
"uri": "https://space.org/zlorbs/f0aacf0b-df7a-4ee5-a2ba-6c4acafd8642",
|
|
"extensions": { // [!code focus:100]
|
|
"org.space:zlorbs": {
|
|
"zlorb_type": "giant",
|
|
"zlorb_size": "huge"
|
|
},
|
|
"pub.versia:location": {
|
|
"latitude": 37.7749,
|
|
"longitude": -122.4194
|
|
}
|
|
}
|
|
}
|
|
```
|
|
</Col>
|
|
</Row>
|
|
|
|
## 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 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). |