Encoding supplementary information in IWXXM

Introduction

Annex 3 to the Convention on International Civil Aviation allows for supplementary information to appear in the meteorological products described therein. In addition, a number of States have filed differences with the ICAO indicating one or more deviations from the standards and recommended practices described for these products. The IWXXM data model accounts for these situations by providing <extension> elements in many of the schemas' complex XML types. These elements allow States to include non-Annex 3 and supplemental content in their IWXXM documents. This wiki describes how to use them with an example of their use.

The IWXXM <extension> elements

As mentioned previously, the <extension> elements are optional and appear in many of complex XML types defined in the schemas. The following table indicates which IWXXM complex types contain the element.

Schema	XML Complex Type
common	AerodromeCloudForecastType
common	AerodromeSurfaceWindTrendForecastType
common	CloudLayerType
airmet	AIRMETEvolvingConditionCollectionType
airmet	AIRMETEvolvingConditionType
airmet	AIRMETType
metarSpeci	AerodromeCloudType
metarSpeci	AerodromeHorizontalVisibilityType
metarSpeci	AerodromeRunwayStateType
metarSpeci	AerodromeRunwayVisualRangeType
metarSpeci	AerodromeSeaConditionType
metarSpeci	AerodromeSurfaceWindType
metarSpeci	AerodromeWindShearType
metarSpeci	METARType
metarSpeci	MeteorologicalAerodromeObservationType
metarSpeci	MeteorologicalAerodromeTrendForecastType
metarSpeci	SPECIType
sigmet	SIGMETEvolvingConditionCollectionType
sigmet	SIGMETEvolvingConditionType
sigmet	SIGMETPositionCollectionType
sigmet	SIGMETPositionType
sigmet	SIGMETType
sigmet	TropicalCycloneSIGMETEvolvingConditionCollectionType
sigmet	TropicalCycloneSIGMETPositionCollectionType
spaceWxAdvisory	SpaceWeatherAdvisoryType
spaceWxAdvisory	SpaceWeatherAnalysisType
spaceWxAdvisory	SpaceWeatherRegionType
taf	AerodromeAirTemperatureForecastType
taf	MeteorologicalAerodromeForecastType
taf	TAFType
tropicalCycloneAdvisory	TropicalCycloneAdvisoryType
tropicalCycloneAdvisory	TropicalCycloneForecastConditionsType
tropicalCycloneAdvisory	TropicalCycloneObservedConditionsType
volcanicAshAdvisory	VolcanicAshAdvisoryType
volcanicAshAdvisory	VolcanicAshCloudForecastType
volcanicAshAdvisory	VolcanicAshCloudObservedOrEstimatedType
volcanicAshAdvisory	VolcanicAshForecastConditionsType
volcanicAshAdvisory	VolcanicAshObservedOrEstimatedConditionsType
volcanicAshAdvisory	WindObservedOrEstimatedType

The optional <extension> elements appear at the end of each IWXXM type listed. To illustrate, with the elements <METAR> and <CloudLayer> which are of METARType and CloudLayerType, respectively.

<METAR>
    <issueTime></issueTime>
    <aerodrome></aerodrome>
    <observationTime></observationTime>
    <observation></observation>
    <trendForecast></trendForecast>
    <extension></extension>
</METAR>

<CloudLayer>
    <amount/>
    <base/>
    <cloudType/>
    <extension></extension>
</CloudLayer>

And elements of these complex types can have an unlimited number of <extension> elements appended to their ends.

<AerodromeWindShear>
    <runway></runway>
    <extension></extension>
    <extension></extension>
</AerodromeWindShear>

With so many places to include supplementary or non-Annex 3 content in the IWXXM document, there is considerable freedom as to where the additional information can appear. However, as the producer of the IWXXM documents, the decisions should not be arbitrary and common sense should be the guide in narrowing down which IWXXM element needs to contain the additional data.

