Should XML elements have grouping parents?

Question

Which convention would be preferred and why (include some pros and cons of one over the other)?

This:

<company>
    <employees>
        <employee />
        <employee />
        <employee />
    </employees>
    <buildings>
        <building />
        <building />
    </building>
</company>

or this:

<company>
    <employee />
    <employee />
    <employee />
    <building />
    <building />
</company>

Answer 1

Are there attributes or data you could possibly attach to all employees in a group ? I'd normally go for the first example (a grouping element) since it gives you the freedom to

1. create multiple groups
2. attach data to the group as a whole

It's a little more verbose, but buys you a lot more flexibility going forwards.

Answer 2

To answer your question with a question... How do grouping elements affect readability, both visually and programmatically?

The grouped method (with the <employees> and <buildings>) is more visual.

The non-grouped method is a little more concise for an XPath query, /company/employees/employee vs. /company/employee.

So, it may be 6 of one, half a dozen of the other.

Answer 3

Generally when dealing with XML in programming, you often want to translate it to objects that your program can use. Most XML serializers take elements to represent properties of the parent element.

When you group them like in your top example, serializers can interpret that as a single collection or array property. In this case, you'd have a Company, which has an Employees property, which is a collection of Employee objects.

If you do it the second way, you'll end up with a Company object with properties called "Employee", "Employee2", "Employee3" or something similar. When you're programming, that's not a good object design.

Answer 4

There are no semantic reasons to have explicit representation of the collection through a specific element. In the end, both documents have the same meaning - they represent a company with all of its employees and buildings.

However, there are additional benefits the first example offers:

• it is more readable and can benefit from outlining in editors.
• you can create more strict schema
• it's easier to serialize to strongly typed collections
• you can specify attributes on the collection element that apply to all elements inside

On the flip side, the second example also has some benefits of its own (though I do find these dubious at least):

• is less chatty/uses less memory
• is easier to process through non-XML tools

Answer 5

I'd approach it by thinking of what data you're representing.

In C#, I see this:

// Top Example:
public class Company
{
  public Employee[] employees;
  public Building[] buildings;
}

// Vs. Bottom Example:
public Things[] employeesAndBuildings;

Logically, buildings and employees are not the same thing. Since your company has several buildings and several employees, you should logically seperate the two groups.

The second example is shorter and depending on what is reading the format in, the reader can just as easily separate the two items out. For readability though, the format can get more unreadable when things go in a different order:

<company>
    <employee />
    <building />
    <employee />
    <building />
    <employee />
</company>

I'd go for the first format.