DGCS Portal

DigitalGlobe Cloud Services Documentation Portal

Welcome to the DigitalGlobe Cloud Services Documentation Portal. You'll find comprehensive guides and documentation to help you start working with DigitalGlobe Cloud Services as quickly as possible. Let's jump right in!

Get Started    

Geography Markup Language (GML)

1. Introduction to GML

The Geography Markup Language (GML) is the XML code used by the OGC to express geographical features. GML serves as a modeling language for geographic systems as well as an open interchange format for geographic transactions on the Internet. Note that the concept of feature in GML is a very general one and includes not only conventional “vector” or discrete objects, but also coverages and sensor data. The ability to integrate all forms of geographic information is key to the utility of GML.

GML was conceived and evolved for a variety of reasons, the most important reasons being:

  • To provide a language for expressing geographic entities – to create application specific geographic vocabularies.
  • To enable the encoding of geographic information consistent with these vocabularies.
  • To support geospatial queries and transactions across the Internet.

GML is feature-centric. Features are entities – things that describe aspects of the real world from the perspective of a particular application community – whether circumscribed by geography or function or both. GML vocabularies are created by communities of interest. These vocabularies are called GML Application Schemas. If you look at such an Application Schema you will find real world objects like Buildings, Roads, Buoys, Navigation Aids, Airline Flight Paths, Vehicles and Railway Switches. Each such object is defined in the schema by listing its properties. For example, a Building might be described by:

<abc:Building gml:id=’b143’>
	<abc:height>40</abc:height>
	<abc:footprint>
		<gml:polygon></gml:polygon>
	</abc:footprint>
</abc:Building>

Note that the Building (feature) has two properties, namely height and footprint. The height property in this case has an integer value (number of stories), while the footprint property has a Polygon (shape) for a value.

GML application schemas can be the basis of standards themselves – such as S57GML, cityGML, geoRSS GML and AIXM, or they can be informal creations for only a very small community, which in this case is up to the community.

GML application schemas should NOT be confused with GML profiles. A GML profile is a subset of GML, defined usually by the subset tool (part of the GML specification), consisting of the selected element, attribute and type declarations and all dependent components from the GML core schemas (the schemas defined by the GML specification). Application schemas can be built on GML profiles. Some GML profiles are also specifications including the GML Simple Features Profile, the Point Profile, the GML Profile for GMLJP2 and the GML Profile for GeoRSS.

GML was developed to support geographic requests and transactions and this usage predates the WCS developed for this purpose. When a user sends a request for geographic data – e.g. “find all water wells within this county” – there must be a way to express “water well”, “county” and the “geometric extent of the county”. GML is used for this purpose. When the user wants to send a transaction such as, “change the shape of the Holmes River to the following …”, the user needs a way to express the river’s geometry; GML provides this mechanism.

2. Overview of GML Schema

GML specifies XML encodings of a number of the conceptual classes defined in the ISO 19100 series of International Standards and the OpenGIS Abstract Specification in conformance with these standards and specifications.

In some cases the mapping from the conceptual classes to XML is straightforward, while in other cases the mapping is more complex.

In addition, GML provides XML encodings for concepts not yet modeled in the ISO 19100 series of International Standards or the OpenGIS Abstract Specification. Examples include moving objects, simple observations or value objects. Additional conceptual classes corresponding to these extensions are also specified in Annex D.

The GML schema comprises the components (XML elements, attributes, simple types, complex types, attribute groups, groups, etc.) that are described in this International Standard. The XML encoding conforms to ISO 19118.

3. GML Schema Feature

A GML feature is a feature encoded using GML. Examples include a road, a river, a person, a vehicle, an administrative area, or an event. The feature schema provides a framework for the creation of GML features and feature collections.

3.1 AbstractFeatureType

The basic feature model is given by the gml:AbstractFeatureType, defined in the schema as follows:

<complexType name="AbstractFeatureType" abstract="true">
	<complexContent>
		<extension base="gml:AbstractGMLType">
			<sequence>
				<element ref="gml:boundedBy" minOccurs="0"/>
				<element ref="gml:location" minOccurs="0"/>
			</sequence>
		</extension>
	</complexContent>
</complexType>

The content model for gml:AbstractFeatureType adds two specific properties suitable for geographic features to the content model defined in gml:AbstractGMLType.

