Bencodex JSON Representation
===========================
Introduction
------------
Bencodex JSON Representation is a standard way to represent a given Bencodex
value to a valid JSON value to be interchanged.
This specification defines a standard way to represent a Bencodex value to (a
subset of) JSON and how to decode/encode them.
Note that this specification is a separate specification from Bencodex itself.
Bencodex implementations are not required to implement this specification.
### Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14[^RFC-2119] when, and only
when, they appear in all capitals, as shown here.
Prefixes
--------
Bencodex JSON Representation defines a set of prefixes that **SHALL** be used
for JSON[^JSON] string value to denote a corresponding Bencodex type. The
defined prefixes are following:
- `0x` denotes a hexadecimal byte string. The rest of the string **SHOULD** be
parsed as a byte-string encoded in hexadecimal.
- The hexadecimal byte string **SHOULD NOT** contain any upper letters.
- The casing of the value **SHOULD** be ignored.
- `U+FEFF BYTE ORDER MARK` denotes a Unicode string. The rest of the string
**MUST** be parsed as a Unicode string.
- `b64:` denotes a base64-encoded byte string. The rest of the string **MUST**
be parsed as a byte string encoded in base64 as defined in
[RFC 4648](https://www.rfc-editor.org/rfc/rfc4648.html).
- In case no prefixes mentioned above are found, the value of the string
**MUST** be parsed as an integer.
- Any non-digit character in the string **SHOULD** result in an error, except
minus sign at the start of the string which denotes negative integer.
If the JSON string value contains escaped Unicode code points (denoted using
`\u`) they **SHOULD** be interpreted before identifying a prefix.
Encoding to JSON
----------------
When encoding a given value to JSON, the value **MUST** be encoded as specified
in the following table.
| Null (`n`) | Null (`null`) |
| Boolean (`t`, `f`) | Boolean (`true`, `false`) |
| Byte string | See [Prefixes](#prefixes) |
| Unicode string | See [Prefixes](#prefixes) |
| Integer (`i`–`e`) | See [Prefixes](#prefixes) |
| Lists (`l`–`e`) | Array (`[]`) |
| Dictionary | Object (`{}`) |
When encoding a dictionary value to a JSON object, the resulting object
**SHOULD** have the same key order as Bencodex specifies.
When encoding a byte string, an implementation **MAY** choose which encoding to
use depending on the length of the value.
Decoding to Bencodex
--------------------
When decoding a given JSON to Bencodex, the duplicate keys of the JSON object
**SHOULD** result in failure of the decoding. In case if this is not desirable,
the implementation **MAY** use the lexically last key-value pair as specified
in [Section 15.12](https://www.ecma-international.org/ecma-262/5.1/ECMA-262.pdf)
("The JSON Object") of ECMAScript 5.1[^ECMAScript].
The ordering of object keys **MUST** be ignored and reordered as Bencodex
specifies.