Any JSON value (object, array, string, number, boolean, null) is accepted at the top level, as permitted by RFC 8259.
Encoding (ooRexx → JSON):
nulltrue / falseDecoding (JSON → ooRexx):
\uXXXX handling: Since ooRexx has no native Unicode support,
\u00XX sequences are decoded to the corresponding single-byte
character. Non-\u00XX sequences (e.g. \u4E16)
are kept as literal \uXXXX text. During encoding, any
literal \uXXXX pattern already present in a source string
is passed through unchanged. This means a Rexx string containing the
six characters \u0041 will encode as \u0041
(decoded as A by a JSON consumer), rather than escaping
the backslash. This is a deliberate trade-off for ooRexx environments
where \uXXXX sequences are used to represent Unicode characters that
cannot be stored natively.
Example:
json = .json~new
doc = json~fromJSON('{"name": "Alice", "age": 30, "active": true}')
say doc["name"] -- Alice
say doc["age"] -- 30
say doc["active"] -- 1 (a JsonBoolean singleton)
say .json~toJSON(doc) -- {"active":true,"age":30,"name":"Alice"}
::requires "json.cls"
*/
::class "JSON" public
/** Returns the .JsonBoolean proxy for .true, which ensures a proper JSON encoding.
It can be used interchangeably with ooRexx' .true or 1 values.
@return the .JsonBoolean value for .true
*/
::attribute true get class unguarded
return .jsonBoolean~true
/** Returns the .JsonBoolean proxy for .false, which ensures a proper JSON encoding.
It can be used interchangeably with ooRexx' .false or 0 values.
@return the .JsonBoolean value for .false
*/
::attribute false get class unguarded
return .jsonBoolean~false
/**
* Constructor, initializes the instance.
*/
::method init
expose eJS uJS ctrl crlf
use strict arg -- no arguments allowed
eJS = .directory~new() -- escape table: character -> JSON escape sequence
eJS['08'x] = '\b'
eJS['09'x] = '\t'
eJS['0A'x] = '\n'
eJS['0C'x] = '\f'
eJS['0D'x] = '\r'
eJS['"'] = '\"'
eJS['\'] = '\\'
eJS['/'] = '\/'
uJS = .directory~new() -- unescape table: JSON escape sequence -> character
do index over eJS
uJS[eJS[index]] = index
end
-- chars that end a value
ctrl = .Set~of(' ', '}', ']', ',', '09'x, '0a'x, '0d'x)
crlf = .rexxInfo~endOfLine -- get the platform's endOfLine character(s)
-- Store in package-local variables so the string2json routine can access them
pkgLocal=.context~package~local
pkgLocal~js.eJS = eJS
pkgLocal~js.uJS = uJS
pkgLocal~js.ctrl = ctrl
pkgLocal~js.crlf = crlf
/* ========================================================================== */
/* Public API methods */
/* ========================================================================== */
/** Utility class method to ease reading JSON files into an ooRexx object.
*
Example:
rexxObject = .json~fromJsonFile('some.json')
*
* @param fn file name or file object to read JSON data from
*
* @return rexxObject ooRexx object representing the JSON text
*/
::method fromJsonFile class
use strict arg fn
s=.stream~new(fn)~~open("read") -- open stream for reading
jsonText=s~charin(1,s~chars) -- read all chars, close stream
s~close
json=self~new -- create json instance
return json~fromJson(jsonText) -- use it to create ooRexx representation
/** Utility class method to ease creating minimized JSON files from an ooRexx object.
* If a legible (with ignorable whitespace to ease reading for humans) JSON file
* is desired instead, supply .true as the third argument.
*
Example:
.json~toJsonFile('some.json',someRexxObject)
*
* @param fn file name or file object to write produced JSON text to
* @param rexxObject rexxObject to encode as JSON
* @param isLegible optional logical value, defaults to .false (create minimized JSON string)
*
*/
::method toJsonFile class
use strict arg fn, rexxObject, legible=.false
if arg()=3 then -- check supplied argument
.Validate~logical("legible",legible) -- test for logical value 0 or 1
json=self~new -- create json instance
jsonText=json~toJSON(rexxObject, legible) -- create JSON text representing the rexxObject
-- open stream for writing, delete existing file, if any, write json text to it
.stream~new(fn)~~open("write replace")~~charout(jsonText)~~close
::method toJSON class unguarded -- make available via class object
j=self~new -- create JSON instance
forward to (j) -- forward message to JSON instance
::method fromJSON class unguarded -- make available via class object
j=self~new -- create JSON instance
forward to (j) -- forward message to JSON instance
/** Serialises an ooRexx object tree to XML conforming to either
* json.xsd (with namespace) or json.dtd
* (with DOCTYPE).
*
* @param obj the ooRexx object tree to serialise
* @param schema optional schema type: "xsd" (default) or
* "dtd"
* @return a well-formed XML string
* @see JsonXmlEmitter
* @see JsonXmlParser
*/
::method jsonToXml class
use strict arg obj, schema = "xsd"
return .JsonXmlEmitter~new(schema)~emit(obj)
/** Serialises an ooRexx object tree to XML and writes it to a file.
*
* @param obj the ooRexx object tree to serialise
* @param path the file system path to write
* @param schema optional schema type: "xsd" (default) or
* "dtd"
*/
::method jsonToXmlFile class
use strict arg obj, path, schema = "xsd"
xml = self~jsonToXml(obj, schema)
s = .stream~new(path)~~open("WRITE REPLACE")
if s~state \== "READY" then
raise syntax 93.900 additional("Cannot open file for writing:" path)
s~charOut(xml)
s~close
/* ========================================================================== */
/* Encoding: ooRexx objects -> JSON text */
/* ========================================================================== */
/**
* Converts a Rexx object to JSON formatting.
*
* @param rexxObject The object to convert. Accepts MapCollection, OrderedCollections,
* or String objects, JsonBoolean objects or nil. Otherwise, it calls
* the makeJSON, makeArray, or makeString method for the object.
* @param legible Optional logical value (default .false). If .true, the output
* includes ignorable whitespace for human readability.
*/
::method toJSON
expose buffer legible leadin crlf
use strict arg rexxObject, legible=(.false) -- default to minimized JSON
if arg()=2 then -- check supplied argument
.Validate~logical("legible",legible) -- test for logical value 0 or 1
buffer = .mutablebuffer~new()
leadin = " " -- 3-space indentation for legible output
self~emitValue(rexxObject, 0)
return buffer~string
/** Emits a JSON value for any ooRexx object. Dispatches based on object type.
* Handles both minimized and legible output via the 'legible' instance variable.
*
* @param rexxObject the object to encode
* @param level current indentation level (used only in legible mode)
*/
::method emitValue private
expose buffer legible
use strict arg rexxObject, level
select
when rexxObject~isA(.string) then do
call string2json buffer, rexxObject
end
when rexxObject~isA(.OrderedCollection) then do
self~emitArray(rexxObject, level)
end
when rexxObject~isA(.MapCollection) then do
self~emitObject(rexxObject, level)
end
when rexxObject~isNil then do
buffer~append('null')
end
when rexxObject~hasMethod('makejson') then do
-- object can render itself as a JSON string; handles .JsonBoolean as well
buffer~append(rexxObject~makeJson)
end
when rexxObject~hasMethod('makearray') then do
self~emitValue(rexxObject~makearray, level)
end
when rexxObject~hasMethod('makestring') then do
-- object can render itself as string; use proper JSON escaping
call string2json buffer, rexxObject~makeString
end
otherwise
-- use the object's string method; may help debugging if needed
call string2json buffer, rexxObject~string
end
/** Emits a JSON array from an OrderedCollection.
*
* @param rexxObject the OrderedCollection to encode
* @param level current indentation level
*/
::method emitArray private
expose buffer legible leadin crlf
use strict arg rexxObject, level
buffer~append('[')
items = rexxObject~items
if items == 0 then buffer~append(']')
else do
level += 1
if legible then buffer~append(crlf, leadin~copies(level))
do counter c item over rexxObject
self~emitValue(item, level)
if c <> items then do
buffer~append(',')
if legible then buffer~append(crlf, leadin~copies(level))
end
else do
if legible then buffer~append(crlf, leadin~copies(level - 1))
buffer~append(']')
end
end
level -= 1
end
/** Emits a JSON object from a MapCollection. Keys are sorted alphabetically
* for reproducible output.
*
* @param rexxObject the MapCollection to encode
* @param level current indentation level
*/
::method emitObject private
expose buffer legible leadin crlf
use strict arg rexxObject, level
buffer~append('{')
items = rexxObject~items
if items == 0 then buffer~append('}')
else do
level += 1
if legible then buffer~append(crlf, leadin~copies(level))
do counter c index over rexxObject~allIndexes~sort
-- encode the key: must be a quoted string in JSON
if index~isA(.string) then
call string2json buffer, index, .true -- force quoted
else
call string2json buffer, index~string, .true -- convert to string, force quoted
buffer~append(':')
if legible then buffer~append(' ')
self~emitValue(rexxObject[index], level)
if c <> items then do
buffer~append(',')
if legible then buffer~append(crlf, leadin~copies(level))
end
else do
if legible then buffer~append(crlf, leadin~copies(level - 1))
buffer~append('}')
end
end
level -= 1
end
/* ========================================================================== */
/* Public XML parsing (instance methods) */
/* ========================================================================== */
/** Parses an XML string (conforming to json.xsd or
* json.dtd) back into an ooRexx object tree.
*
* @param input an XML string or an .Array of lines
* @return the ooRexx object tree
* @see JsonXmlParser
* @see JsonXmlEmitter
*/
::method parseXml
use strict arg input
select
when input~isA(.string) then
t = input~changeStr("0D0A"x, "0A"x)~changeStr("0D"x, "0A"x)
when input~isA(.array) then
t = input~makeString('L', "0A"x)
otherwise
raise syntax 93.900 additional("parseXml: input must be a String or Array")
end
xmlParser = .JsonXmlParser~new
return xmlParser~parse(t)
/** Parses an XML file (conforming to json.xsd or
* json.dtd) back into an ooRexx object tree.
*
* @param path the file system path to read
* @return the ooRexx object tree
*/
::method parseXmlFile
use strict arg path
s = .stream~new(path)~~open("READ")
if s~state \== "READY" then
raise syntax 93.900 additional("Cannot open file:" path)
arr = s~arrayIn
s~close
return self~parseXml(arr)
/* ========================================================================== */
/* Decoding: JSON text -> ooRexx objects */
/* ========================================================================== */
/**
* Recursively converts a JSON text to Rexx objects.
*
* @param jsonString A JSON text.
*/
::method fromJSON
expose jsonString jsonPos jsonStringLength
use strict arg jsonString
-- strip UTF-8 BOM if present
if jsonString~left(3) == 'EFBBBF'x then
jsonString = jsonString~substr(4)
jsonPos = 1
jsonStringLength = jsonString~length
self~trimLeadingWhitespace()
rexxObject = self~parseJSONvalue()
if jsonPos > jsonStringLength then return rexxObject
self~trimLeadingWhitespace()
if jsonPos > jsonStringLength then return rexxObject
self~raiseError('Expected end of input')
return .nil
/**
* Determines type of value.
*
*/
::method parseJSONvalue private
expose jsonString jsonPos
parse value jsonString with =(jsonPos) char +1
select
when char == '{' then do
jsonPos = jsonPos + 1
return self~parseJSONobject()
end
when char == '[' then do
jsonPos = jsonPos + 1
return self~parseJSONarray()
end
when char == '"' then do
jsonPos = jsonPos + 1
return self~parseJSONstring()
end
otherwise return self~parseJSONother()
end
return
/**
* Converts a JSON object into a Rexx directory object.
*
*/
::method parseJSONobject private
expose jsonString jsonPos
rexxDirectory = .directory~new()
self~trimLeadingWhitespace()
parse value jsonString with =(jsonPos) char +1
if char == '}' then do
jsonPos = jsonPos + 1
return rexxDirectory
end
else self~parseJSONobjectValue(rexxDirectory)
do forever
self~trimLeadingWhitespace()
parse value jsonString with =(jsonPos) char +1
select
when char == '}' then do
jsonPos = jsonPos + 1
return rexxDirectory
end
when char == ',' then do
jsonPos = jsonPos + 1
self~parseJSONobjectValue(rexxDirectory)
end
otherwise self~raiseError('Expected end of an object or new value')
end
end
return
/**
* Converts JSON name:value pairs into a Rexx directory item@index.
*
* @param rexxDirectory A Rexx directory object.
*/
::method parseJSONobjectValue private
expose jsonString jsonPos
use strict arg rexxDirectory
self~trimLeadingWhitespace()
parse value jsonString with =(jsonPos) char +1
if char == '"' then do
jsonPos = jsonPos + 1
index = self~parseJSONstring()
end
else self~raiseError('Name must be a quoted string')
self~trimLeadingWhitespace()
parse value jsonString with =(jsonPos) char +1
if char == ':' then do
jsonPos = jsonPos + 1
self~trimLeadingWhitespace()
rexxDirectory[index] = self~parseJSONvalue()
end
else self~raiseError('Expected colon separating object name and value')
return
/**
* Converts a JSON array into a Rexx array object.
*
*/
::method parseJSONarray private
expose jsonString jsonPos
rexxArray = .array~new()
self~trimLeadingWhitespace()
parse value jsonString with =(jsonPos) char +1
if char == ']' then do
jsonPos = jsonPos + 1
return rexxArray
end
else do
self~trimLeadingWhitespace()
rexxArray~append(self~parseJSONvalue())
end
do forever
self~trimLeadingWhitespace()
parse value jsonString with =(jsonPos) char +1
select
when char == ']' then do
jsonPos = jsonPos + 1
return rexxArray
end
when char == ',' then do
jsonPos = jsonPos + 1
self~trimLeadingWhitespace()
rexxArray~append(self~parseJSONvalue())
end
otherwise self~raiseError('Expected end of an array or new value')
end
end
return
/**
* Converts a quoted JSON string into a Rexx string object.
*
*/
::method parseJSONstring private
expose jsonString uJS jsonPos jsonStringLength
rexxString = .mutablebuffer~new()
do forever
parse value jsonString with =(jsonPos) char +1
if char == '\' then do
parse value jsonString with =(jsonPos) char2 +2
if uJS~hasIndex(char2) then do
-- two-character escape sequences \" \\ \/ \b \f \n \r \t
jsonPos = jsonPos + 2
rexxString~append(uJS[char2])
end
else if jsonString~match(jsonPos, "\u00") then do
-- \u00XX escape sequence is supported
hex = jsonString[jsonPos + 4, 2]
if hex~length == 2, hex~dataType("x") then do
jsonPos = jsonPos + 6
rexxString~append(hex~x2c)
end
else
self~raiseError("Invalid escape sequence")
end
else if jsonString~match(jsonPos, "\u") then do
-- in general \uXXXX escape sequences are not supported
-- as ooRexx has no Unicode support
-- short of failing, we just keep any \uXXXX as-is
hex = jsonString[jsonPos + 2, 4]
if hex~length == 4, hex~dataType("x") then do
jsonPos = jsonPos + 6
rexxString~append("\u", hex)
end
else
self~raiseError("Invalid escape sequence")
end
else do
self~raiseError("Invalid escape sequence")
end
end
else if char == '"' then do
jsonPos = jsonPos + 1
return .jsonString~new(rexxString~string)
end
else do
-- reject raw control characters U+0000..U+001F per RFC 8259 §7
if char <<= '1F'x then
self~raiseError("Unescaped control character in string")
-- append to the string up to the next quote, backslash, or control char
stop = jsonString~verify('"\'||'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'x, "match", jsonPos)
if stop == 0
then stop = jsonStringLength + 1
rexxString~append(jsonString[jsonPos, stop - jsonPos])
jsonPos = stop
end
if jsonPos > jsonStringLength then self~raiseError('Expected end of a quoted string')
end
return
/**
* Converts other JSON types (numbers, booleans, null) into Rexx objects.
*
*/
::method parseJSONother private
expose jsonString ctrl jsonPos jsonStringLength
length = jsonStringLength + 1
do i = jsonPos while i \== length
parse value jsonString with =(i) char +1
if ctrl~hasIndex(char) then leave
end
parse value jsonString with =(jsonPos) string +(i - jsonPos)
if self~isJsonNumber(string) then do
jsonPos = jsonPos + string~length
return string
end
else do
select
when string == 'false' then do
jsonPos = jsonPos + string~length
return .JsonBoolean~false
end
when string == 'true' then do
jsonPos = jsonPos + string~length
return .JsonBoolean~true
end
when string == 'null' then do
jsonPos = jsonPos + string~length
return .nil
end
otherwise nop
end
end
self~raiseError('Invalid JSON value')
return
/**
* Skips allowed whitespace between values.
*
*/
::method trimLeadingWhitespace private
expose jsonString jsonPos jsonStringLength
jsonPos = jsonString~verify('20 09 0d 0a'x, , jsonPos)
if jsonPos == 0
then jsonPos = jsonStringLength + 1
/** Raises a JSON parse error with line, column, and context information.
* Computes the 1-based line number and column from the current character
* position in the JSON string.
*
* @param msg the error description
*/
::method raiseError private
expose jsonString jsonPos jsonStringLength
use strict arg msg
-- compute line and column from jsonPos
lineNum = 1
lineStart = 1
do i = 1 to min(jsonPos, jsonStringLength) - 1
char = jsonString~substr(i, 1)
if char == '0A'x then do
lineNum += 1
lineStart = i + 1
end
else if char == '0D'x then do
lineNum += 1
-- handle CR+LF as a single newline
if i < jsonStringLength, jsonString~substr(i + 1, 1) == '0A'x then
i += 1
lineStart = i + 1
end
end
col = jsonPos - lineStart + 1
-- extract context line (from lineStart to end of line or string)
lineEnd = jsonString~pos('0A'x, lineStart)
if lineEnd == 0 then lineEnd = jsonStringLength + 1
-- also check for CR
crPos = jsonString~pos('0D'x, lineStart)
if crPos > 0, crPos < lineEnd then lineEnd = crPos
contextLine = jsonString~substr(lineStart, lineEnd - lineStart)
raise syntax 93.900 additional(.JsonError~new(msg, lineNum, col, contextLine)~makeString)
/**
* Validates a string against the JSON number grammar (RFC 8259):
*
* number = [ "-" ] int [ frac ] [ exp ]
* int = "0" / ( digit1-9 *DIGIT )
* frac = "." 1*DIGIT
* exp = ( "e" / "E" ) [ "+" / "-" ] 1*DIGIT
*
* Returns .true if the string is a valid JSON number, .false otherwise.
*
*/
::method isJsonNumber private
use arg string
return isJsonNumber(string)
/* ========================================================================= */
/* JsonError */
/* ========================================================================= */
/** Represents an error encountered during JSON parsing. Instances carry the
* error message, source location (line and column), and the offending input
* line for diagnostic purposes.
*
* @see Json
*/
::class JsonError public
/** The human-readable error description. */
::attribute message
/** The 1-based line number where the error was detected (0 if unknown). */
::attribute lineNumber
/** The 1-based column where the error was detected (0 if unknown). */
::attribute column
/** The source line that triggered the error (empty string if unavailable). */
::attribute contextLine
/** Creates a new JsonError instance.
*
* @param message the error description
* @param lineNumber optional 1-based line number (default 0)
* @param column optional 1-based column (default 0)
* @param contextLine optional source line text (default "")
*/
::method init
expose message lineNumber column contextLine
use strict arg message, lineNumber = 0, column = 0, contextLine = ""
/** Returns a human-readable representation of the error, including the line
* number, column, and context line when available.
*
* @return a formatted error string
*/
::method makeString
expose message lineNumber column contextLine
s = "JsonError:" message
if lineNumber > 0 then do
s = s "(line" lineNumber
if column > 0 then s = s", column" column
s = s")"
end
if contextLine \== "" then s = s || "0A"x || " >" contextLine~strip
return s
/* ========================================================================= */
/* JsonBoolean */
/* ========================================================================= */
/** An ooRexx class to represent a JSON boolean (logical) value. It inherits from
the ooRexx mixinclass Comparable and therefore implements its abstract
method compareTo.
To get access to the JsonBoolean true and false
sentinels it is advised to use the JSON class attributes
true and false.
*/
::class "JSONBoolean" public inherit comparable
/** Class getter attribute method that refers to the proxy object that represents the value .true.
*/
::attribute true get class unguarded -- true proxy, class getter method
/** Class getter attribute method that refers to the proxy object that represents the value .false.
*/
::attribute false get class unguarded -- false proxy, class getter method
/** Make sure that only the JsonBoolean class can create instances.
*/
::method new class private
forward class (super)
/** Finalizes the class initialization by creating the two proxy class attribute values true
* and false.
*/
::method activate class -- initialization of class object complete, we now can use everything
expose true false
true =self~new(.true) -- create and store true proxy value
false=self~new(.false) -- create and store false proxy value
/** Constructor that saves argument in its attribute 'value'.
* @param value mandatory Rexx string representing the logical value
*/
::method init -- make constructor method inaccessible to other classes, own metaclass is allowed to access directly
expose value
use strict arg value -- assign boolean value
/** Returns the Rexx logical value (0 or 1) stored in this JsonBoolean.
* @return the logical value
*/
::method value unguarded
expose value
return value
/** Forwards message to the string value of the JsonBoolean.
*/
::method unknown unguarded
expose value -- the string value of this JsonBoolean
use arg msg, args
forward to (value) message (msg) arguments (args) -- maybe a method of the string value, forward it
/** Equal comparison method, needs to be overridden otherwise .Object's method gets run instead.
* @param other the other object representing a Boolean/logical value
* @return .true, if this object and other can be regarded to be equal, .false else
*/
::method "=" unguarded -- equal method
expose value
use strict arg other -- other must be a Boolean value
return value~compareTo(other)=0
/** Unequal comparison method.
* @param other the other object representing a Boolean/logical value
* @return .true, if this object and other cannot be regarded to be equal, .false else
*/
::method "\=" unguarded -- unequal method
expose value
use strict arg other -- other must be a Boolean value
return value~compareTo(other)\=0
/** Unequal comparison method, forwarding to method "\=".
*/
::method "<>" unguarded -- synonym for "\="
forward message ("\=")
/** Unequal comparison method, forwarding to method "\=".
*/
::method "><" unguarded -- synonym for "\="
forward message ("\=")
/** Implements the abstract method inherited from the mixinclass Comparable.
*/
::method compareTo unguarded -- implementation for .orderable class: must return -1 if other greater, 0 if same, 1 otherwise
expose value
use strict arg other -- other must be a Boolean value
if other~isA(.JsonBoolean) then -- get Rexx string representing logical value
otherValue=other~value
else
otherValue=other~request("string") -- request the string value
if otherValue=.nil then
raise syntax 88.900 array ("Argument ""other"" ["other"] has no 'MAKESTRING' method")
if value < otherValue then return -1 -- self smaller than other
if value = otherValue then return 0 -- self equal to other
return 1 -- self greater than other
/** Renders the object as a Rexx string representing its logical value.
* @return a Rexx string representing its logical value, either "0" or
* "1"
*/
::method makeString unguarded -- allow instances of this class to be a plug in replacement for Rexx logical values
expose value
return value
/** Renders the object as a JSON string representing its logical value.
* @return a string representing its logical value JSON encoded, either "false"
* or "true"
*/
::method makeJSON unguarded -- creates the string "true" or "false", depending on the attribute "value"
expose value
if value=.true then return "true"
return "false"
/* ========================================================================= */
/* JsonString */
/* ========================================================================= */
/** An ooRexx class that represents a JSON string value. To force numeric values
* to be encoded as JSON strings, use this class, e.g.
* jstring=.JsonString~new("123456789")
*/
::class "JsonString" subclass string public
::method makeJSON unguarded
buffer=.MutableBuffer~new
call string2json buffer, self
return buffer~string
/* ========================================================================= */
/* JsonXmlEmitter */
/* ========================================================================= */
/** Serialises an in-memory ooRexx object tree to XML conforming to either
* json.xsd (with namespace) or json.dtd
* (with DOCTYPE).
*
* Used internally by Json~jsonToXml and
* Json~jsonToXmlFile.
"xsd" (default) or
* "dtd"
*/
::method init
expose schema
use strict arg schema = "xsd"
schema = schema~lower
if schema \== "xsd" & schema \== "dtd" then
raise syntax 93.900 additional("schema must be 'xsd' or 'dtd'")
/** Emits the given ooRexx object tree as an XML string.
*
* @param obj the root object to serialise
* @return a well-formed XML string
*/
::method emit
expose schema
use strict arg obj
mb = .mutableBuffer~new
mb~append('', "0A"x)
if schema == "xsd" then
mb~append('json.xsd or json.dtd
* back into ooRexx objects. This is a purpose-built parser for the JSON XML
* vocabulary — it is not a general-purpose XML parser.
*
* Used internally by Json~parseXml and
* Json~parseXmlFile.