Common approaches accross exchange models

IWXXM previously used a versioning methodology adapted from other WMO standards which is fairly different from common practices and caused some confusions. To ensure a consistent understanding of life cycle across different exchange models (XMs), a common approach is being proposed by the modellers of AIXM, FIXM and IWXXM on model versioning, item deprecation and schema namespace policy.

Version policy

Semantic versioning 2.0.0 is being used as a common reference for model versioning. Given a version number MAJOR.MINOR.PATCH (e.g. IWXXM version 2.1.1):

• A MAJOR (X.y.z) version introduces major conceptual changes. Forward data mapping is not guaranteed. The changes justifying a new MAJOR release include, but not limited to:
  • Re-factoring a large part of the model
  • Scope reduction of the XM / deletion of model elements without prior deprecation or replacement
  • Use of a different data encoding syntax, or withdrawal of a given physical realization of the XM Logical Model
• A MINOR (x.Y.x) version introduces new model elements and capabilities guaranteeing forward data mapping for non-deprecated elements or deprecated elements with replacement. Loss of information may happen for elements being no longer required. The changes allowed in a MINOR release include, but not limited to:
  • Inclusion of new model elements, in particular in support of evolving ICAO requirements (e.g. SARPS update)
  • Deprecation of model elements, with or without replacement
  • Deletion of model elements deprecated in a previous version
  • Addition of a new physical realization of the XM Logical Model
• A PATCH (x.y.Z) version is limited to bug fixing. Forward and backward data mapping is guaranteed without loss of information. A PATCH version does not impose changes in a consuming system. A PATCH version may still require data conversion to be made ahead of the data entering in the consuming system (done by a mediator service). The changes allowed in a PATCH release include, but are not limited to:
  • Clarification of definitions, changes to the XM documentation package and/or to the XM Logical Model with no impact on the physical realization(s).
  • Correcting spelling mistakes, including in physical realizations
  • Updating external references
• Alpha, Beta or Release Candidate versions, if created, will be named as follows:
  • X.Y.Z_ALPHA
  • X.Y.Z_BETA
  • X.Y.Z_RC

An optional increment may be added in order to distinguish between multiple ALPHA, BETA or RC versions (e.g. X.Y.Z_RC2)

W3C XML Schema Versioning Use Cases has provided further elaborations on XML schema forward and backward compatibilities.

Use of deprecation

(Withheld. See #102 for more discussions on this topic)

The proposed deprecation policy for the XMs reads as follows:

• Requirements for deprecation information:
  • Rationale – The reason for the deprecation, such as a replacement or a particular capability being no longer supported
  • Replacement – A reference to other model element(s) that should be used instead, if applicable
  • Deprecation version – The version in which the deprecation occurs
  • Deletion version – The version in which the deletion is planned to occur
  • Capturing deprecation information in XSD. For example:

     <annotation>
          <appinfo>deprecated</appinfo>
          <documentation> 
               <deprecated>
                    <rationale>[…]</rationale>
                    <replacement>[…]</replacement>
                    <deprecationVersion>X.Y.Z</deprecationversion>
                    <deletionVersion>[…]</deletionversion>
                </deprecated>
           </documentation>
     </annotation>

• Capturing deprecation information in UML. For example: Using Sparx EA Tagged Value or stereotype <<deprecated></deprecated>>

Namespace policy

(Withheld. See #28 for more discussions on this topic)

The XM namespace pattern shall be http://www.??xm.aero/schema/{X}.{Y} where {X}.{Y} are the first two version levels from the version designator of the corresponding XM release. Furthermore:

• the namespace shall incorporate the major and minor version designation
• a patch version designator shall not appear in the XML namespace
• The use of only the first two version elements is consistent with the principle that the third number in a version designator designates patch releases only, with no change of content, so users should only use the latest patch versio

Applicability

At the joint ICAO WG-MIE and WG-MRI workshop (EUROCONTROL, Brussels, Belgium, 26-28 Nov 2018) the participants agreed to:

• adopt the proposed version policy
• consider the deprecation procedures only when necessary (and sufficient)
• continue the use of existing Namespace (i.e. http://icao.int/iwxxm/X.Y where X and Y are major and minor version numbers) for IWXXM