XML Protocol Versioning

XML is one of the most widely used specification languages in the world. XML is used to define information exchanged between computers, describe data file formats, enable various web services, and so on. In fact, XML is so pervasive in the technology industry now that virtually every single development platform offers computer programmers a multiplicity of ways in which the parse, access, and create XML data structures.

The use of XML is real-time multimedia communication systems has been slower to gain momentum for a few reasons. But, now that XML is beginning to be used for multimedia communication systems, it is important to understand how XML should be used to ensure proper interoperability between systems. In many cases, we have observed XML being used rather rigidly and in such a way as to risk having older systems unable to properly communicate with newer systems and vise versa. The reason for such design approaches is, we believe, due to the nature of the "always on" Internet and the web services versioning models widely in use.

XML protocol versioning is not a topic limited to real-time communication systems, however. Rather, this is a topic of importance to any two communicating systems that might utilize XML as the protocol signaling syntax and which may be using different versions of the protocol at any given time.

Let us first show you an example of the kinds of problems one can encounter when using XML and not employing proper versioning techniques. This example is a rather gross one, but it still represents a real-world approach we have seen with traditional web services. Consider this message as an initial message of version 1 of a given protocol.

Source Code

<?xml version="1.0" encoding="UTF-8"?>
<FirstMessage version="1">
    <element1/>
</FirstMessage>

Now, let us suppose that the protocol designer changed the syntax of the protocol for version 2, so that the initial message transmitted by the initiating device was the following:

Source Code

<?xml version="1.0" encoding="UTF-8"?>
<InitMessage version="1">
    <SomeDifferentElement/>
</InitMessage>

Clearly, we would not expect the version 1 device to understand what "InitMessage" means. In the world of traditional web services, this did not matter since all web servers support all versions and a specific version is requested explicitly, generally through the URI. But, it is significant for communicating systems that do not necessarily support all versions simultaneously.

With legacy signaling systems, great care was taken to ensure proper forward and backward compatibility between systems. Such design principles are no less important today and should be applied appropriately to XML to ensure that two communicating XML-based systems can properly interwork when protocol enhancements are inevitably made.

Ensuring proper XML protocol interworking requires protocol designers to follow a basic set of rules, borrowing from experience, but applied to the newer XML technology.

Signal Version Information

As hard as software engineers will strive to ensure that products are interoperable between versions, there is always a chance that an error is made and backward compatibility is broken. To address such issues, version information, including the protocol version number, product identifier, and manufacturer identification, should be transmitted in any initial message sent between any two communicating devices. In most cases, this information should be ignored. But, it has been necessary in the past to insert logic into software to interwork with specific releases from certain manufacturers who did something that wasn't quite right.

As such, any XML-based protocol should have attributes in the root XML message similar to the attributes mfg="Packetizer" prod="SampleSystem" rel="1.4" below:

Source Code

<?xml version="1.0" encoding="UTF-8"?>
<setup version="1" mfg="Packetizer" prod="SampleSystem" rel="1.4">
    ... protocol elements ...
</setup>

In this example, the "version" attribute indicates the version number of the signaling protocol employed, the "mfg" attribute indicates the manufacturer, the "prod" attribute is a manufacturer-specified product identification code, and the "rel" attribute indicates the software release version. The product identification code and version numbers should be consistent in form and style from one release to another so that it might be possible to define rules to handle special situations when a given product older than a given release, for example, needs to be treated differently than newer products of the same type.

Ideally, every single message would contain this information, though it does add to the protocol overhead. At the very least, initial signaling messages should contain this information.

Lastly, we cannot stress enough that properly versioned software should not rely on the version numbers to operate properly. If properly designed following the rules described on this page, communication software should be fully interoperable without having any checks performed on the version, vendor, and product information attributes.

URIs Should be Void of Version Numbers

When building a communication system that relies on URIs, one should never place version numbers into the URIs, as is often done with traditional web services. The reason is that if one device tries to access https://example.org/v4/some_service and it does not exist, we have wasted time and resources. Following the guidelines presented on this page, it should be possible to access a service simply through the path https://example.org/some_service.

