XPath and XQuery Functions and Operators 4.0

17.5.1 Element Layouts

The key challenge in mapping XML to JSON is in deciding how element content is to be represented. To illustrate the variety of mappings that are possible, the following table lists some examples of typical XML elements and their JSON equivalents:

<hr/>

"hr": ""

<date-of-birth>2023-05-18</date-of-birth>

"date-of-birth": "2023-05-18"

<box width="5" height="10"/>

"box": { "@width": "5", "@height": "10" }

<label id="t41">Warning!</label>

"label": { "@id": "t41", "#content": "Warning!" }

<box>
    <width>5</width>
    <height>10</height>
</box>

"box": {
    "width": 5, 
    "height": 10
}

<polygon>
    <point x="0" y="0"/>
    <point x="1" y="0"/>
    <point x="1" y="1"/>
    <point x="0" y="1"/>
</polygon>

"polygon": [
    { "x": 0, "y": 0 }, 
    { "x": 1, "y": 0 }, 
    { "x": 1, "y": 1 }, 
    { "x": 0, "y": 1 }
]

This specification defines a number of named mappings, called layouts, and allows the layout for a particular element to be selected in four different ways:

• The layout to be used for a specific element name can be explicitly selected in the options to the fn:elements-to-maps function.

• In the absence of an explicit selection, if the data has been schema-validated, the layout is inferred from the content model for the element type as defined in the schema.

• When the data is untyped and no specific layout has been selected, a default layout is chosen based on the properties of the individual element instance.

• If the uniform option is set to true, then the same layout will be used for all elements with a given name. This means that all elements need to be examined before any element is converted.

It is possible to disable some of the layouts so they will never be chosen by the automatic rules, but only when explicitly selected.

The advantage of using schema information is that it gives a consistent representation for all elements of a particular type, even if they vary in content: for example if an element type allows optional attributes, the JSON representation will be consistent between those elements that have attributes and those without. In the absence of a schema, consistency can be achieved either by using the uniform option, or by selecting a layout explicitly in the layouts option.

The different layouts available are defined in the following sections. For each layout there is a table showing:

• Layout name: the name to be used to select this layout in the $options parameter of the fn:elements-to-maps function.

• Usage: the situations for which this layout is designed.

• Example input: an example of a typical element for which this layout is appropriate, shown as serialized XML.

• Example output: the result of converting this example, shown as serialized JSON. The result is always shown as a singleton map, which is how it will appear when the layout is used for the top-level elements supplied in the $elements argument; when used to convert a descendant element, the corresponding key-value pair may appear as part of a larger map, depending on the layout chosen for its parent element..

  Note:

  The fn:elements-to-maps function produces maps as its result, but it is convenient to illustrate the form of the map by showing the effect of serializing the map as JSON.

• Mapping rules: The rules for mapping the XML element to an XDM map representation.

• Mapping for nilled elements: special rules that apply to an element having the attribute xsi:nil="true". These rules only apply if the element has been schema-validated.

• Notes: General observations, especially concerning what information is retained by this mapping and what information is lost.

The rules for selecting the layout for a particular element are given later, in 17.5.2 Selecting an Element Layout.

Note that it is possible to use any layout for any element. Use of an inappropriate layout may result in information being discarded; but in some cases, discarding information may be the desired outcome.

<employee id="x">
  <date-of-birth>1984-03-20</date>
  <location>Germany</location>
  <position>Janitor</position>
</employee>

{ "employee": { "@id": "x", 
                "date-of-birth": "1984-03-20", 
                "location": "Germany", 
                "position": "Janitor"
              }
}

<employee id="x">
  <date-of-birth>1984-03-20</date>
  <location>Germany</location>
  <position>Janitor</position>
  <position>Gardener</position>
</employee>

{ "employee": { "@id": "x", 
                "date-of-birth": "1984-03-20", 
                "location": "Germany", 
                "position": [ "Janitor", "Gardener" ]
              }
}