# JSON

The JSON rules that every Versia message follows.

All JSON in the Versia protocol **MUST** be an [I-JSON message](https://datatracker.ietf.org/doc/html/rfc7493), a restricted profile of JSON. Messages are [signed](/signatures) as the exact bytes sent, so there is no canonical form to follow.

## Encoding

All JSON data **MUST** be encoded in UTF-8. This is the only encoding supported by the Versia protocol. As I-JSON requires, keys and string values **MUST NOT** contain surrogate or noncharacter code points.

Line breaks inside string values **MUST** be Unix-style `\n` (LF), not Windows-style `\r\n` (CRLF). A receiver **MUST** treat an entity with a `\r\n` inside a string value as [invalid](/validation). There is no rule on whitespace between JSON tokens.

## Keys

Keys **MUST NOT** be empty. Senders **MUST NOT** send an object with duplicate keys.

Which keys an object can have depends on the object:

- Entity and structure fields use the names listed in this specification. Receivers [ignore any others](/validation#unknown-fields-and-types).
- Extension keys follow [Extension Naming](/extensions#naming).
- Any other map documents its own keys where it is defined.

## Values

### Numbers

Numbers **SHOULD NOT** have greater magnitude or precision than an IEEE 754 double-precision number. Any form that JSON allows is valid, including `1.0` and `1e3`.

Numeric fields state their type:

- `integer`: a whole number from 0 to 2⁵³-1 (`9007199254740991`), in any form, so `1000`, `1000.0` and `1e3` are all valid. Other values **MUST NOT** be sent, and [fail validation](/validation).
- `float`: an IEEE 754 double-precision number.

### Optional Fields

Fields that are not marked as **required** are optional. Omitting a field and setting it to `null` mean the same thing. Senders **SHOULD** omit the field, and receivers **MUST** accept both.