Skip to content

Latest commit

 

History

History
93 lines (74 loc) · 4.07 KB

JSON.md

File metadata and controls

93 lines (74 loc) · 4.07 KB
Raw

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 141 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 JSON2 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 46483.
  • 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.

Bencodex type JSON type
Null (n) Null (null)
Boolean (t, f) Boolean (true, false)
Byte string See Prefixes
Unicode string See Prefixes
Integer (i–e) See 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 ("The JSON Object") of ECMAScript 5.14.

The ordering of object keys MUST be ignored and reordered as Bencodex specifies.

Footnotes

  1. Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, http://www.rfc-editor.org/info/rfc2119. ↩

  2. Ecma International, "ECMAScript Language Specification, 5.1 Edition", ECMA Standard 262, June 2011, http://www.ecma-international.org/ecma-262/5.1/ECMA-262.pdf. ↩

  3. Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, https://www.rfc-editor.org/info/rfc4648. ↩

  4. Ecma International, "The JSON Data Interchange Format", Standard ECMA-404, http://www.ecma-international.org/publications/standards/Ecma-404.htm. ↩