1.. _rfc-conformance: 2 3*************** 4RFC Conformance 5*************** 6 7JSON is specified in :rfc:`4627`, *"The application/json Media Type 8for JavaScript Object Notation (JSON)"*. 9 10Character Encoding 11================== 12 13Jansson only supports UTF-8 encoded JSON texts. It does not support or 14auto-detect any of the other encodings mentioned in the RFC, namely 15UTF-16LE, UTF-16BE, UTF-32LE or UTF-32BE. Pure ASCII is supported, as 16it's a subset of UTF-8. 17 18Strings 19======= 20 21JSON strings are mapped to C-style null-terminated character arrays, 22and UTF-8 encoding is used internally. 23 24All Unicode codepoints U+0000 through U+10FFFF are allowed in string 25values. However, U+0000 is not allowed in object keys because of API 26restrictions. 27 28Unicode normalization or any other transformation is never performed 29on any strings (string values or object keys). When checking for 30equivalence of strings or object keys, the comparison is performed 31byte by byte between the original UTF-8 representations of the 32strings. 33 34Numbers 35======= 36 37.. _real-vs-integer: 38 39Real vs. Integer 40---------------- 41 42JSON makes no distinction between real and integer numbers; Jansson 43does. Real numbers are mapped to the ``double`` type and integers to 44the ``json_int_t`` type, which is a typedef of ``long long`` or 45``long``, depending on whether ``long long`` is supported by your 46compiler or not. 47 48A JSON number is considered to be a real number if its lexical 49representation includes one of ``e``, ``E``, or ``.``; regardless if 50its actual numeric value is a true integer (e.g., all of ``1E6``, 51``3.0``, ``400E-2``, and ``3.14E3`` are mathematical integers, but 52will be treated as real values). With the ``JSON_DECODE_INT_AS_REAL`` 53decoder flag set all numbers are interpreted as real. 54 55All other JSON numbers are considered integers. 56 57When encoding to JSON, real values are always represented 58with a fractional part; e.g., the ``double`` value 3.0 will be 59represented in JSON as ``3.0``, not ``3``. 60 61Overflow, Underflow & Precision 62------------------------------- 63 64Real numbers whose absolute values are too small to be represented in 65a C ``double`` will be silently estimated with 0.0. Thus, depending on 66platform, JSON numbers very close to zero such as 1E-999 may result in 670.0. 68 69Real numbers whose absolute values are too large to be represented in 70a C ``double`` will result in an overflow error (a JSON decoding 71error). Thus, depending on platform, JSON numbers like 1E+999 or 72-1E+999 may result in a parsing error. 73 74Likewise, integer numbers whose absolute values are too large to be 75represented in the ``json_int_t`` type (see above) will result in an 76overflow error (a JSON decoding error). Thus, depending on platform, 77JSON numbers like 1000000000000000 may result in parsing error. 78 79Parsing JSON real numbers may result in a loss of precision. As long 80as overflow does not occur (i.e. a total loss of precision), the 81rounded approximate value is silently used. Thus the JSON number 821.000000000000000005 may, depending on platform, result in the 83``double`` value 1.0. 84 85Signed zeros 86------------ 87 88JSON makes no statement about what a number means; however Javascript 89(ECMAscript) does state that +0.0 and -0.0 must be treated as being 90distinct values, i.e. -0.0 |not-equal| 0.0. Jansson relies on the 91underlying floating point library in the C environment in which it is 92compiled. Therefore it is platform-dependent whether 0.0 and -0.0 will 93be distinct values. Most platforms that use the IEEE 754 94floating-point standard will support signed zeros. 95 96Note that this only applies to floating-point; neither JSON, C, or 97IEEE support the concept of signed integer zeros. 98 99.. |not-equal| unicode:: U+2260 100 101Types 102----- 103 104No support is provided in Jansson for any C numeric types other than 105``json_int_t`` and ``double``. This excludes things such as unsigned 106types, ``long double``, etc. Obviously, shorter types like ``short``, 107``int``, ``long`` (if ``json_int_t`` is ``long long``) and ``float`` 108are implicitly handled via the ordinary C type coercion rules (subject 109to overflow semantics). Also, no support or hooks are provided for any 110supplemental "bignum" type add-on packages. 111