XPath and XQuery Functions and Operators 4.0

14.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 a number of different ways:

• The layout to be used for a specific elements can be explicitly selected by supplying a conversion plan as input to the fn:element-to-map function.

• It is possible to construct a conversion plan by analyzing a corpus of documents using the fn:element-to-map-plan function.

• It is also possible to construct a conversion plan manually, or to modify the conversion plan produced by the fn:element-to-map-plan function before use.

• In the absence of an explicit conversion plan, 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.

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 by supplying a conversion plan that applies uniformly to multiple documents.

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 a conversion plan supplied to the fn:element-to-map 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:element-to-map function produces a map 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.

• Errors: situations where the layout cannot be used, and where attempting to use it will fail. For example, the empty layout cannot be used for an element that is not empty. In such a situation the recovery action is as follows, in order:

  1. Attributes are dropped, and if this is sufficient to enable the layout to be used, then the element is converted without its attributes.

  2. If the type of an element or attribute in the conversion plan is given as boolean or numeric, but the actual value of the element or attribute is not castable to xs:boolean or xs:numeric respectively, then the node is output ignoring the type property, that is, as an instance of xs:untypedAtomic.

  3. If the conversion plan supplies a fallback layout (an entry with key "*"), then the fallback layout is used.

  4. The element-to-map function fails with a dynamic error.

The rules for selecting the layout for a particular element are given later, in 14.5.6 Selecting an element layout14.5.5 Selecting an element layout14.5.614.5.5 Selecting an element layout.

Note that it is possible to request any layout for any element. If an inappropriate layout is chosen for a particular element (for example, empty layout for an element that is not empty), then the rules for that layout specify what happens. It is possible to specify a fallback layout for use when the selected layout fails: this will typically be a layout such as xml or mixed that can handle any element.

<hr class="ccc" id="zzz"/>

{ "hr": { "@class": "ccc", "@id": "zzz" } }

<date>2023-05-30</date>

{ "date": "2023-05-30" }

<price currency="USD">23.50</date>

{ "price": { "@currency": "USD", "#content": 23.50 } }

<para id="x">This is a <i>fine</i> mess!</para>

{ "para": [
     { "@id": "x" },
     "This is a ",
     { "i": "fine" },
     "mess!"
   ] }

14.5.2 Creating a conversion plan

It is possible to create a conversion plan by analyzing a collection of sample input documents. The function fn:element-to-map-plan is supplied with a collection of nodes (which will normally be element or document nodes), and it examines all the elements within the trees rooted at these nodes, looking for commonalities among like-named elements.

The output of this function (the conversion plan) holds information about how elements and attributes (identified by name) should be converted.

For elements, the information is primarily a mapping from element names (xs:QName instances) to layout names. In some cases additional information beyond the layout name is also included. The conversion plan is represented as an XDM map, whose structure is defined in this specification. A conversion plan can be constructed directly, or the plan produced by calling fn:element-to-map-plan can be modified before use. The plan can be serialized using the JSON output method and reloaded so that the same plan is used whenever a query or stylesheet is executed.

The fn:element-to-map-plan function selects a layout for a given element name N by applying the following rules:

1. Let $EE be the set of all elements named N, specifically $input/descendant-or-self::*[node-name(.) eq N]. Let $EE be the set of all elements named N, specifically $input/descendant-or-self::*[node-name(.) eq N].Let $EE be the set of all elements named N, specifically $input/descendant-or-self::*[node-name(.) eq N].