For instance, if the aerodrome observer measures a cloud base height that, during the measurement period, varies significantly around a mean value, then the element CloudLayer (which is of CloudLayerType) is likely the most logical placement of such information within the IWXXM document. Alternatively, some supplemental data may not be good candidates for inclusion into one of the specialized complex types. An example would be to indicate a loss of information due to a sensor or instrumentation failure. In such cases, the failed sensor or instrument can be reported in the <extension> element at the end of the MeteorologicalAerodromeObservation or METAR which are of MeteorologicalAerodromeObservationType and METARType, respectively.

The next objective is to write the XML complex type(s) needed to encode these data.

Writing XML schema for State extensions

Although the IWXXM <extension> elements allows for arbitrary XML content to appear within them, in order for the IWXXM document to be considered valid, all XML content within it must refer to a schema. Consumers of IWXXM documents require a copy of all schemas used to construct the document in order to perform validation. Therefore if a State disseminates IWXXM documents containing extension elements, the schema on which the extension content is based must be made available. This can be easily accomplished by posting the schema files on a web page in a similar manner as the WMO or the United States for IWXXM consumers to download.

This wiki page is not a comprehensive "How to create an XML schema" guide--there are plenty of tutorials on the internet and books for that. This is a very concise introduction of how a State can get started in creating one.

It is important that a unique namespace for the State extension types is declared. The character string is assigned to the targetNamespace attribute in the <schema> element. This effectively 'tags' all of the XML types that the State defines within the schema file. There is no formal guidance or regulation regarding the targetNamespace string, only that it be unique.

A simple example

To illustrate a State extension schema, let's write one containing an XML type that encodes the variability of a cloud base height.

Start with an empty schema:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
</xs:schema>

The 'elementFormDefault' attribute set to 'qualified' means that any component defined within the schema will 'belong' to the targetNamespace. Let's create a character string for the targetNamespace. As standard practice and convention, it looks like a URI to reduce the probablity of duplication, e.g., 'http://weather.gov.xx/iwxxm-xx/1.0'. The 'xx' portion of the string can be the 2-letter code of the State.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace='http://www.weather.gov.xx/iwxxm-xx/1.0'>
</xs:schema>

To properly encode the variability of a cloud base, an XML complex type, called 'CloudBaseVariabilityType', will contain two components: the highest and lowest values observed. To describe these values fully, one should provide the unit of measure associated with these values. To faciliate this, one can make use of--and is strongly encouraged to do so--existing types that can: 1) express a value; 2) provide a unit-of-measure attribute. The GML XML package has just the type: LengthType. To use GML components, it needs to be imported into the schema:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace='http://www.weather.gov.xx/iwxxm-xx/1.0'>
  <xs:import namespace='http://www.opengis.net/gml/3.2' schemaLocation='http://schemas.opengis.net/gml/3.2.1/gml.xsd'/>
</xs:schema>

To be clear as to which components belong to which namespace, let's define some namespace prefixes to indicate this. Putting these prefixes in the <xs:schema> element provides file-wide scope.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace='http://www.weather.gov.xx/iwxxm-xx/1.0'
 xmlns:ns1='http://www.weather.gov.xx/iwxxm-xx/1.0' xmlns:gml='http://www.opengis.net/gml/3.2'>
  <xs:import namespace='http://www.opengis.net/gml/3.2' schemaLocation='http://schemas.opengis.net/gml/3.2.1/gml.xsd'/>
</xs:schema>

Now we can use GML components in creating the desired complex type:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.weather.gov.xx/iwxxm-xx/1.0"
    xmlns:ns1="http://www.weather.gov.xx/iwxxm-xx/1.0" xmlns:gml="http://www.opengis.net/gml/3.2">
    <xs:import namespace="http://www.opengis.net/gml/3.2" schemaLocation="http://schemas.opengis.net/gml/3.2.1/gml.xsd"/>
    <xs:complexType name="CloudBaseVariabilityType">
        <xs:sequence>
            <xs:element name="low" type="gml:LengthType"/>
            <xs:element name="high" type="gml:LengthType"/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>

