XML Format

General Notes

  • Tag name of fields, including container fields, follows the name of the Dield
    <taskElement ...>
      <targetElement .../>
      <taskOptions>...</taskOptions>
    </taskElement>
    
  • 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();
person.setName("Person");
<dataElement name="Person">
  ...
</dataElement>

Nameless Roots

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

<accessRight>
  ...
</accessRight>

Children

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

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

Null

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();
person.setName("Person");
person.setType(primaryType);
<dataElement name="Person">
  <dataElementType name="Primary"/>
  ...
</dataElement>

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(
    ComponentDataRef.withFunctionalKey("demoBooking"),
    "Booking");

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

Boolean

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; -->

Date

ISO8601 format. (See also ISO8601Converter.java.)

Input: any TZ Output: UTC (+0000)

yyyy-MM-dd'T'HH:mmZ

<!-- 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"/>

String

As text node.

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

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

See also: