9 JSON Output Method

The JSON output method serializes the instance of the data model as a JSON value using the JSON syntax defined in [RFC 7159]. Sequence normalization is not performed for this output method.

[Definition: Whenever a value is serialized to a JSON string, the following procedure is applied to the supplied string:

  1. Any character in the string for which character mapping is defined (see 11 Character Maps) is substituted by the replacement string defined in the character map.

  2. Any other character in the input string (but not a character produced by character mapping) is a candidate for Unicode Normalization if requested by the normalization-form parameter, and JSON escaping. JSON escaping replaces the characters quotation mark, backspace, form-feed, newline, carriage return, tab, reverse solidus, or solidus by the corresponding JSON escape sequences \", \b, \f, \n, \r, \t, \\, or \/ respectively, and any other codepoint in the range 1-31 or 127-159 by an escape in the form \uHHHH where HHHH is the hexadecimal representation of the codepoint value. Escaping is also applied to any characters that cannot be represented in the selected encoding.

  3. The resulting string is enclosed in double quotation marks.

]

Finally, encoding, as controlled by the encoding parameter, converts the character stream produced by the preceding rules into an octet stream.

9.1 The Influence of Serialization Parameters upon the JSON Output Method

When nodes are serialized using the JSON output method, serialization is delegated to the output method specified by the json-node-output-method serialization parameter. The omit-xml-declaration parameter is set to yes, and no other serialization parameters are passed down to the serialization method responsible for serializing the node.

9.1.1 JSON Output Method: the version Parameter

The version parameter is not applicable to the JSON output method.

9.1.2 JSON Output Method: the html-version Parameter

The html-version parameter is not applicable to the JSON output method.

9.1.3 JSON Output Method: the encoding Parameter

The encoding parameter identifies the encoding that the JSON output method MUST use to convert sequences of characters to sequences of bytes. Serializers are REQUIRED to support values of UTF-8 and UTF-16. A serialization error [err:SESU0007] occurs if the serializer does not support the encoding specified by the encoding parameter. The serializer MUST signal the error. If the instance of the data model contains a character that cannot be represented in the encoding that the serializer is using for output, the serializer MUST signal a serialization error [err:SERE0008].

Note:

If an encoding other than UTF-8, UTF-16, UTF-32, US-ASCII, or an equivalent is specified for the encoding parameter, the output will (except in unusual circumstances) fail to conform to the definition of JSON in [RFC 7159].

9.1.4 JSON Output Method: the indent and suppress-indentation Parameters

The indent parameter controls whether the serializer adjusts the whitespace in the serialized result so that a person will find it easier to read. If the indent parameter has one of the values yes, true or 1, the serializer MAY output additional whitespace characters adjacent to the JSON structural tokens. If the indent parameter has the value no, false or 0, the serializer MUST output no whitespace characters adjacent to the JSON structural tokens.

The suppress-indentation parameter is not applicable to the JSON output method.

9.1.5 JSON Output Method: the cdata-section-elements Parameter

The cdata-section-elements parameter is not applicable to the JSON output method.

9.1.6 JSON Output Method: the omit-xml-declaration and standalone Parameters

The omit-xml-declaration and standalone parameters are not applicable to the JSON output method.

9.1.7 JSON Output Method: the doctype-system and doctype-public Parameters

The doctype-system and doctype-public parameters are not applicable to the JSON output method.

9.1.8 JSON Output Method: the undeclare-prefixes Parameter

The undeclare-prefixes parameter is not applicable to the JSON output method.

9.1.9 JSON Output Method: the normalization-form Parameter

The normalization-form parameter is applicable to the JSON output method. The values NFC and none MUST be supported by the serializer. A serialization error [err:SESU0011] results if the value of the normalization-form parameter specifies a normalization form that is not supported by the serializer; the serializer MUST signal the error.

9.1.10 JSON Output Method: the media-type Parameter

The media-type parameter is applicable to the JSON output method. See 3 Serialization Parameters for more information.

9.1.11 JSON Output Method: the use-character-maps Parameter

The use-character-maps parameter is applicable to the JSON output method. See 11 Character Maps for more information.

9.1.12 JSON Output Method: the byte-order-mark Parameter

The byte-order-mark parameter is applicable to the JSON output method. See 3 Serialization Parameters for more information.

Note:

Serialized output containing a byte-order mark does not conform to the definition of JSON in [RFC 7159] (although conforming JSON parsers are allowed to tolerate the byte-order mark).

9.1.13 JSON Output Method: the escape-uri-attributes Parameter

The escape-uri-attributes parameter is not applicable to the JSON output method.

9.1.14 JSON Output Method: the include-content-type Parameter

The include-content-type parameter is not applicable to the JSON output method.

9.1.15 JSON Output Method: the item-separator Parameter

The item-separator serialization parameter is not applicable to the JSON output method.

9.1.16 JSON Output Method: the allow-duplicate-names Parameter

The allow-duplicate-names serialization parameter determines whether the presence of multiple keys in a map item with the same string value (e.g. the date 2014-10-01 and the string "2014-10-01") will or will not raise serialization error [err:SERE0022]. If the value is one of, yes, true or 1, such duplicate keys will result in duplicate object-member names in the JSON output and no error will be raised because of the duplicate names. If the value is no, false or 0, such duplicate keys are an error ([err:SERE0022]).

9.1.17 JSON Output Method: the json-node-output-method Parameter

The json-node-output-method serialization parameter determines how a node in the data model instance gets converted to a JSON value. If the value is one of xml, xhtml, html or text, then the node is converted to a JSON string by serializing the node using the output method specified by this parameter. If the value is xml or xhtml then the node is serialised with the additional serialization parameter omit-xml-declaration set to yes.