Question

I work with an application that uses a large set of xml interfaces for integration and data import / export. We use JAXB to map from those interfaces to our domain object model. One challenge we frequently face is how to deal with the need to change to the these interfaces during the course of a project in the face of new requirements.

In the ideal world, all requirements are known up front. The xml specification would be drafted to reflect those requirements and then never changed. In the real world though, gaps that impact the interfaces are discovered throughout the lifecycle of the project. Some of these changes are benign in their impact (ex. introducing a new non-required field). For other types of changes though, there is an option to implement them in an “unclean” way that preserves backward compatibility or a “cleaner” method which does not.

For example, let’s say that there is a new requirement to add ‘Field2’ everywhere that ‘Field1’ appears in the schema. Since ‘Field1’ and ‘Field2’ are functionally / logically grouped, the most natural approach (we’ll call it “Approach 1”) is to replace usages of:

<Field1></Field1>

with

<GroupingName>
    <Field1></Field1>
    <Field2></Field2>
</GropuingName>

The nice thing about Approach 1 is that it is easy to implement and maintain. The big disadvantage is that it has broken the interface. All existing XPath’s to Field1 have to be changed. The alternative (“Approach 2”) is to introduce Field2 alongside Field1 without the grouping tag.

<Field1></Field1>
<Field2></Field2>

Approach 2 preserves backward compatability but violates ‘DRY’ and does not guarantee that Field2 appears everywhere the Field1 does.

My question is, what are the industry standards / best-practices for handling xml changes in the face of new requirements Is it:

1. Force apporach 1 on the customer (new requirements = interface changes)
2. Hold your nose and take on approach 2.
3. Branch the code base. Implement approach 2 in the branch and take on approach 1 in the main trunk. (Less workable at the beginning of the project).
4. Other?

Answer 1

Modify the XSD to define a named group; not a complex type:

and replace each element declaration of “Field1” with
this insures that “Field2” must occur following “Field1” everywhere “Field1” occurs.
Set if the occurance is optional.