The value of the gml:boundedBy property describes an envelope that encloses the entire feature instance, and is primarily useful for supporting rapid searching for features that occur in a particular location.

The value of the gml:location property describes the extent, position or relative location of the feature. gml:location is deprecated as part of the standard content model of gml:AbstractFeatureType.

3.2 AbstractFeature

The element gml:AbstractFeature is declared as follows:

<element name="AbstractFeature"
  type="gml:AbstractFeatureType"
  abstract="true"
  substitutionGroup="gml:AbstractGML"/>

This abstract element serves as the head of a substitution group which may contain any elements whose content model is derived from gml:AbstractFeatureType. This may be used as a variable in the construction of content models.

gml:AbstractFeature may be thought of as anything that is a GML feature and may be used to define variables or templates in which the value of a GML property is “any feature”. This occurs in particular in a GML feature collection where the feature member properties contain one or multiple copies of gml:AbstractFeature respectively.

The other features are boundedBy, BoundingShapeType, EnvelopeWithTimePeriod, EnvelopeWithTimePeriodType, locationName, locationReference, FeaturePropertyType, FeatureArrayPropertyType.

4. Overview

Many applications require definitions of terms that are used within instance documents as the values of certain properties or as reference information to tie properties to standard information values in some way. Units of measure and descriptions of measurable phenomena are two particular examples.

GML 3.1 provides the following advice with respect to the use of GML dictionary/definition components:

It will often be convenient to use definitions provided by external authorities. These may already be packaged for delivery in various ways, both online and offline. In order to be references from GML documents, it is usually necessary that a URL be available for each definition. Where this is the case, it is usually preferable to refer to these directly.

Alternatively, it may be convenient or necessary to capture definitions in XML, either as a separate document or embedded within an instance document containing features. The definitions may be transcriptions from an external source, or may be new definitions for a local purpose. In order to support this case, some simple components are provided in GML in the form of:

  • A generic gml:Definition, which may serve as the basis for more specialized definitions.
  • A generic gml:Dictionary, which allows a set of definitions or references to definitions to be collected.

These components may be used directly, but also serve as the basis for more specialized definition elements in GML, in particular: coordinate operations (Clause 12), coordinate reference systems (Clause 12), datums (Clause 12), temporal reference systems (Clause 14), and units of measure (Clause 16).

Note that the GML definition and dictionary components implement a simple nested hierarchy of definitions with identifiers. The latter provides handles which may be used in the description of more complex relationships between terms. However, the GML dictionary components are not intended to provide direct support for complex taxonomies, ontologies or thesauri. Specialized XML tools are available to satisfy the more sophisticated requirements.

The dictionary schema document is identified by the following location independent
name (using URN syntax): urn:x-ogc:specification:gml:schema-xsd:dictionary:3.2.1.

4.1 Dictionary Schema

Definition, DefinitionType, remarks

The basic gml:Definition element specifies a definition, which can be included in or referenced by a dictionary. It is declared as follows:

<element name="Definition" type="gml:DefinitionType"
substitutionGroup="gml:AbstractGML"/>
<complexType name="DefinitionBaseType">
  <complexContent>
    <restriction base="gml:AbstractGMLType">
      <sequence>
        <element ref="gml:metaDataProperty" minOccurs="0" maxOccurs="unbounded"/>
        <element ref="gml:description" minOccurs="0"/>
        <element ref="gml:descriptionReference" minOccurs="0"/>
        <element ref="gml:identifier"/>
        <element ref="gml:name" minOccurs="0" maxOccurs="unbounded"/>
      </sequence>
      <attribute ref="gml:id" use="required"/>
    </restriction>
  </complexContent>
</complexType>
<complexType name="DefinitionType">
  <complexContent>
    <extension base="gml:DefinitionBaseType">
      <sequence>
      	<element ref="gml:remarks" minOccurs="0"/>
      </sequence>
    </extension>
  </complexContent>
</complexType>
<element name="remarks" type="string"/>

The content model for a generic definition is a derivation from gml:AbstractGMLType.

The gml:description property element shall hold the definition if this can be captured in a simple text string, or the gml:descriptionReference property element may carry a link to a description elsewhere.

The gml:identifier element shall provide one identifier describing this definition. The identifier must be unique within the dictionaries using this definition.

The gml:name elements shall provide zero or more terms and synonyms for which this is the definition.

