"Seegrid will be due for a migration to confluence on the 1st of August. Any update on or after the 1st of August will NOT be migrated"

Nil values in GML


Related pages

Nil or Void values

ISO/IEC 11404 defines the Void datatype as follows:

8.1.12 Void

Description: Void is the datatype representing an object whose presence is syntactically or semantically required, but carries no information in a given instance.


Values: Conceptually, the value space of the void datatype is empty, but a single nominal value is necessary to perform the “presence required” function.

Value-syntax: void-literal = “nil” .

“nil” is the syntactic representation of an occurrence of void as a value.

This description makes clear the semantic distinction between "missing" data, and the "nil" value.

In addition to these considerations, it has been recognized that "nil" values can often be glossed to provide the reader with information about why a required item is missing. Because of the ability to define flexible content models, XML serialization provides the opportunity for recording "null", "nil" or "void" values informatively. GML and OGC have recognised this with a taxonomy of five null or nil values as follows (GML 3.2 sub-clause

there is no value
the correct value is not readily available to the sender of this data. Furthermore, a correct value may not exist
the value will be available later
the correct value is not known to, and not computable by, the sender of this data. However, a correct value probably exists
the value is not divulged

These values are supported in two ways in OGC endorsed implementation:
  1. as the GML NilReasonType, which enumerates the five nil values plus some descriptive alternatives (other:text and anyURI)
  2. in the OGC URN scheme "def:nil" branch (see OGC 06-023r1)
However, within the GML encoding pattern, there are a number of options for how to achieve it. This page will provide a discussion of the various options and some recommendations.

GML encoding of nil values

1. Optional element

Schema definition:

<element name="propertyA" base="myns:SomeComplexGMLPropertyType" minOccurs="0"/>

this is commonly used in schema design, but leads to ambiguous semantics in the instance: what does it mean if the element is missing? maybe they just forgot or were lazy!

2. Element or attribute type="gml:NilReasonType"

Schema definition:

<element name="propertyA" type="gml:NilReasonType"/>

Instance example:


simpleContent properties, but gml:NilReasonType must be in a union with the real type for practical use. Potentially ambiguous if the real type is string based.

3. Element with nillable="true" and @nilReason

Schema definition:

<element name="propertyB" nillable="true">
         <extension base="myns:SomeSimpleType">
            <attribute name="nilReason" type="gml:NilReasonType"/>

Instance example:

<propertyB nil="true" nilReason="unknown"/>

UML models
  • The nillable tag is set to "true" for it to apply to an attribute or association in a UML model. The default nillable value for an attribute or association (ie, if the nillable tag is ommitted from the UML), is "false".
  • example of nillable tag in Enterprise Architect:
  • The FullMoon application has been upgraded (May 2011) to be able to process all "nillable" tags from UML models into XML schemas.
Best practice in GeoSciML version 3 instance documents and web services
  • The nil="true" pattern was introduced in GML v3.2, and is the best practice pattern for use with GeoSciML version 3. The majority of attributes and associations in GeoSciML version 3 are mandatory but nillable elements. That is, the element tag must occur in the XML, but its content may be nilled (nil="true") with an appropriate nilReason (eg, nilReason="missing").
  • nil="true" is not to occur in the XML where there is valid content, either inline or byReference, for an attribute or association. For example:

<cgu:value xlink:href="http://resource.geosciml.org/classifier/cgi/featureobservationmethod/0016" xlink:title="Synthesis of multiple published descriptions"/>

not <cgu:value xlink:href="http://resource.geosciml.org/classifier/cgi/featureobservationmethod/0016" xlink:title="Synthesis of multiple published descriptions" xsi:nil="true"/>

4. Special value for xlink:href on complex-type GML property element

Schema definition:

<element name="propertyC" base="myns:SomeComplexGMLPropertyType"/

Instance example:

<propertyC xlink:href="urn:ogc:def:nil:OGC:unknown"/>

most flexible, requires no change to standard application schema pattern, but only useable on complexContent properties where inlineOrByReference!="inline"

-- SimonCox - 20 Nov 2006


-- OliverRaymond - 11 May 2011
Topic attachments
I Attachment Action Size Date Who Comment
nilTag.jpgjpg nilTag.jpg manage 7.4 K 11 May 2011 - 06:54 OliverRaymond example of nillable tag in Enterprise Architect
Topic revision: r7 - 11 May 2011, OliverRaymond

Current license: All material on this collaboration platform is licensed under a Creative Commons Attribution 3.0 Australia Licence (CC BY 3.0).