Ability to write extension to the code list and enumeration

[jkorosi]

Branch or PR for inclusion

[add when created]

Summary and Purpose

IWXXM extension was introduced in version 2 to facilitate producers to include information beyond the provisions in Annex 3. It is currently implemented only for XML elements derived from GML FeatureType, Type and DataType.

Stakeholder(s) 

• Tim Hailes <tim.hailes@bom.gov.au>

Reason 

1. Need for an extension to XML elements derived from GML CodeList type

• The current design does not allow writing an extension of the code list. The real-life example is the need to define freezing layers phenomenon in the AIRMET warning. The phenomenon is in AIRMET defined by iwxxm:AeronauticalAreaWeatherPhenomenonType.

<complexType name="AeronauticalAreaWeatherPhenomenonType">
<annotation>
 <documentation>Weather phenomenon of significance to aviation operations; used in AIRMET reports. The set of permitted options are defined in ICAO Annex 3 / WMO No. 49-2 C.3.1 sub-clause 1.1.4</documentation>
 <appinfo>
   <vocabulary>http://codes.wmo.int/49-2/AirWxPhenomena</vocabulary>
   <extensibility>none</extensibility>
 </appinfo>
</annotation>
<complexContent>
 <extension base="gml:ReferenceType"/>
</complexContent>
</complexType>

• The definition of extension will have an impact on the Schematron rules

<sch:pattern id="AIRMET.AIRMET.phenomenon">
   <sch:rule context="//iwxxm:AIRMET/iwxxm:phenomenon">
      <sch:assert test="@xlink:href = document('codes.wmo.int-49-2-AirWxPhenomena.rdf')/rdf:RDF/*/skos:member/*/@*[local-name()='about'] or @nilReason">AIRMET/iwxxm:phenomenon elements should be a member of http://codes.wmo.int/49-2/AirWxPhenomena</sch:assert>
   </sch:rule>
</sch:pattern>

2. Need for an extension to XML elements derived from GML Enumeration type

• The similar situation can occur when we need to extend enumeration. For example the definition of INTER in TAF is not possible. The INTER is even allowed by Manual on Codes - Regional Codes and National Coding Practices, Volume II

<simpleType name="AerodromeForecastChangeIndicatorType">
<annotation>
 <documentation>
   The forecast change indicator type, including temporary, permanent, or probable conditions.  This is an extension of ForecastChangeIndicator that includes report-specific entries, and in particular the 30 and 40% probability conditions.
   Note that the TAC representations for "FM", "TL", and "AT" are represented by the phenomenonTime on the change forecast (MeteorologicalAerodromeForecast):
   FM and TL - a phenomenonTime with a TimePeriod (start is FM and end is TL)
   TL - a phenomenonTime with a TimePeriod (start is beginning of forecast validity and end is TL)
   FM - a phenomenonTime with a TimePeriod (start is FM and end is end of forecast validity)
   AT - a phenomenonTime with a TimeInstant
 </documentation>
</annotation>
<restriction base="string">
 <enumeration value="BECOMING">
   <annotation>
     <documentation>Conditions are expected to reach or pass through specified threshold values at a regular or irregular rate and at an unspecified time during the time period.  The time period should normally not exceed 2 hours but in any case should not exceed 4 hours. ICAO Annex 3 / WMO No. 49-2: "BECMG"</documentation>
     </annotation>
 </enumeration>
 <enumeration value="TEMPORARY_FLUCTUATIONS">
     <annotation>
       <documentation>Expected temporary fluctuations to meteorological conditions which reach or pass specified threshold criteria and last for a period of less than one hour in each instance and in the aggregate cover less than half of the forecast period during which the fluctuations are expected to occur. ICAO Annex 3 / WMO No. 49-2: "TEMPO"</documentation>
     </annotation>
 </enumeration>
 ...
 <enumeration value="PROBABILITY_40_TEMPORARY_FLUCTUATIONS">
   <annotation>
     <documentation>A 40% probability of occurrence of temporary conditions of an alternative value of a forecast element or elements. ICAO Annex 3 / WMO No. 49-2: "PROB40 TEMPO"</documentation>
   </annotation>
 </enumeration>
</restriction>
</simpleType>

• The extension can also have an impact on Schematron rules if any checks it.

We should describe if such extensions can be defined and how they should be defined.

Detailed proposal 

For code lists the schema fragment may look like:

<complexType name="AerodromePresentWeatherType">
	<annotation>
		<documentation>...</documentation>
		<appinfo>
			<vocabulary>http://codes.wmo.int 49-2/AerodromePresentOrForecastWeather</vocabulary>
			<extensibility>none</extensibility>
		</appinfo>
	</annotation>
	<!-- Start of new addition for extension -->
	<complexContent>
		<extension base="gml:ReferenceType">
			<sequence>
				<element name="extension" type="gml:ReferenceType" minOccurs="0" maxOccurs="unbounded"/>
			</sequence>
		</extension>
	</complexContent>
	<!-- End of new addition for extension -->
</complexType>

and the instance fragment looks like this:

