Minimal IT - Minimal integration 5: keep XML simple

1 November 2005

Minimal integration 5: keep XML simple

Extensible markup language (XML) is ideal as an interface data format. To keep it simple, you need to adopt some simple rules which ignore many of its advanced features.

XML is really very simple. The basic unit of XML is called an element. Every element has a name, and some content, and is coded like this:

    <MyElementName> ... any content you like ... </MyElementName>

The content can be data, in which case we can call the element a "data element".

Alternatively, the content can be other elements. We can then call the element a "structural element".

In the example below, the elements Order, OrderItemList and OrderItem are structural elements, and the elements customerName, productNumber and quantity are data elements.

<Order>
  <customerName>Mr J Smith</customerName>
  <OrderItemList>
    <OrderItem>
      <productNumber>018716</productNumber>
      <quantity>2</quantity>
    </OrderItem>
    <OrderItem>
      <productNumber>907232</productNumber>
      <quantity>1</quantity>
    </OrderItem>
  </OrderItemList>
</Order>

The rules for keeping XML simple are also very simple.

Make a clear distinction between structural elements and data elements. Never code data directly within a structural element, or nested elements within a data element. To make the distinction clear, name structural elements so that they start with an upper case letter, and name data elements so that they start with a lower case letter.
Never have more than one occurrence of the same element within a structural element, except for lists.
Code a list as a single structural element that represents the list and a repeating set of structural elements that represent each item. The item can then contain data elements. The example above shows how to code a list.

These rules make sure that the XML is always easy to understand. They also make sure that the XML is easy to convert to other structures such as objects in a programming language or data on a database.

If you see other examples of XML, they probably will not meet these rules, and may contain more advanced features.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Sample order file -->
<Envelope xmlns:order="http://minimalit.com/order.xsd">
  <order:Order order_ref="103820">
    <order:customerName>Mr J Smith</order:customerName>
    <order:address>
      14 Acacia Avenue
      Twickenham
      <order:postcode>TR7 4BU</order:postcode>
    </order:address>
    <order:OrderItem quantity="2">018716</order:OrderItem>
    <order:OrderItem quantity="1">907232</order:OrderItem>
  </order:Order>
</Envelope>

It is useful to be able to read XML like this. The main features you will come across are:

Processing instructions in <?xml ... ?> sequences which specify character sets.
Comments in  sequences.
Name="value" pairs, called attributes, which are an alternative method of coding data.
Elements with prefixes like <order:customerName> which are part of the standards for validating XML against predefined structures.
Elements which contain both data and other elements.

I have written hundreds of XML interface definitions, and I rarely need to use any of these other features. Learn to read them, but only use them where there is a real need.

Having covered how to format data sent between systems, next week I will cover some of the technologies that we can use to actually send the data.