mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
119 lines
2.8 KiB
Plaintext
119 lines
2.8 KiB
Plaintext
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. |