The gml:remarks element shall be used to hold additional textual information that is not conceptually part of the definition but is useful in understanding the definition.

Dictionary, DictionaryType

Sets of definitions may be collected into dictionaries or collections. These are declared in the schema as follows:

<element name="Dictionary" type="gml:DictionaryType"
substitutionGroup="gml:Definition"/>
<complexType name="DictionaryType">
  <complexContent>
    <extension base="gml:DefinitionType">
      <choice minOccurs="0" maxOccurs="unbounded">
        <element ref="gml:dictionaryEntry"/>
        <element ref="gml:indirectEntry"/>
      </choice>
      <attributeGroup ref="gml:AggregationAttributeGroup"/>
    </extension>
  </complexContent>
</complexType>

A gml:Dictionary is a non-abstract collection of definitions. The gml:Dictionary content model adds a list of gml:dictionaryEntry and gml:indirectEntry (deprecated) properties that contain or reference gml:Definition objects. A database handle (gml:id attribute) is required in order for this collection to be referred to.

The standard gml:identifier, gml:description, gml:descriptionReference and gml:name properties are available to reference or contain more information about this dictionary. The gml:description and gml:descriptionReference property elements may be used for a description of this dictionary. The derived gml:name element may be used for the name(s) of this dictionary.

dictionaryEntry, DictionaryEntryType

These elements contain or refer to the definitions that are members of a dictionary. The element
gml:dictionaryEntry is declared as follows:

<element name="dictionaryEntry" type="gml:DictionaryEntryType"/>
	<complexType name="DictionaryEntryType">
		<complexContent>
			<extension base="gml:AbstractMemberType">
				<sequence minOccurs="0">
					<element ref="gml:Definition"/>
				</sequence>
				<attributeGroup ref="gml:AssociationAttributeGroup"/>
			</extension>
		</complexContent>
	</complexType>

The content model follows the standard GML property pattern, so a gml:dictionaryEntry may either contain or refer to a single gml:Definition. Since gml:Dictionary is substitutable for gml:Definition, the content of an entry may itself be a lower-level dictionary.

Note that if the value is provided by reference, this definition does not carry a handle (gml:id) in this context, so does not allow external references to this specific definition in this context. When used in this way, the referenced definition will usually be in a dictionary in the same XML document.

Using Definitions and Dictionaries

Dictionaries and definitions are GML objects, so they may be found in independent GML data instance documents.

In application schemas it might be useful to attach a gml:Dictionary or gml:Definitions to a feature collection in order to record definitions used in properties of members of the collection.

The following example shows two instances of dictionaries:

<gml:Dictionary gml:id="rockTypes">
    <gml:description>
      A simple dictionary of rock types using components from gmlBase
    </gml:description>
    <gml:identifier codeSpace="http://www.abc.org/terms">
      Rock Types
    </gml:identifier>
    <gml:dictionaryEntry>
        <gml:Definition gml:id="granite">
            <gml:description>
              A igneous rock normally composed of quartz, two feldspars and
              optional mica
            </gml:description>
            <gml:identifier codeSpace="http://www.abc.org/terms">
            	Granite
            </gml:identifier>
        </gml:Definition>
    </gml:dictionaryEntry>
    <gml:dictionaryEntry>
        <gml:Definition gml:id="sst">
            <gml:description>
              A detrital sedimentary rock normally composed of siliceous
              grains
            </gml:description>
            <gml:identifier codeSpace="http://www.abc.org/terms">
             Sandstone
          	</gml:identifier>
        </gml:Definition>
    </gml:dictionaryEntry>
    <gml:dictionaryEntry xlink:href=”http://my.big.org/definitions/geology/limestone”/>