Now that a new XML complex type has been created, a variable of that type needs to be defined, CloudBaseVariability, so that it can be used within the IWXXM <extension> element.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.weather.gov.xx/iwxxm-xx/1.0"
    xmlns:ns1="http://www.weather.gov.xx/iwxxm-xx/1.0" xmlns:gml="http://www.opengis.net/gml/3.2">
    <xs:import namespace="http://www.opengis.net/gml/3.2" schemaLocation="http://schemas.opengis.net/gml/3.2.1/gml.xsd"/>
    <xs:complexType name="CloudBaseVariabilityType">
        <xs:sequence>
            <xs:element name="low" type="gml:LengthType"/>
            <xs:element name="high" type="gml:LengthType"/>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="CloudBaseVariability" type="ns1:CloudBaseVariabilityType"/>
</xs:schema>

Finally, although optional, it is helpful to consumers of the State's IWXXM documents to provide documentation on the components of the extension schema. Presumably much of the text could come from the State's governance documentation for the Annex 3 product.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.weather.gov.xx/iwxxm-xx/1.0"
    xmlns:ns1="http://www.weather.gov.xx/iwxxm-xx/1.0" xmlns:gml="http://www.opengis.net/gml/3.2">
    <xs:import namespace="http://www.opengis.net/gml/3.2" schemaLocation="http://schemas.opengis.net/gml/3.2.1/gml.xsd"/>
    <xs:complexType name="CloudBaseVariabilityType">
        <xs:sequence>
            <xs:element name="low" type="gml:LengthType">
                <xs:annotation>
                    <xs:documentation>Minimum cloud base height observed during sampling period</xs:documentation>
                </xs:annotation>
            </xs:element>
            <xs:element name="high" type="gml:LengthType">
                <xs:annotation>
                    <xs:documentation>Maximum cloud base height observed during sampling period</xs:documentation>
                </xs:annotation>
            </xs:element>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="CloudBaseVariability" type="ns1:CloudBaseVariabilityType">
        <xs:annotation>
            <xs:documentation>Variable cloud base height shall be reported if base varies significantly during the sampling period of the report.
Considered significant if cloud base is less than 1000 [ft_i] and varies more than 200 ft;
  base between 1000 and 2000 [ft_i] and varies more than 400 ft;
  base between 2000 and 3000 [ft_i] and varies more than 500 ft.</xs:documentation>
        </xs:annotation>
    </xs:element>.
</xs:schema>

With this schema now completed and posted on the Internet, the State can disseminate their IWXXM documents containing supplementary content.

Using State Extensions in IWXXM

With the State's extensions published in a schema file and accessible via the Internet, supplemental content can be included in the IWXXM documents the State produces and disseminates.

Continuing the example of providing supplemental data on the variabilility of a cloud layer's base height, the resulting IWXXM XML can appear like so,

<iwxxm:cloud>
    <iwxxm:AerodromeCloud>
        <iwxxm:layer>
            <iwxxm:CloudLayer>
                <iwxxm:amount xlink:href="http://codes.wmo.int/49-2/CloudAmountReportedAtAerodrome/BKN"/>
                <iwxxm:base uom="[ft_i]">900</iwxxm:base>
                <iwxxm:extension>
                    <CloudBaseVariability xmlns="http://www.weather.gov.xx/iwxxm-xx/1.0"
                        xsi:schemaLocation="http://www.weather.gov.xx/iwxxm-xx/1.0 URL-path/to/StateExtensionSchema.xsd">
                        <low uom="[ft_i]">900</low>
                        <high uom="[ft_i">1100</high>
                    </CloudBaseVariability>
                </iwxxm:extension>
            </iwxxm:CloudLayer>
        </iwxxm:layer>
    </iwxxm:AerodromeCloud>
</iwxxm:cloud>

The first element in the <iwxxm:CloudLayer> <extension> code block is the CloudBaseVariability element defined in the State's schema file. This element contains additional attributes, xmlns and xsi:schemaLocation. The first attribute indicates a change to a default namespace -- the one belonging to the State. The second attribute indicates where XML content belonging to the State's namespace can be found on the Internet, in other words, where the State's schema file is located. In this XML snippet, the scope of the State's namespace is limited to elements located within <CloudBaseVariability>.

Annex 3 to the Convention on International Civil Aviation allows for supplementary information to appear in the meteorological products described therein. This wiki illustrates how IWXXM <extension> elements are used to provide this information.