<iwxxm:presentWeather xlink:href="http://codes.wmo.int/306/4678/DZ">
	<iwxxm:extension xlink:href="http://your.own.codes.registry/your/own/code/list/entry"/>
</iwxxm:presentWeather>

or

<iwxxm:presentWeather nilReason="http://codes.wmo.int/common/nil/inapplicable">
	<iwxxm:extension xlink:href="http://your.own.codes.registry/your/own/code/list/entry"/>
</iwxxm:presentWeather>

For enumeration, the schema fragment may look like:

<simpleType name="TropicalCycloneMovementType">
	<annotation>
		<documentation>...</documentation>
	</annotation>
	<!-- Union is used for the addition of extension --> 
	<union>
		<simpleType>
			<restriction base="string">
				<enumeration value="MOVING">
					<annotation>
						<documentation>...</documentation>
					</annotation>
				</enumeration>
				<enumeration value="STATIONARY">
					<annotation>
						<documentation>...</documentation>
					</annotation>
				</enumeration>
			</restriction>
		</simpleType>
		<!-- Start of the new addition for extension -->
		<simpleType>
			<restriction base="string">
				<pattern value="extension:.[A-Z0-9_]{,30}"/>
			</restriction>
		</simpleType>
		<!-- End of the new addition for extension -->
	</union>
</simpleType>

and the instance fragment looks like:

<iwxxm:movement>extension:ABC</iwxxm:movement>

[blchoy]

Including an extension to a code list is not too difficult:

<complexType name="AerodromePresentWeatherType">
	<annotation>
		<documentation>...</documentation>
		<appinfo>
			<vocabulary>http://codes.wmo.int 49-2/AerodromePresentOrForecastWeather</vocabulary>
			<extensibility>none</extensibility>
		</appinfo>
	</annotation>
	<complexContent>
		<extension base="gml:ReferenceType">
			<sequence>
				<element name="extension" type="gml:ReferenceType" minOccurs="0" maxOccurs="1"/>
			</sequence>
		</extension>
	</complexContent>
</complexType>

and the instance fragment looks like this:

<iwxxm:presentWeather xlink:href="http://codes.wmo.int/306/4678/DZ">
	<iwxxm:extension xlink:href="http://your.own.codes.registry/your/own/code/list/entry"/>
</iwxxm:presentWeather>

Enumeration is a bit tricky, as it is of simple type. Give me some time to think of a solution.

[blchoy]

OK. For enumeration, we may want to implement extension as follow:

<simpleType name="TropicalCycloneMovementType">
	<annotation>
		<documentation>...</documentation>
	</annotation>
	<union>
		<simpleType>
			<restriction base="string">
				<enumeration value="MOVING">
					<annotation>
						<documentation>...</documentation>
					</annotation>
				</enumeration>
				<enumeration value="STATIONARY">
					<annotation>
						<documentation>...</documentation>
					</annotation>
				</enumeration>
			</restriction>
		</simpleType>
		<simpleType>
			<restriction base="string">
				<pattern value="extension:.+"/>
			</restriction>
		</simpleType>
	</union>
</simpleType>

and the instance fragment looks like:

<iwxxm:movement>extension:ABC</iwxxm:movement>

Views please?

[jkorosi]

I am afraid that the proposed solution does not really help because the intention was to define a new phenomenon. The proposal still needs to pick one from the allowed phenomena. The possible solution can be definition of "fake extension phenomenon" as

<iwxxm:presentWeather xlink:href="http://codes.wmo.int/306/4678/extensionPhenomenon">
	<iwxxm:extension xlink:href="http://your.own.codes.registry/your/own/code/list/entry"/>
</iwxxm:presentWeather>

I think it should pass the Schematron validation.

The enumeration extension seems good for me.

[blchoy]

The proposal still needs to pick one from the allowed phenomena.

If you don't want to pick any entry in the main code list, you can make it nil:

<iwxxm:presentWeather nilReason="http://codes.wmo.int/common/nil/inapplicable">
	<iwxxm:extension xlink:href="http://your.own.codes.registry/your/own/code/list/entry"/>
</iwxxm:presentWeather>

I confirm that both proposals have passed schema and schematron validations.

I am afraid that the proposed solution does not really help because the intention was to define a new phenomenon.

You will need to have the schematron rule skip checking when it encounters <iwxxm:presentWeather xlink:href="http://your.own.codes.registry/your/own/code/list/entry"/>. This can be done in this form but it will also risk the original intention to prevent syntax errors like <iwxxm:presentWeather xlink:href="http://cooks.wmo.int/306/4678/DZ"> . We need an indication that the URL is part of an extended code list. We can add an optional attribute for this purpose like <iwxxm:presentWeather xlink:href="http://your.own.codes.registry/your/own/code/list/entry" extension="true"/>, but the cleanest and most secure way (the attribute extension="true" is basically a switch to turn off schematron check, but this also leaves a back door for people to abuse its use) to do from my perspective is to add a new extension element for this purpose. Finally, may be there are people who would like to give extra information to supplement <iwxxm:presentWeather xlink:href="http://codes.wmo.int/306/4678/DZ"/> ? In this case we can make the extension AnyType instead of ReferenceType to extend its capability.

[amilan17]

not ready.