</gml:Dictionary>
<gml:Dictionary gml:id="AbridgedGMLdictionary">
    <gml:identifier codeSpace="http://www.opengis.net/gml/3.2">
    	GML Dictionary
    </gml:identifier>
    <gml:dictionaryEntry>
        <gml:Definition gml:id="term4.1">
            <gml:description>
            	conceptual schema for data required by one or more applications
            </gml:description>
            <gml:identifier codeSpace="http://www.isotc211.org/19101">
            	application schema
            </gml:identifier>
        </gml:Definition>
    </gml:dictionaryEntry>
    <gml:dictionaryEntry>
        <gml:Definition gml:id="term4.2">
            <gml:description>
              application schema written in XML Schema in accordance with the rules specified in ISO 19136
            </gml:description>
            <gml:identifier codeSpace="http://www.opengis.net/gml/3.2">
            	GML application schema
            </gml:identifier>
        </gml:Definition>
    </gml:dictionaryEntry>
    <gml:dictionaryEntry>
        <gml:Definition gml:id="term4.3">
            <gml:description>
              semantic relationship between two or more classifiers that specifies connections among their instances
            </gml:description>
            <gml:identifer codeSpace="http://www.uml.org/1.3">
             association
            </gml:identifier>
        </gml:Definition>
    </gml:dictionaryEntry>
    <gml:dictionaryEntry>
        <gml:Definition gml:id="term4.4">
            <gml:description>
             name-value pair contained in an element
          	</gml:description>
            <gml:identifer codeSpace="http://www.w3.org/XML/1998/namespace">
             attribute
            </gml:identifier>
        </gml:Definition>
    </gml:dictionaryEntry>
</gml:Dictionary>

5. GML-Based Request

The request to the web service for any of the operations can be sent as a GML-based request instead of the plain Get URL. The key and value pair of parameters that we send to the server is now sent through the GML-based request in the following way:

<?xml version="1.0" encoding="utf-8"?>
<GetCoverage
    xmlns="http://www.opengis.net/WCS"
    xmlns:DigitalGlobe=http://www.digitalglobe.com
    xmlns:ogc="http://www.opengis.net/ogc"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:gml="http://www.opengis.net/gml" service="WCS"
version="1.1.0" outputFormat="text/xml; subtype=gml/3.1.1" maxFeatures="100" handle="" >
    <Query typeName="DigitalGlobe:FinishedFeature" srsName="urn:x-ogc:def: crs:EPSG:4326">
        <ogc:Filter>
            <ogc:Intersects>
                <ogc:PropertyName>geometry</ogc:PropertyName>
                <gml:Envelope srsName="urn:x-ogc:def:crs:EPSG:4326"
                    xmlns:gml="http://www.opengis.net/gml">
                    <gml:lowerCorner>-90 -180</gml:lowerCorner>
                    <gml:upperCorner>90 180</gml:upperCorner>
                </gml:Envelope>
            </ogc:Intersects>
        </ogc:Filter>
    </Query>
</GetCoverage>

The <GetCoverage> element contains one or more <Query> elements, each of which contain the description of a query. The results of all queries contained in a GetCoverage request are concatenated to produce the result set.

The outputFormat attribute defines the format needed to generate the result set. The default value is GML2.

The optional maxFeatures attribute can be used to limit the number of features that a GetCoverage request retrieves. Once the maxFeatures limit is reached, the result set is truncated at that point.

Each individual query packaged in a GetCoverage request is defined using the <Query> element. The <Query> element defines which feature type to query, what properties to retrieve and what constraints (spatial and nonspatial) to apply to those properties.

The typeName attribute is used to indicate the name of the feature type or class to be queried.

The featureVersion attribute is included in order to accommodate systems that support feature versioning. A value of ALL indicates that all versions of a feature should be fetched. Otherwise, an integer, n, can be specified to return the nth version of a feature. The version numbers start at 1, which is the oldest version. If a version value larger than the largest version number is specified, then the latest version is returned. The default action shall be for the query to return the latest version. Systems that do not support versioning can ignore the parameter and return the only version that they have.

The <PropertyName> element is used to enumerate the feature properties that should be selected during a query and whose values should be included in the response to a GetCoverage request. A client application can determine the properties of a feature by making a DescribeCoverageType request before composing a GetCoverage request.

The DescribeCoverageType operation will generate a GML application schema defining the schema of the feature type. The client can then select the properties to be fetched. In addition, the client can determine which feature properties are mandatory and must be fetched in order for the service to be able to generate an instance of the feature type that will validate against the generated GML application schema. In the event that a web service encounters a query that does not select all mandatory properties of a feature, the web service will internally augment the property name list to include all necessary property names. A web service client must therefore be prepared to deal with a situation where it receives more property values than it requests.

If no <PropertyName> elements are specified, then all feature properties should be fetched.

The <Filter> element can be used to define constraints on a query. Both spatial and/or non-spatial constraints can be specified as described in the Filter Encoding Specification. If no <Filter> element is contained within the <Query> element, then the query is unconstrained and all feature instances should be retrieved.

Geography Markup Language (GML)