mirror of
https://github.com/versia-pub/docs.git
synced 2026-03-13 10:59:16 +01:00
docs: ♻️ Rewrite various docs pages, add null fields everywhere they were missing, make some Note and User fields mandatory
This commit is contained in:
parent
e6f7a27d3e
commit
e9b5ccd76c
31 changed files with 412 additions and 148 deletions
119
app/json/page.mdx
Normal file
119
app/json/page.mdx
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
export const metadata = {
|
||||
title: 'JSON',
|
||||
description:
|
||||
'Guidelines on JSON handling and serialization',
|
||||
}
|
||||
|
||||
# JSON
|
||||
|
||||
Identical data structures can be represented in many different ways in JSON. This document describes the rules that must be followed when using JSON in the Versia protocol.
|
||||
|
||||
## Encoding
|
||||
|
||||
All JSON data **must** be encoded in UTF-8. This is the only encoding supported by the Versia protocol.
|
||||
|
||||
Line endings must be in Unix-style `\n` (LF) format. The use of Windows-style `\r\n` (CRLF) line endings is not allowed.
|
||||
|
||||
## Keys
|
||||
|
||||
Keys in JSON must be strings, cannot be empty, and may only contain the following characters:
|
||||
- `a-z`
|
||||
- `A-Z`
|
||||
- `0-9`
|
||||
- `-`, `_`, `.`, `#`, `/`, `:`
|
||||
|
||||
Duplicate keys are **not** allowed.
|
||||
|
||||
``` json {{ "title": "Valid Keys" }}
|
||||
{
|
||||
"valid-key": "value",
|
||||
"valid_key": "value",
|
||||
"valid.key": "value",
|
||||
"valid#key": "value",
|
||||
"valid/key": "value",
|
||||
"valid:key": "value"
|
||||
}
|
||||
```
|
||||
|
||||
```json {{ "title": "Invalid Keys" }}
|
||||
{
|
||||
"invalid key": "value", // ❌️ Invalid: space is not allowed
|
||||
"invalid@key": "value", // ❌️ Invalid: @ is not allowed
|
||||
"": "value", // ❌️ Invalid: empty key is not allowed
|
||||
9: "value", // ❌️ How did you even serialize this??
|
||||
}
|
||||
```
|
||||
|
||||
## Values
|
||||
|
||||
### Numbers
|
||||
|
||||
Numbers in JSON must be represented as decimal numbers. They can be integers or floating-point numbers, but must follow the following rules:
|
||||
|
||||
```json {{ "title": "Must not use scientific notation" }}
|
||||
{
|
||||
"value": 1e3, // ❌️ Invalid
|
||||
"value2": 1000 // ✅ Valid
|
||||
}
|
||||
```
|
||||
|
||||
```json {{ "title": "Must not have leading zeros" }}
|
||||
{
|
||||
"value": 01, // ❌️ Invalid
|
||||
"value2": 1 // ✅ Valid
|
||||
}
|
||||
```
|
||||
|
||||
```json {{ "title": "Must not have trailing decimal points" }}
|
||||
{
|
||||
"value": 1., // ❌️ Invalid
|
||||
"value2": 1 // ✅ Valid
|
||||
}
|
||||
```
|
||||
|
||||
```json {{ "title": "Must not have trailing zeros after the decimal point" }}
|
||||
{
|
||||
"value": 1.00, // ❌️ Invalid
|
||||
"value2": 1.0, // ❌️ Invalid
|
||||
"value3": 1 // ✅ Valid
|
||||
}
|
||||
```
|
||||
|
||||
```json {{ "title": "Must not have leading decimal points" }}
|
||||
{
|
||||
"value": .1, // ❌️ Invalid
|
||||
"value2": 0.1 // ✅ Valid
|
||||
}
|
||||
```
|
||||
|
||||
```json {{ "title": "Must not use numbers outside the range -2⁵³ to 2⁵³ (included)." }}
|
||||
{
|
||||
"value": 18014398509481984, // ❌️ Invalid
|
||||
"value2": -20873930 // ✅ Valid
|
||||
}
|
||||
```
|
||||
|
||||
```json {{ "title": "Must not use the negative zero" }}
|
||||
{
|
||||
"value": -0, // ❌️ Invalid
|
||||
"value2": 0 // ✅ Valid
|
||||
}
|
||||
```
|
||||
|
||||
```json {{ "title": "Must not use Infinity or NaN" }}
|
||||
{
|
||||
"value": Infinity, // ❌️ Invalid
|
||||
"value2": NaN // ❌️ Invalid
|
||||
}
|
||||
```
|
||||
|
||||
```json {{ "title": "Must not use hexadecimal or octal notation" }}
|
||||
{
|
||||
"value": 0x1A, // ❌️ Invalid
|
||||
"value2": 0o17 // ❌️ Invalid
|
||||
}
|
||||
```
|
||||
|
||||
### Optional Fields
|
||||
|
||||
Fields that are 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue