Rayfish Convention for XML to JSON Mapping

The Rayfish convention is an XML-to-JSON translation standard designed to convert XML documents into strictly structured JSON objects without losing data fidelity or structural integrity. Unlike naive mapping techniques that translate XML element names directly into JSON keys, Rayfish standardizes every XML node into a uniform, predictable object schema. This approach resolves common translation challenges, such as handling repeated sibling tags, mixed content, and document order preservation.

Core Structure of a Rayfish Node

Rayfish standardizes XML by requiring every XML element to be represented as a JSON object containing a fixed set of standardized keys. Instead of using the XML tag name as the JSON property key, Rayfish stores the tag name as a value within the object.

Each standard Rayfish node object typically contains:

#name: A string representing the local name or tag name of the XML element.
#text: A string containing the text content directly inside the element (if text content exists).
#children: A JSON array containing the ordered child elements, where each child is itself a strict Rayfish JSON object.
@attributeName: Attributes of the element, often prefixed with an @ symbol or placed in a dedicated attribute map to prevent collisions with child elements or reserved properties.

Preserving Element Order and Sibling Consistency

Standard JSON objects are unordered collections of key-value pairs, which creates problems when translating XML containing multiple sibling tags with the same name (such as repeated <item> elements) or when document sequence is semantically significant.

Rayfish solves this by delegating all nested elements to the #children array. Because JSON arrays guarantee element order, the exact sequence of child nodes is preserved. Furthermore, sibling elements with identical tag names do not overwrite one another or require dynamic type switching between single objects and arrays.

Example Transformation

Consider the following XML snippet:

<book id="101">
    <title>XML Standards</title>
    <author>Jane Doe</author>
</book>

Under the Rayfish convention, this XML converts into the following strict JSON object:

{
  "#name": "book",
  "@id": "101",
  "#children": [
    {
      "#name": "title",
      "#text": "XML Standards",
      "#children": []
    },
    {
      "#name": "author",
      "#text": "Jane Doe",
      "#children": []
    }
  ]
}

Advantages and Practical Application

By standardizing every node into an identical object shape, Rayfish eliminates ambiguity during programmatic parsing. Developers can write recursive traversal algorithms using fixed keys (#name, #text, #children) without needing to inspect object keys dynamically at runtime. While this introduces verbosity compared to looser JSON conversions, it ensures full bidirectional fidelity when translating between XML and JSON formats.