mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
73 lines
1.7 KiB
Plaintext
73 lines
1.7 KiB
Plaintext
## 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",
|
|
"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",
|
|
"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
|
|
|
|
[https://datatracker.ietf.org/doc/html/rfc3339](https://datatracker.ietf.org/doc/html/rfc3339)
|
|
|
|
## UUID
|
|
|
|
```typescript
|
|
type UUID = `${number}-${number}-${number}-${number}-${number}`;
|
|
```
|
|
|
|
## URI
|
|
|
|
```typescript
|
|
type URI = string;
|
|
```
|
|
|
|
## Extensions
|
|
|
|
```typescript
|
|
type OrgNamespace = string;
|
|
type ExtensionName = string;
|
|
|
|
type ExtensionsKey = `${OrgNamespace}:${ExtensionName}`;
|
|
|
|
type Extensions = {
|
|
[key in ExtensionsKey]: any;
|
|
}
|
|
``` |