2. If empty($EE/(* | text()) (that is, if there are no child elements or text nodes) then:

   1. If empty($EE/@*) (that is, if there are no attributes), then the layout is empty: see 14.5.1.1 Layout: Empty Content.

   2. Otherwise, the layout is empty-plus: see 14.5.1.2 Layout: Empty Content with Attributes.

3. If empty($EE/*) (that is, if there are no child elements) then:

   1. If empty($EE/@*) (that is, if there are no attributes) then the layout is simple: see 14.5.1.3 Layout: Simple Content.

   2. Otherwise, simple-plus: see 14.5.1.4 Layout: Simple Content with Attributes.

   3. The plan also includes the property type. If all the elements in $EE are castable as xs:boolean, then the type is boolean; otherwise, if all the elements in $EE as castable as xs:numeric, then the type is numeric; otherwise, the type is string.

4. If empty($EE/text()[normalize-space()]) (that is, there are no text node children other than whitespace), then:

   1. If all-equal($EE/*/node-name()) and exists($EE/*[2]) (that is, if all child elements have the same name, and at least one element has multiple child elements), then:

      1. If empty($EE/@*) (that is, if there are no attributes) then list: see 14.5.1.5 Layout: Simple List.

      2. Otherwise, list-plus: see 14.5.1.6 Layout: List with Attributes.

   2. If every $e in $EE satisfies all-different($e/*/node-name()) (that is, the child elements are uniquely named among their siblings), then record: see 14.5.1.7 Layout: Record.

   3. Otherwise, sequence: see 14.5.1.8 Layout: Sequence.

5. Otherwise, mixed: see 14.5.1.9 Layout: Mixed.

For elements with simple content (more specifically, elements where the chosen layout is simple or simple-plus) the conversion plan also includes an entry indicating whether the content should be represented as a boolean, a number, or a string. If every instance of the element name has content that is castable to xs:boolean, the plan indicates "type": "boolean". If every instance of the element name has content that is castable to xs:numeric, the plan indicates "type": "numeric". In other cases, the plan indicates "type": "string"; however, this may be omitted because it is the default.

For attributes, the conversion plan identifies whether attributes (with a given name) should be represented as booleans, numbers, or strings; alternatively, it may indicate that attributes with a given name should be discarded. For every distinct attribute name present in the input, an entry is output associating the attribute name with one of the types boolean or numeric; the entry is generally omitted when the values are to be represented as strings, though the type can also be given explicitly as string. An entry with type boolean is generated for an attribute name if all the attributes with that name are castable as xs:boolean. Similarly, an entry with type numeric is generated for an attribute name if all the attributes with that name are castable as xs:numeric. In other case, the attributes are treated as being of type string. Entries with type string may be omitted, since that is the default. The entry for an attribute may also specify "type": "skip" to indicate that the attribute should be discarded.

A plan that is produced by analyzing a corpus of input documents can then be customized by the user if required. For example:

• If simple layout is chosen for a particular element name, but it is known that some documents might be encountered in which that element has attributes, then simple might be changed to simple-plus.

• If record layout is chosen for a particular element name, but it is known that some documents might be encountered in which child elements can be repeated, then record might be changed to sequence.

• If a generated plan determines that phone numbers should be represented as numbers, it might be modified to treat them as strings.

The conversion plan is a map of type map(xs:string, record(*)). The key is an element or attribute name, representing element names in the form Q{uri}local, and attributes in the form @Q{uri}localnotation: in both cases the Q{uri} part must be omitted for a name in no namespace. Strings are used as keys in preference to xs:QName instances to allow the plan to be serialized in JSON format.

A more detailed definition of the structure is given in 14.5.4 Structure of the conversion plan14.5.3 Structure of the conversion plan14.5.414.5.3 Structure of the conversion plan.

A small example might be (in its JSON serialization):

{ "bookList": { "layout": "list", "child": "book" },
  "book": { "layout": "record" },
  "author": { "layout": "simple" },
  "title": { "layout": "simple" },
  "price": { "layout": "simple", "type": "numeric" },
  "hardback": { "layout": "simple", "type": "boolean" },
  "@out-of-print": { "type": "boolean" },
  "@Q{http://www.w3.org/2001/XMLSchema-instance}nil": { "type": "skip" }
}

14.5.3 Attributes in the xsi namespace

This section defines modifications to the above rules that apply to elements having attributes in the xsi namespace (that is, http://www.w3.org/2001/XMLSchema-instance).

• When analyzing a corpus using fn:element-to-map-plan, elements having the attribute xsi:nil="true" are ignored. If all elements with a given name have this attribute, allocate the layout mixed.

• When deciding whether an element has any attributes (for example to decide between the layouts empty and empty-plus), all attributes in the xsi namespace are ignored.

• When converting an individual element to a map, all attributes in the xsi namespace are ignored.

• Notwithstanding the above, elements having the nilled property (which essentially means they are schema-validated and have the attribute xsi:nil="true"), are treated specially by each of the possible element layouts.

14.5.414.5.3 Structure of the conversion plan

This section provides a definition of the structure of the conversion plan that is output by the fn:element-to-map-plan function, and used as input to the fn:element-to-map function.

The structure is defined by the following item type:

map( xs:string,
     record ( layout? as enum("empty", "empty-plus", "simple", "simple-plus",
                              "list", list-plus",
                              "record", "sequence", "mixed",
                              "xml", "error", "deep-skip"),
              child? as xs:string,
              type? as enum("boolean", "numeric", "string", "skip")
              * )
)

The rules relating to this structure are as follows:

1. The keys of the map entries are strings of the form:

   1. local-name representing the name of an element in no namespace.

   2. Q{uri}local-name representing the name of an element in a namespace.

   3. * representing a fallback rule for use with elements where either (a) there is no more specific rule, or (b) processing using the selected layout fails.

   4. @local-name representing the name of an attribute in no namespace.

   5. @Q{uri}local-name representing the name of an attribute in a namespace.

   Any entries whose keys are not in this format will be ignored.

2. The layout entry is present if and only if the key represents the name of an element.

3. The child entry is present if and only if the value of layout is list or list-plus. It represents an element name in the format local-name for a name in no namespace, or Q{uri}local-name for a name in a namespace.

4. The type entry is present if, and only if, one of the following conditions applies:

   1. The key represents the name of an attribute.

   2. The layout is simple or simple-plus. In this case the value must not be "skip".

If additional entries (beyond those described above) are present in any of the maps, they are ignored, provided that the map is coercible to the given type definition.

The fallback rule (with key "*") is used to process elements whose name has no specific entry, and also for elements where normal processing fails (for example when the selected layout is "empty", but the element has children). If no fallback rule is present then "error" is assumed: this causes processing to fail with a dynamic error. The fallback rule will typically set the layout property to one of the following:

• error: this causes the function to fail with a dynamic error.

• deep-skip: this causes the element and its content (recursively) to be omitted from the output.

• mixed: this causes the element to be output using layout mixed

• xml: this outputs the element to be output using layout xml, which represents the content as a string containing serialized XML.

However, any layout may be used as the fallback; if it fails, the error is unrecoverable.

14.5.514.5.4 Schema-based conversion

As an alternative to constructing a conversion plan by analyzing a corpus of specimen documents, conversion may be controlled using type annotations derived from schema validation.

If the function element-to-map encounters an element whose name is not present in the conversion plan (including the case where no plan is supplied), and if the element has a type annotation T other than xs:anyType or xs:untyped, then the following rules apply:

1. Let zeroLength(ST) be true for a simple type ST if any of the following conditions is true:

   1. ST.{variety} = list, and ST.{facets} includes a length or maxLength facet whose value is 0 (zero).

   2. ST.{variety} = atomic, and ST.{facets} includes a length or maxLength facet whose value is 0 (zero).

   3. ST.{variety} = atomic, and ST.{facets} includes an enumeration facet constraining the value to be zero-length.

   4. ST.{variety} = atomic, and ST.{facets} includes a pattern facet with the value "" (a zero-length string).

2. If T is a simple type:

   1. If zeroLength(T), then the selected layout is empty (see 14.5.1.1 Layout: Empty Content).

   2. Otherwise, the selected layout is simple (see 14.5.1.3 Layout: Simple Content), and the selected type is boolean if T is derived from xs:boolean; numeric if T is derived from xs:decimal, xs:double, or xs:float; or string otherwise.

3. Otherwise (if T is a complex type):

   1. Let $noAttributes be true if T.{attribute uses} is empty and T.{attribute wildcard} is absent.

   2. If T.{content type}.{variety} = empty, then:

      1. If $noAttributes and if empty layout is not disabled, then the selected layout is empty (see 14.5.1.1 Layout: Empty Content).

      2. Otherwise, the selected layout is empty-plus (see 14.5.1.2 Layout: Empty Content with Attributes).

   3. If T.{content type}.{variety} = simple (a complex type with simple content), then:

      1. Let ST be T.{content type}.{simple type definition} (the corresponding simple type).

      2. If zeroLength(ST), then:

         1. If $noAttributes, the selected layout is empty (see 14.5.1.1 Layout: Empty Content).

         2. Otherwise, the selected layout is empty-plus (see 14.5.1.2 Layout: Empty Content with Attributes).

      3. Otherwise:

         1. If $noAttributes, the selected layout is simple (see 14.5.1.3 Layout: Simple Content).

         2. Otherwise the selected layout is simple-plus (see 14.5.1.4 Layout: Simple Content with Attributes).

         3. In both cases the selected type is one of booleannumeric, or string, chosen in the same way as for elements having a simple type.

   4. If T.{content type}.{variety} = element-only (a complex type with an element-only content model):

      1. Let $noWildcards be true if T.{content type}.{open content} is absent, and T.{content type}.{particle}, expanded recursively, contains no wildcard term.

      2. Let $childCardinalities be a set of (xs:QName, xs:double) pairs representing the expanded names of the element declaration terms within T.{content type}.{particle}, expanded recursively, and for each one, the maximum number of occurrences of elements with that name, computed using the value of the {maxOccurs} property of the particles at each level, taking the value unbounded as positive infinity.

      3. If $noWildcards is true, and if $childCardinalities contains a single entry, and that entry has a cardinality greater than one, then:

         1. If $noAttributes then the selected layout is list (see 14.5.1.5 Layout: Simple List).

         2. Otherwise, the selected layout is list-plus (see 14.5.1.6 Layout: List with Attributes).

      4. If $noWildcards is true, and if every entry in $childCardinalities has a cardinality of one, then the selected layout is record (see 14.5.1.7 Layout: Record).

      5. Otherwise, the selected layout is sequence (see 14.5.1.8 Layout: Sequence).

   5. Otherwise (that is, when T.{content type}.{variety} = mixed, the selected layout is mixed (see 14.5.1.9 Layout: Mixed).

For attribute nodes, the selected type is boolean if the type annotation is derived from xs:boolean; numeric if the type annotation is derived from xs:decimal, xs:double, or xs:float; and string otherwise.

14.5.614.5.5 Selecting an element layout

The various layouts available for elements are described in 14.5.1 Element Layouts. This section defines the rules for selecting an element layout for a given element E. The rules are applied in order.

1. If an explicit layout is given for the element name of E in the conversion plan supplied to the fn:element-to-map function call, then that layout is used. If the selected layout is deep-skip, then no output is produced for that element. If the selected layout is error, then the function fails with a dynamic error. If the selected layout fails for the element instance, then the fallback layout (identified with the key "*" in the conversion plan) is used; in the absence of a fallback layout, the function fails with a dynamic error.

2. Otherwise (when no explicit layout is given for E), if the type annotation of the element is something other than xs:untyped or xs:anyType, then a schema-determined layout is used as defined in 14.5.5 Schema-based conversion14.5.5 Schema-based conversion.Otherwise (when no explicit layout is given for E), if the type annotation of the element is something other than xs:untyped or xs:anyType, then a schema-determined layout is used as defined in 14.5.4 Schema-based conversion14.5.4 Schema-based conversion.Otherwise (when no explicit layout is given for E), if the type annotation of the element is something other than xs:untyped or xs:anyType, then a schema-determined layout is used as defined in 14.5.5 Schema-based conversion14.5.4 Schema-based conversion14.5.514.5.4 Schema-based conversion.

3. Otherwise, if the conversion plan supplies a fallback layout (identified with the key "*"), then the fallback layout is used.

4. If the above rules do not provide a layout for E, then a conversion plan for E is determined by applying the rules in 14.5.2 Creating a conversion plan, with an input that contains the single element E and no others. (Only the element E itself is considered, not its descendants.)

14.5.714.5.6 Element and Attribute Names

The name-format option gives control over how element and attribute names are formatted. There are four options:

• The default option (which may be explicitly requested by specifying "name-format": "default") retains the namespace URI for any element that is either (a) the top-level element of a tree being converted, or (b) has a name that is in a different namespace from its parent element. In such cases the format "Q{uri}local" is used. For other elements, the name is output using the local part of the element name alone. For attributes, the form "Q{uri}local" is used for an attribute in a namespace, and the local name alone is used for a no-namespace name. Namespace prefixes are not retained.

• The option eqname uses the format "Q{uri}local" for all element and attribute names that are in a namespace, or the local name alone for all names that are not in a namespace.

• The option local discards all namespace information: all elements and attributes are output using the local name alone.

• The option lexical outputs element and attribute names in the form obtained by calling the function fn:name. If the name has a prefix, the prefix is retained in the output. However, the output contains no information that enables the prefix to be associated with a namespace URI, so this format is suitable only when prefixes in the input documents are used predictably.

Regardless of the chosen name-format, and regardless of the above rules, attributes in the xml namespace (http://www.w3.org/XML/1998/namespace) are output using a lexical QName, with the prefix xml.

Attribute names in the output are typically prefixed with the character "@". The option attribute-marker allows this to be changed to a different prefix or none.

Whichever format of names is chosen, if the rules for the selected layout would result in an output map having two entries with the same key, the conflict is resolved by combining these entries into an array. For example if name-format is set to local then the element <data x:val="3" y:val="4"/> becomes either { "data": { "@val": ["3", "4"] } } or (because attribute order is unpredictable) { "data": { "@val": ["4", "3"] } }.

14.5.814.5.7 Element and Attribute Content

The conversion plan may indicate that element content is to be output as type string, numeric, or boolean: the default is string. In the case of untyped elements and attributes, the value is output as an instance of a string, numeric, or boolean type, according to this prescription. Specifically:

• If the prescribed type is boolean and the value is castable as xs:boolean, then it is output as an instance of xs:boolean.

• If the prescribed type is numeric and the value is castable as xs:numeric, then it is output as an instance of xs:integer, xs:decimal, or xs:double depending on the lexical form of the value, following the same rules as for XPath numeric literals. For example, "-1" becomes an xs:integer, 12.00 becomes an xs:decimal, and 1e-3 becomes an xs:double. The special xs:double values NaN and INF (which cannot be used as numeric literals) are also recognized.

• In all other cases the value is output as an instance of xs:untypedAtomic, retaining its original lexical form.

Where the element or attribute is schema-validated, however:

1. If an element has the nilled property (that is, xsi:nil="true"), then the mapping for nilled elements with the chosen layout is used.

2. Let AV be the typed value of the node (that is, the result of atomization).

3. If, however, an element is annotated with a type that does not allow atomization (specifically, a complex type with element-only content) then let AV be the string value of the element, as an atomic item of type xs:untypedAtomic.

4. If an attribute is annotated as having a simple type of {variety} list, or if an element using layout simple or simple-plus is annotated as having either a simple type of {variety} list or a complex type with simple content of {variety} list then the atomized value AV is represented in the result as the array represented by the XPath expression array{AV}. This applies whether or not the atomized value actually contains multiple atomic items. The individual atomic items in the array retain their type, for example items of type xs:date remain items of type xs:date in the result.

5. In all other cases AV will be a single atomic item, and this value is used as is, retaining its type.

14.5.914.5.8 Lost XDM Information

This section is non-normative. Its purpose is to explain what information available in the XDM nodes supplied as input to the fn:element-to-map function is missing from the output.

• Element and attribute names: If the chosen name-format is default or eqname, then local names and namespace URIs of elements and attributes are retained, but namespace prefixes are lost. If the chosen name-format is lexical, then prefixes are retained but namespace URIs are lost. If the chosen name-format is local then only local names are retained; namespace URIs and prefixes are lost.

  In addition, element names are lost when the parent element is mapped using list layout: see 14.5.1.5 Layout: Simple List.

• In-scope namespaces: All information about in-scope namespaces (and in particular, bindings for namespaces that are declared but not used in element and attribute names) is lost.

• Comments and processing instructions: Comments and processing instructions are lost except when they appear as children of elements that are mapped using the sequence, mixed or xml layouts.

• Text nodes: Whitespace text nodes are discarded when they appear as children of elements that are mapped using the empty, empty-plus, list, list-plus, record, or sequence layouts. Non-whitespace text nodes are never discarded.

• Additional node properties: The values of the is-id, is-idref, and is-nilled properties of a node are lost.

• Type annotations: The values of type annotations on elements are lost. Type annotations on atomized values of schema-validated nodes, however, are retained.

• Element order: The order of child elements is lost when record layout is used and the element has multiple children with the same name.

• XSI attributes: Attributes in the xsi namespace (for example, xsi:type and xsi:nil) are not represented in the result. .

• XSI attributes: Attributes in the xsi namespace (for example, xsi:type and xsi:nil) are not represented in the result. .

14.5.1014.5.9 Examples

The following examples show the effect of transforming some simple XML documents with default options, and then serializing the result as JSON with indent is set to true. The actual indentation is implementation dependent.

<a x='1' b='2'/>

{ "a":{
    "@x": "1",
    "@b": "2"
  } }

<a><x>1</x><y>2</y></a>

{ "a":{
    "x": "1",
    "y": "2"
  } }

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

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

<cities>
   <city id="LDN">
      <name>London</name>
      <size>18.2</size>
   </city>
   <city id="PRS">
      <name>Paris</name>
      <size>19.1</size>
   </city>
   <city id="BLN">
      <name>Berlin</name>
      <size>14.6</size>
   </city>
</cities>

{ "cities":[
    {
      "@id": "LDN",
      "name": "London",
      "size": "18.2"
    },
    {
      "@id": "PRS",
      "name": "Paris",
      "size": "19.1"
    },
    {
      "@id": "BLN",
      "name": "Berlin",
      "size": "14.6"
    }
  ] }

The following more complex example demonstrates a case where the default conversion is inadequate (for example, it wrongly assumes that for the third production, the order of child elements is immaterial). A better result, shown below, can be achieved by using a schema-aware conversion.

<g:grammar language="xquery"
    xmlns:g="http://www.w3.org/XPath/grammar">
  <g:production
    name="FunctionBody">
    <g:ref name="EnclosedExpr"/>
    <g:ref name="Block"/>
  </g:production>
  <g:production
    name="EnclosedExpr">
    <g:ref name="Lbrace"/>
    <g:ref name="Expr"/>
    <g:optional>
      <g:ref name="Expr"/>
    </g:optional>
    <g:ref name="Rbrace"/>
  </g:production>
  <g:production
    name="SimpleReturnClause">
    <g:string>return</g:string>
    <g:ref name="ExprSingle"/>
  </g:production>
</g:grammar>

[{ "Q{http://www.w3.org/XPath/grammar}grammar": [
  { "@language": "xquery" },
  { "production": [
    { "@name": "FunctionBody" },
    { "ref": { "@name": "EnclosedExpr" } },
    { "ref": { "@name": "Block" } }
  ] },
  { "production": [
    { "@name": "EnclosedExpr" },
    { "ref": { "@name": "Lbrace" } },
    { "ref": { "@name": "Expr" } },
    { "optional":[
      { "ref": { "@name": "Expr" } }
    ] },
    { "ref": { "@name": "Rbrace" } }
  ] },
  { "production": [
    { "@name": "SimpleReturnClause" },
    { "string": "return" },
    { "ref": { "@name": "ExprSingle" } }
  ] }
] }]

14.5.1114.5.10 fn:element-to-map-plan

Summary

Analyzes sample data to generate a conversion plan suitable for use by the element-to-map function.

Signature

fn:element-to-map-plan(
$input	as (document-node() | element())*
) as map(xs:string, record(*))

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The function takes as input a collection of document and element nodes and analyzes the trees rooted at these nodes to determine a conversion plan for converting elements in these trees to maps, suitable for serialization in JSON format. The conversion plan can be used as-is by supplying it directly to the element-to-map function; alternatively it can be amended before use. The plan can also be serialized to a file (in JSON format) allowing the same plan to be used repeatedly for transforming documents with a similar structure to those in the sample provided.

The rules followed by the function, and the detailed format of the conversion plan, are described in 14.5.2 Creating a conversion plan.

Formal Equivalent

The effect of the function is equivalent to the result of the following XQuery expression.

let $data-type := fn($nodes as node()*) {
  if (every($nodes ! (. castable as xs:boolean))) then "boolean"
  else if (every($nodes ! (. castable as xs:numeric))) then "numeric"
  else ()
}
let $name := fn($node as node()) {
  if (namespace-uri($node)) 
  then expanded-QName(node-name($node))
  else local-name($node)
}  
return (
  for $ee in $input/descendant-or-self::*
  group by $n := $name($ee)
  return { $n :
           if (empty($ee/(*|text())))
             then { 'layout' : if (empty($ee/@*)) 
                               then 'empty' 
                               else 'empty-plus' } 
           else if (empty($ee/*)) 
             then map:merge((
                    if (empty($ee/@*)) 
                      then {'layout': 'simple'}
                      else {'layout': 'simple-plus'},
                    $data-type($ee) ! { 'type': . }
                 ))
           else if (empty($ee/text()[normalize-space()])) 
             then if (all-equal($ee/*/node-name()) and exists($ee/*[2]))
                    then { 'layout': if (empty($ee/@*)) 
                                     then 'list' 
                                     else 'list-plus',
                           'child': $name(head($ee/*))
                         }
                    else { 'layout' : if (every($ee ! all-different(*/node-name())))
                                      then 'record'
                                      else 'sequence'
                         }             
           else {'layout': 'mixed'}
        },
  for $a in $input//@*
  group by $n := $name($a)
  let $t := $data-type($a)
  return $t ! { `@{$n}`: { 'type': $t } }
) => map:merge()

Notes

The conversion plan is organized by element and attribute name, so its effectiveness depends on the $input collection being homogenous in its structure, and representative of the documents that will subsequently be converted using the element-to-map function.

This function is separate from the element-to-map function for a number of reasons:

• The collection of documents that need to be analyzed to establish an effective conversion plan might be much smaller than the set of documents actually being converted.

• Conversely, it might be that only a small number of documents need to be converted at a particular time, but the conversion plan used needs to take into account variations that might exist within a larger corpus.

• If JSON output is required in a particular format, it might be necessary to fine-tune the automatically generated conversion plan to take account of these requirements.

• It might be necessary to devise a conversion plan that can be used to convert individual documents as they arrive over a period of time, and to ensure that the same conversion rules are applied to each document even though documents might exhibit variations in structure.

• The conversion plan is human-readable, which can help in understanding why the output of element-to-map is in a particular form.

Examples

Expression:	element-to-map-plan(<a><b>3</b><b>4</b></a>)
Result:	{ 'a': { 'layout': 'list', 'child': 'b' }, 'b': { 'layout': 'simple', 'type': 'numeric' } }
Expression:	element-to-map-plan((<a x="2">red</a>, <a x="3">blue</a>))
Result:	{ 'a': { 'layout': 'simple-plus' }, '@x': { 'type': 'numeric' } }
Expression:	element-to-map-plan( <a xmlns="http://example.ns">H<sub>2</sub>SO<sub>4</sub></a> )
Result:	{ 'Q{http://example.ns}a': { 'layout': 'mixed' }, 'Q{http://example.ns}sub': { 'layout': 'simple', 'type': 'numeric' } }
Expression:	element-to-map-plan((<a><b/><b/></a>, <a><b/><c/></a>))
Result:	{ 'a': { 'layout': 'sequence' }, 'b': { 'layout': 'empty' }, 'c': { 'layout': 'empty' } }

14.5.1214.5.11 fn:element-to-map

Summary

Converts an element node into a map that is suitable for JSON serialization.

Signature

fn:element-to-map(
$element	as element()?,
$options	as map(*)?	:= {}
) as map(xs:string, item()?)?

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

This function returns a map derived from the element node supplied in $element. The map is in a form that is suitable for JSON serialization, thus providing a mechanism for conversion of arbitrary XML to JSON.

The map that is returned will always be a single-entry map; the key of this entry will be a string representing the element name, and the value of the entry will be a representation of the element's attributes and children.

The entries that may appear in the $options map are as follows. The option parameter conventions apply.

record(
plan?	as map(xs:string, record(layout?, child?, type?)),
attribute-marker?	as xs:string,
name-format?	as xs:string
)

Key	Value	Meaning
plan?	A conversion plan, supplied as a map whose keys represent element and attribute names. The plan might be generated using the function element-to-map-plan, or it might be constructed in some other way. The format of the plan is described in 14.5.2 Creating a conversion plan. Type: map(xs:string, record(layout?, child?, type?)) Default: {}
attribute-marker?	A string that is prepended to any key value in the output that represents an XDM attribute node in the input. The string may be empty. If, after applying the requested prefix (or no prefix) there is a conflict between the names of attributes and child elements, then the requested prefix (or lack thereof) is ignored and the default prefix "@" is used. Type: xs:string Default: "@"
name-format?	Indicates how the names of element and attribute nodes are handled. Type: xs:string Default: "default"
	lexical	Names are output in the form produced by the fn:name function.
	local	Names are output in the form produced by the fn:local-name function.
	eqname	Names in a namespace are output in the form "Q{uri}local". Names in no namespace are output using the local name alone.
	default	An element name is output as a local name alone if either (a) it is a top-level element and is in no namespace, or (b) it is in the same namespace as its parent element. An attribute name is output as a local name alone if it is in no namespace. All other names are output in the format "Q{uri}local" if in a namespace, or "Q{}local" if in no namespace. "Top-level" here means that the element is one that appears explicitly in the sequence of elements passed in the $elements argument, as distinct from a descendant of such an element.

If $element is the empty sequence, the result is the empty sequence.

The principles for conversion from elements to maps are described in 14.5.1 Element Layouts, and the rules for selecting an element layout for each element are given in 14.5.6 Selecting an element layout14.5.5 Selecting an element layout14.5.614.5.5 Selecting an element layout.

In general, every descendant element within the tree rooted at the supplied $element maps to a key-value pair in which the key represents the element name, and the corresponding value represents the attributes and children of the element. This key-value pair will be added to the content representing its parent element, in a way that depends on the parent element's layout.

The representation of a node of any other kind depends on the layout chosen for its parent element.

Error Conditions

A dynamic error [err:FOJS0008] occurs if any element cannot be processed using the selected layout for that element, unless fallback processing is defined; or if error action is explicitly requested for an element.

Any error in the conversion plan is treated as a type error [err:XPTY0004]^XP whether or not it is technically a contravention of the defined type for the value. This relieves users and implementers of the burden of distinguishing different kinds of error in the plan.

Examples

Expression:	element-to-map(())
Result:	()
Expression:	element-to-map(<foo>bar</foo>)
Result:	{ "foo": "bar" }
Expression:	element-to-map( <list> <item value='1'/> <item value='2'/> </list>, { 'attribute-marker': '' } )
Result:	{ "list": [ { "value": "1" }, { "value": "2" } ] }
Expression:	element-to-map( <name> <first>Jane</first> <last>Smith</last> </name> )
Result:	{ "name": { "first": "Jane", "last": "Smith" } }
Expression:	element-to-map( <name xmlns="http://example.ns/"> <first>Jane</first> <middle>Elizabeth</middle> <middle>Mary</middle> <last>Smith</last> </name>, { 'plan': {'Q{http://example.ns/}name': { 'layout': 'record' }}, 'name-format' : 'local' } )
Result:	{ "name": { "first": "Jane", "middle": ["Elizabeth", "Mary"], "last": "Smith" } }
Expression:	element-to-map( <name xmlns="http://example.ns/"> <first>Jane</first> <middle>Elizabeth</middle> <middle>Mary</middle> <last>Smith</last> </name>, { 'plan': {'Q{http://example.ns/}name': { 'layout': 'record' }, 'Q{http://example.ns/}middle': { 'layout': 'deep-skip' } }, 'name-format' : 'local' } )
Result:	{ "name": { "first": "Jane", "last": "Smith" } }