XML Format

General Notes

  • Tag name of fields, including container fields, follows the name of the Dield
    <taskElement ...>
      <targetElement .../>
  • Tag name of root element follows the name of the DataElement
  • Tag name of element inside a container (<fields><field ...>) follows the name of the DataElement
  • Names can be overriden in field-renames.properties
  • Functional key storage can be adjusted in element’s *XmlReader.java and *XmlWriter.java
  • Nesting is based on Composite hierarchy

Content Representation

Data Element

<(metaElementName) (optionalName)/>

Named Roots

DataElementDetails person = new DataElementDetails();
<dataElement name="Person">

Nameless Roots

Not all elements have name field (nameNotWanted, etc.).



Child elements are placed in a container element with pluralized name of the stored element.

<dataElement name="Person">
    <field name="name">...</field>
    <field name="age">...</field>


Null value is represented as

<nullValue undefined="true"/>

Any other value of the undefined attribute will result in undefined behavior.

Element Reference

References to other elements use dataRefs or –TODO link to functional keys page–.

Name-only Reference

Elements without functional key use the element’s name as the reference key.

skinparam nodesep 50

object "__Person : DataElement__" as p {
  name : String = "Person"
  type : DataElementType = Primary

object "__Primary : DataElementType__" as primary {
  name : String = "Primary"

p -> "type" primary
// There is no DataElementTypeDataRef; we use plain DataRef
DataRef primaryType = DataRef.withName("Primary");

DataElementDetails person = new DataElementDetails();
<dataElement name="Person">
  <dataElementType name="Primary"/>

Composed Functional Key Reference

Elements with functional key store all parts of their key in XML.

Component’s functional key: name DataElement’s functional key: component_name

DataElemenDataRef bookingRef = DataElementDataRef.withFunctionalKey(

TaskElementDetails confirmBooking = new TaskElementDetails();
<taskElement name="ConfirmBooking">
  <targetElement component="demoBooking" name="Booking"/>


true or false only.

<!-- boolean isEnabled = true; -->
<isEnabled value="true"/>
<!-- boolean isEnabled = false; -->
<isEnabled value="true"/>
<!-- Boolean isEnabled = null; -->
<isEnabled undefined="true"/>

<!-- any other value than true|false is read as null -->
<isEnabled value="nope"/> <!-- read as Boolean isEnabled = null; -->


ISO8601 format. (See also ISO8601Converter.java.)

Input: any TZ Output: UTC (+0000)


<!-- 4. November 2007 12:34 CEST (+2) -->
<!-- input: -->
<createdAt value="2007-11-04T12:34+0200"/>
<!-- output: -->
<createdAt value="2007-11-04T10:34+0000"/>
<!-- Date createdAt = null; -->
<createdAt undefined="true"/>

Integer, Long

There is no type distinction in the XML; readers must observe the metamodel.

<!-- int number = 17; -->
<number value="17"/>
<!-- long another = 17L; -->
<another value="17"/>
<!-- Integer item = null; -->
<item undefined="true"/>


As text node.

Null value is exported, but is ignored on import. Instead null string is read as an empty string.

<!-- String name = "Alpha"; -->
<!-- String description = null; -->
<description is-null="true"/>
<!-- is-null="true" is read same as: -->

See also: