Proposed Interoperability Guidelines (TAB Approved)

Approved on 2nd October 2009.

This document has no formal standing in OASIS at this point in time. It has been written by the TAB in order to exchange ideas within OASIS.

Interoperability Defined

Interoperability is understood in different ways depending on the specification under consideration:

Often, specifications mix both aspects. Interoperability is also described as portability, when an entity - an artifact, a software component - is expected to be used over a platform - an API, a processor, a framework. The standardization of this platform (and of some aspect of the entity) will help the portability of such an entity over different instances of the platform.

Interoperability Guidelines: Useful When and Where

These guidelines concern the writing of specifications where there is a clear expectation that these specifications are precise enough to ensure that their implementations are interoperable or very close to be. In other words, where interoperability is only a matter of correct or consensual interpretation of the specification.

This is not always the case:

Whose Responsibility ?

A large part of the confusion about Interoperability can be summarized by the question:

Too often interoperability problems arise when each party (the specification authors, the implementation developers) is over-reliant on the other party to ensure interoperability.

This little guide is intended to point at the most common interoperability traps that specification writers could avoid, or could help implementers avoid. In other words, although the responsibility for these interoperability traps may not always be clearly attributed (in general, both parties share the blame in various proportions), there is always something that specification writers can do about them.

Ten Mistakes That Will Cause Interoperability Problems (work in progress)

1. Errors are for Wimps

Too often, the causes of errors that an implementation may experience are insufficiently identified and covered in a specification. Errors are also a communication item in addition to drawing a clear line between expected and unexpected behavior or feature. Yet they have low priority on the agenda of specification writers, when the schedule is tight. Proper definition, standardization and reporting of errors is an important aspect of interoperability.

Best Practice:

2. Remind me which Version of the Specification am I using right now?

Version and revision numbers of the implemented specification should be readily accessible, not just by other implementations but by end-users. Not doing so will invariably cause misunderstandings and interoperability issues over time. One may wonder: isn’t that mostly an implementation issue? Only partly so: while it is the responsibility of an implementation a specification to announce in some way which version(s) it supports (see the well known -v option in many command-line software tools), the specification should help make the version information that is associated with an artifact easy to access by an implementation. And when two implementations communicate, they also need a (standard) way of accessing version information about each other.

Best Practice:

3. When I see “MAY” or "SHOULD", I see “optional” all the way

The optional character of a specified feature, when concerning an artifact that may be produced and consumed, is a common source of confusion and interoperability failure. An artifact MAY implement a feature. This clearly means that a compliant device producing such an artifact MAY omit this feature. However, any compliant device consuming such an artifact MUST be able to process this feature, should it be present (unless specified otherwise). This is the intention of the definition of the MAY / OPTIONAL keywords as stated in [RFC2119] (although this subtle interpretation is not explicit enough for SHOULD / RECOMMENDED):

So implicitly, a MAY / SHOULD for an artifact becomes a MUST (be able to process) for its processors.

Best Practice:

4. I am expecting you to support this Optional Feature, will you ?

Often, specification writers use recommendations (SHOULD, RECOMMENDED) as a trade-off: on one hand they would like implementers to implement the recommended features as they know it would be best for interoperability or performance if everyone supports it. On the other hand making that feature mandatory may hurt a broader adoption of the specification. The end result is that some users will implement it and will expect others to do so, while others don’t.

Best Practice:

5. The composition of two Specifications is just the Sum of these

Specifications refer to each other, and compose with each other. For example, a protocol layer will operate above another protocol that is defined in another specification. Or, some interface used in combination with another interface. Often the specification writer wishfully assumes a “black-box” or perfectly modular composition, and ignores the “corner cases” (error escalation, mismatched features)leaving the details to implementers. The degree of variability introduced by such compositions is then underestimated. As a result, implementers may interpret differently how the composition is supposed to operate.

The composition of implementations of these specifications is a separate issue that will depend on engineering choices - but still predicated on how precisely the composition of these specifications has been specified.

Best Practice:

6. Extensibility: NIMSY (not in my specification yard)

Extensibility makes it possible to extend either the specified artifact or the functions of a specified device. A common mistake is for specification writers to treat extension points in their specification as customization hooks that are fully out of scope and the usage of which they have no responsibility for. As a result, these extension points may be used and interfere with the core specification in ways that were not foreseen, and cause unexpected interoperability problems.

Best Practice:

7. Backward Compatibility: it is all or nothing (and if it is not all, let us just not talk about it).

Assume your new specification version is not backward compatible – in general, an embarrassing fact you'd prefer users to not ask about. Yet the worse thing to do is to avoid talking about it, hoping no one will notice – which may indeed be the case in the very unlikely event where everyone migrates at the same time to the new version. Users will implicitly assume backward interoperability, and they are on their way to be disappointed and angered.

Best Practice:

8. Writing for an Exclusive Club

Who are the readers of your specification? If this is only the club of experts who spent 2 years together coming up with a consensus on how to do business in a specific area, then the specification does not need be more than a glorified MOU: every word conveys a well understood meaning in your club that does not need be further detailed, given the common background and domain culture of the authors (the club members). But if the specification must be read by implementers, end-users, test developers or product developers who may not fully share the author’s background and expertise, then interpretation mistakes or liberties will abound.

Best Practice:

9. The Conformance Clause will fix all that

Conformance clauses are not an excuse to keep a the main body of a specification wide-open to interpretations, too vague or simply incomplete. Future conformance clauses will multiply these interpretations and jeopardize interoperability. Pressure to complete a specification may lead to such abuse, with a premature release of the specification leaving the publishing of the (overloaded) conformance clause to a later date. This is enough to confuse implementers who assume wrongly that the specification alone is sufficient for their implementations to be interoperable.

Best Practice:

10. Our job is only to Specify. Verifiability is the job of Test Suite writers.

Sure, but if you do not provide at least hints on how some specification requirements might be verified, test suite writers will interpret your statements as they wish, or may just ignore them. It will not be until systems are in production, that conformance discrepancies - and therefore interoperability problems - are discovered. If there is no way to test some requirements, then conformance and interoperability hangs solely on the interpretation of your words by implementers.

Best Practice:

InteropGuide (last edited 2012-09-21 01:23:23 by jdurand2)