While this guidance is intended for communication systems that are not traditional web server-based systems, this same guidance is still applicable to such traditional web services. After all, if you design a web service and might offer 15 versions of the software over time, would you want to maintain 15 different URLs with slightly different software? Software development practices like that lead to horribly bloated systems. When or if it is necessary to observe a version number, only then would your software need to follow a slightly different code path.

Mandatory and Optional Elements and Attributes

One of the most important rules we can offer is that all elements and attributes within a signaling system should be optional and, where a required element or attribute is missing, a default value should be specified.

OK, let us relax the rules a little. In the first version of a protocol specification, some elements or attributes may be defined as mandatory. However, one cannot create new mandatory elements or attributes in a second revision of a protocol. After all, the version 1 devices could not have known about new elements or attributes.

Practically speaking, this can be a challenge. Even so, this rule is vitally important.

Consider this example:

Source Code

<?xml version="1.0" encoding="UTF-8"?>
<setup version="1" mfg="Packetizer" prod="SampleSystem" rel="1.4">
    <destinationAddress type="tel">+15551212</destinationAddress>
</setup>

Suppose the above example is a protocol that initiates a voice telephone call. What information is absolutely required to be present? At the very least, one would need to define the destination address of whom the caller is trying to reach. Is the caller's identity needed? Not really. In fact, virtually everything else could be treated as optional. If the caller's identity is missing and you wish to display something on the screen to indicate who is calling, a reasonable default might be "Anonymous".

Now, that is not to say that the call will not fail if the caller's identity is not present. However, that would be a matter of policy. The XML parser should properly process the message and a decision on how to handle the message should be made at the application level. Even then, a decision to fail the call or to take other such drastic action should be avoided.

When designing an XML-based communication protocol, think very carefully about what information is and is not absolutely necessary in the first version. When creating subsequent versions, it is incumbent on the protocol designer to define default values where necessary for elements and attributes that are needed, but are missing in the signaling. Older devices are definitely not going to be able to send them.

Perform Schema Validation with Extreme Care

XML-based communication systems should not perform XML schema validation. At least, validation should not be done to the extent of requiring the presence of mandatory elements and attributes, as outlined above. Further, any schema validation should not result in an error when the parser encounters unknown elements or attributes. After all, such unknown elements or attributes may be from version 2 or later of a given protocol.

Suppose that the above XML example represents a complete version 1 "setup" message. Suppose that the version 1 system were to receive the following message:

Source Code

<?xml version="1.0" encoding="UTF-8"?>
<setup version="2" mfg="Packetizer" prod="SampleSystem" rel="2.1">
    <destinationAddress type="tel">+15551212</destinationAddress>
    <conferenceID value="F6F48ABE-54AA-4881-862E-DB664DD65CDE"/>
    <mediaFlows>
        <mediaFlow id="1">
            <transport type="udp">
                <address type="ipv4" value="192.168.1.20"/>
                <port value="46446"/>
                <dscp value="ef"/>
            </transport>
        </mediaFlow>
    </mediaFlows>
    <supportedApps>
        <application id="urn:oid:1.3.6.1.4.1.17090.5.1"/>
        <application id="urn:oid:1.3.6.1.4.1.17090.5.2"/>
        <application id="urn:oid:0.0.8.325.0.1" invoke="true">
            <capabilities>
                <capability id="1" invoke="true" flowID="1"/>
                <capability id="2"/>
            </capabilities>
        </application>
        <application id="urn:oid:0.0.8.325.0.2"/>
    </supportedApps>
</setup>

The version 1 application should completely ignore every single element and attribute that was not defined as part of the version 1 schema. In this example, only the first three lines and the last line of this message should be processed by a version 1 system, while everything else would be silently ignored. A version 2 system would understand how to process all of the elements defined in this second version of the protocol. Both the version 1 and version 2 system should not make logical decisions based on the advertised protocol version in the message. That exists only for information.

Just as important, protocol designers should take great care in extending an XML-based protocol to ensure that elements can be ignored and that any changes or additions do not violate the guidelines on this page. Protocols will grow over time, with the addition of new elements and attributes, so plan for it.