---
url: >-
  /statelake/administering-statelake/designer/data-definitions/file-definitions/xml-file-definitions.md
---

# XML File Definitions

**XML** files differ from **Flat** data files because they contain information scattered within the file that relates to the file structure, interspersed with the actual data values. This format tends to make **XML** files larger in size, but can also make them easier to read.

For example, an order number in an XML file might appear as:

```xml
<OrderNumber>12345</OrderNumber>
```

**XML** also has the advantage of using what are known as **Schema** files.

These **Schema** files are separate from the **XML** data files, and describe the structure of the incoming XML data file, along with any validation rules that each data file must comply with. They are more difficult to read.

**Schema** files can be created via a simple text editor - either created from scratch, or by modifying an existing **Schema** so that it meets your current requirements.

The format of these **Schema** files determine how the incoming data is translated, and typically have a file name ending with .xsd, - whereas XML data files have an .xml file extension.

::: info
When working with XML files, **Statelake** will always require these **Schema** files, not only to define the structure of the file, but also for validation purposes when reading from, or writing to, an XML file.
:::

The following examples show the content of a simple XSD **Schema** file, and also the content of the corresponding XML data file.

## Simple XML Schema Definition (.XSD) For An Order

```xml
<?xml version="1.0"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="OrderHeader" type="OrderHeaderType"/>
<xs:complexType name="OrderHeaderType">
  <xs:sequence>
    <xs:element name="OrderNumber" type="xs:string"    minOccurs="1" maxOccurs="1" />
    <xs:element name="OrderDate"   type="xs:date"      minOccurs="1" maxOccurs="1" />
    <xs:element name="OrderLine"  type="OrderLineType" minOccurs="1" maxOccurs="unbounded" />
  </xs:sequence>
</xs:complexType>
<xs:complexType name="OrderLineType">
  <xs:sequence>
    <xs:element name="LineNumber"    type="xs:int"    minOccurs="1" maxOccurs="1" />
    <xs:element name="ProductCode"   type="xs:string" minOccurs="1" maxOccurs="1" />
    <xs:element name="OrderQuantity" type="xs:int"    minOccurs="1" maxOccurs="1" />
  </xs:sequence>
</xs:complexType>
</xs:schema>
```

## Simple XML Data File (.XML) For The Same Order

```xml
<OrderHeader>
  <OrderNumber>12345</OrderNumber>
  <OrderDate>26-10-2011</OrderDate>
  <OrderLine>
    <LineNumber>1</LineNumber>
    <ProductCode>ABC</ProductCode>
    <OrderQuantity>10</OrderQuantity>
  </OrderLine>
  <OrderLine>
    <LineNumber>2</LineNumber>
    <ProductCode>XYZ</ProductCode>
    <OrderQuantity>3</OrderQuantity>
  </OrderLine>
</OrderHeader>
```

When selecting the **XML File** type in your **File Definition**, a number of fields become available on the main screen that need populating.

An **XML File** type **File Definition** can be used to interact with any **XML File** that can be described using an **XML Schema** (XSD).

If you do not have an XSD schema file available for the XML you wish to process, you can infer one from an instance of the XML file.

## Type Specific Fields

| Field Name | Description |
|---|---|
| XSD Schema | Select the **XSD Schema** file that defines the structure of the XML you are processing. This must exist before the definition can be designed. Either click the **3-dot ellipse** to navigate to the directory where the schema file is located, or enter the appropriate path name if known.::: warningIf the \<DefaultDir> tag is used in this **XSD Schema** field, be aware that it has its own unique interpretation in the **XML Definition**. It is advised that you enter the full path if known, or use the ellipses to identify the path and **Schema** file.::: |
| Resolve imported/included schemas | Select to allow the inclusion of imported or included schemas. The default is that this box is ticked. |
| Schema Root Node | Specify the element that is to be considered the root element. This only applies if the system detects multiple root node options in the **XSD Schema**. |
| Target NS Prefix | Enter the prefix to use for the target namespace when creating **XML Files**. |
| Schema Location | Enter the location of the schema that will become the schema **Location** attribute when creating **XML Files**. This should normally be left blank. |
| Include "XMLSchema-instance (XSI)" namespace | Include the XSI namespace when creating XML files. |
| Add namespaces as needed | Add namespaces only as they are used when creating **XML Files**. Otherwise namespaces are specified as attributes of the root node. |
| Include "XMLSchema (XSD)" namespace | Include the XSD namespace when creating **XML Files**. |
| Show schema annotations in design view | Show any annotation (documentation) information from the **XSD Schema** when working in the **Designer**. |
| Include XML Prolog | Include the XML prolog when creating **XML Files**. |
| Write out files using UTF-16 encoding | Create XML files using UTF-16 encoding. |
| Use xsi:nil for null fields | This option will result in **xsi:nil** being written to elements that have null values from the mapping. Otherwise, fields with null values will be excluded from the output. |
| Output XML in readable format | Create XML files that are nicely formatted when viewed in a text editor. Not recommended as this is slow, and formatting is normally applied by the application reading the file. |
| Force namespace prefix on attributes | Where an attribute has been defined with a namespace, setting this tick box will force the namespace to be included in the XML payloads. |
| Validate XML document against Schema | Validate any read or written XML files against the XSD Schema. This is recommended. |
| Allow DTD references in XML instance | Allow XML instances that are read into the File Definition to have DTD references. This is disabled by default due to security concerns. |
| Ignore XML validation errors | By default this is unticked. Tick to transfer control from the **Action** manager to allow imperfect XML payloads in or out. In some circumstances you may be able to use **Statelake** scripting to handle any differences. |
| XSLT Transforms *Before reading* | Select an XSLT (Transform file) to be applied to the XML payload before it is processed by the definition. |
| *After writing* | Select an XSLT (Transform file) to be applied to the XML payload after it has been processed by the definition. |

## Buttons

| Button Name | Description |
|---|---|
| Create Blank XML File | Click to create an empty **XML File**. The **XSD Schema** field must hold the name of a valid schema file. |