The CityGML 3.0 GML schemas have been derived based on the OGC GML 3.2 standard. This means that CityGML GML instance documents must be created and exchanged in the GML version 3.2.

If for certain reasons the use of GML 3.3 is preferred, Appendix F provides an example for how to make use of GML 3.3 in CityGML instance documents. Please note, however, that software compliant to this standard might not be able to read the additional GML 3.3 content.

In the GML encoding of the CityGML 3.0 Conceptual Model, different types of objects exist: features, top-level features, and geometries. All these objects have a unique identity, thus, they can be distinguished from each other and can also be referenced from other objects.

The CityGML 3.0 Conceptual Model introduces two attributes to provide all features and top-level features with a unique identity: 1) the mandatory featureID attribute to distinguish all (top-level) features and possible multiple versions of the same real-world object and 2) an optional identifier attribute to reference specific (top-level) features independent from their actual feature version. The featureID attribute value is unique within the same CityGML dataset and also for a specific version of a feature, whereas the identifier attribute has an identical value for all versions of the same real-world object. It is recommended to use globally unique identifiers like UUID values or identifiers maintained by an organization such as a mapping agency for both attributes: for the identifier attribute, as these identifiers should remain stable over the lifetime of the real-world object, and for the featureID attribute, as this ensures that 3D city models which are integrated from different sources into e.g., one GIS or database will not have colliding featureID values and also to be able to uniquely identify a specific version of a feature using these identifiers together with a timestamp and a version number.

The two attributes are defined in the UML class AbstractFeature as part of the Core module of the CityGML 3.0 Conceptual Model. They are mapped to the predefined GML concepts gml:id and gml:identifier in the GML encoding. Table 3 lists the two identity attributes together with their definition and GML encoding, and the GML code in Listing 1 illustrates the use of the identity attributes to represent the object identity in GML instance documents. Please note that the values of the gml:id and the gml:identifier might also be identical, for example, when only a first version of the object exists. Please also note that, although the featureID attribute is defined mandatory in the CityGML 3.0 Conceptual Model, the gml:id attribute is optional according to the GML standard.

The GML encoding implements the geometry model defined in ISO 19107. This means that all geometries are derived from the class AbstractGML as well and, thus, also geometries exhibit the same unique identity as features do. The fact that geometries also have an identity is of particular importance for CityGML, since CityGML requires defining references to geometries. For these references, only the gml:id attribute is of interest. One example is the application of textures to surfaces. The textures reference the gml:ids of those LinearRings that describe the boundaries of the surface geometries (e.g., Triangle, Polygon, or a MultiSurface consisting of Polygons) to which the textures are applied. Another example is that the CityGML GML encoding allows for realizing topological relationships amongst others through referencing of shared geometries.

There are two XML concepts that are used to reference objects in GML instance documents: the XML Linking Language (XLink) and the XML Pointer Language (XPointer).

XLink allows for creating links (referred to as XLinks in this document) by providing specific attributes to XML elements for referencing other resources. The most commonly used attribute is xlink:href, the value of the attribute is the URI of the referenced document. In CityGML, however, we are mainly interested in referencing specific objects (features and geometries) within the same or an external GML instance document. To be able to reference specific objects, XPointer needs to be used in addition to XLink. For references to objects in external documents the URI value provided in the xlink:href attribute is complemented by a number sign (#) followed by the gml:id of the object to be referenced. For references to objects within the same document it is enough to provide the number sign (#) and the gml:id of the referenced object (this is also called a relative URI). This is exemplified in Listing 2, where the element <versionMember> references a <Building> feature. Since the feature is part of the same GML instance document, a relative URI is specified by simply providing the number sign and the gml:id of the building as value of the attribute xlink:href. In the context of version management, referencing features by their gml:id means that a specific feature version of a real-world object is referenced.

When using references, it is important to keep in mind that many (top-level) features in CityGML have a complex structure. This is shown in Listing 3. In general, features can have spatial and non-spatial properties that describe the features in more detail. Spatial properties are properties that have a geometry from ISO 19107 as data type (<lod2Solid> in the example). Non-spatial properties can either have a simple data type (<function> with Integer value or <creationDate> with Date value), but they can also be further specified by additional attributes, such as the height of the building that is described by further properties (<height> with the additional properties <highReference>, <lowReference>, <status>, and <value>). In addition, they can also be composed of subfeatures that contain spatial and non-spatial properties themselves (<WallSurface> with <lod2MultiSurface> geometry).

The subfeatures can be provided inline or by reference. Inline means that the subfeatures are provided directly as content of the (top-level) feature as is shown below, where the subfeature <BuildingRoom> is provided as content of the <Building> feature. In contrast, by reference means that the subfeatures are provided elsewhere in the CityGML document and are referenced from the (top-level) feature using an XLink as is described above and illustrated in Listing 2.

When modeling cities, geometries and features can be integral parts of multiple city objects. To avoid redundant modeling of these geometries and features, CityGML offers the possibility to represent geometries and features only once and to reference them from any other city object to which they belong as well. This non-redundant representation guarantees that no integrity problems occur, i.e., several differing instances of the same geometry or feature will not exist.

Three different cases for non-redundant representation need to be differentiated.

For these cases, different requirements are provided for how to encode the references in CityGML. Although these requirements impose restrictions, they facilitate at the same time reading, storing, processing, and generating of CityGML documents, because they reduce the multiple possibilities of how to represent and link features and geometries in CityGML documents to the most appropriate ones. Furthermore, top-level features can now completely be loaded in the main memory, because links to shared geometries that are part of different top-level features represented further down in the GML document do not need to be resolved any more. This also facilitates querying features and geometries using web services, as up to now queries cannot address specific parts of a geometry. Maintenance at the level of the top-level features becomes easier as well, because links between feature geometries do not need to be maintained and updated any more when a feature changes its geometry or when the feature does not exist anymore.

In these requirements, XLink represents a link at the geometry level (“geometry link”), i.e., a reference to the ID of the geometry to be reused. The link direction is always from the geometry of the space to the geometries of the space boundaries (example 1).

CityObjectRelation represents a link at the feature level (“feature link”) referencing the ID of another feature that contains a shared geometry. The explicit representation of the relation between the features facilitates spatial analyses.

In this requirement, XLink represents a link at the feature level (“feature link”), i.e., a reference to the ID of the feature being part of the natural aggregation. All features are part of a natural aggregation, i.e., features are typically represented in a data set once in physical form, either directly as part of the city model when they are top-level features (e.g., a Building), or inline as part of other (top-level) features (e.g., a BuildingRoom represented inline as part of the top-level feature Building). At the same time, the features can also occur in alternative aggregations.

Example 1: Building with Solid geometry and boundary surfaces

The building (=space) in Figure 1 is modeled in LOD2 as Solid geometry and is bounded by four WallSurfaces, one RoofSurface, and one GroundSurface (=space boundaries). All space boundaries are modeled as Polygon geometries. The Solid geometry of the building references the Polygon geometries using XLink. This example refers to Requirement /req/global/referencinggeometries2.

The GML file is available on the CityGML 3.0 GML Encoding GitHub.

The Building from the GML file is illustrated in the object diagram in Figure 2. The XLink references between the Solid geometry and the Polygon geometries are highlighted in red.

Example 2: Building with roof overhangs

The building (=space) in Figure 3 is modeled in LOD2 as Solid geometry and is bounded by four WallSurfaces, one RoofSurface, and one GroundSurface (=space boundaries). All space boundaries are modeled as Polygon geometries. The Solid geometry of the building references the Polygon geometries using XLink. This example refers to Requirement /req/global/referencinggeometries2.

The RoofSurface contains four Polygon geometries. Two of these Polygons are roof overhangs (i.e., dangling surfaces), and, thus, are not referenced by the Solid geometry of the building, as they would render the solid invalid if referenced. For this reason, an additional MultiSurface geometry is added to the building that references the dangling surfaces. In accordance with Requirement /req/global/referencinggeometries2 this MultiSurface geometry is optional. It is added to the building to provide additional information, but it is not mandatory to add this geometry.

The GML file is available on the CityGML 3.0 GML Encoding GitHub.

The Building from the GML file is illustrated in the object diagram in Figure 4. The XLink references between the Solid geometry and the Polygon geometries are highlighted in red, the XLink references between the MultiSurface geometry and the dangling surfaces in blue.

Example 3: Building with BuildingInstallation

The building (=space) in Figure 5 is modeled in LOD2 as Solid geometry and is bounded by eight WallSurfaces, four RoofSurfaces, and one GroundSurface (=space boundaries). In addition, the building has a dormer that is modeled as BuildingInstallation (=space). The building installation is modeled as MultiSurface geometry and is bounded by one RoofSurface and three WallSurfaces (=space boundaries). This example refers to Requirement /req/global/referencinggeometries2.

The space boundaries of the building and of the building installation are all modeled as Polygon geometries. The Solid geometry of the building references those Polygon geometries that represent the space boundaries of the building space using XLink. The MultiSurface geometry of the building installation references those Polygon geometries that represent the space boundaries of the building installation using XLink. Moreover, in this example, the Solid geometry of the building has to additionally reference the Polygon geometries that represent the space boundaries of the building installation using XLink to ensure a closed and watertight volume geometry. In general, however, references to the geometries of a nested space are optional, and it is allowed to not reference them in accordance with Requirement /req/global/referencinggeometries2.

The GML file is available on the CityGML 3.0 GML Encoding GitHub.

The Building from the GML file is illustrated in the object diagram in Figure 6. The XLink references from the building to the space boundaries of the building are highlighted in red, whereas those to the space boundaries of the building installation are highlighted in blue.

Example 4: Two buildings with shared boundary surface

The two buildings (=top-level features) in Figure 7 are modeled in LOD2 as Solid geometry and are bounded by Wall-, Roof-, and GroundSurfaces that are modeled as Polygon geometries. One of the WallSurfaces of the first Building shares the Polygon geometry with one of the WallSurfaces of the second Building. Both WallSurfaces might appear identical, however, the surface normals of the Polygon geometries of the WallSurfaces are pointing in opposite directions. This example refers to Requirements /req/global/referencinggeometries1 and /req/global/referencinggeometries4.

To express that the WallSurfaces of the two buildings share the Polygon geometry, the WallSurfaces reference each other using a CityObjectRelation with the relation type “shared.” Both WallSurfaces contain the Polygon geometry themselves, the second WallSurface, however, in reverse order.

The GML file is available on the CityGML 3.0 GML Encoding GitHub.

The Buildings from the GML file are illustrated in the object diagram in Figure 8. The CityObjectRelation is highlighted in red.

Example 5: Road crossing a Bridge

A Road and a Bridge (=top-level features) are modeled in LOD2, as is shown in Figure 9. The Bridge is bounded by Ground-, Roof-, and WallSurfaces that are modeled as MultiSurface geometries. The Road consists of three sections; each section is bounded by two TrafficAreas that are modeled as MultiSurface geometries as well. The RoofSurfaces of the Bridge share MultiSurface geometries with two TrafficAreas of the Road. The RoofSurfaces and the TrafficAreas are geometrically identical, but they differ semantically. This example refers to Requirements /req/global/referencinggeometries1 and /req/global/referencinggeometries4.

To express that the RoofSurfaces share MultiSurface geometries with two TrafficAreas, they reference each other using CityObjectRelations with the relation type “shared.”

The GML file is available on the CityGML 3.0 GML Encoding GitHub.

The Road and Bridge from the GML file are illustrated in the object diagram in Figure 10. The CityObjectRelations are highlighted in red.

Example 6: Parking garage

The parking garage in Figure 11 is modeled in LOD2 as a building (=top-level feature) with Floor-, Roof-, and WallSurfaces that are modeled as MultiSurface geometries. The parking garage contains a Road with Sections and TrafficAreas that are modeled as MultiSurface geometries as well. The Floor- and RoofSurface of the Building share MultiSurface geometries with the Sections and TrafficAreas of the Road. This example refers to Requirements /req/global/referencinggeometries1 and /req/global/referencinggeometries4.

To express the sharing of MultiSurface geometries between the Roof-/WallSurfaces and the Sections/TrafficAreas, they reference each other using CityObjectRelations with the relation type “shared.”

The GML file is available on the CityGML 3.0 GML Encoding GitHub.

Example 7: A specific version of a city model

A Version feature groups, for instance, different versions of city objects that are valid within a specific time period. The city model represents the natural aggregation of these versioned city objects, whereas the Version feature represents the alternative aggregation. Thus, the versioned city objects are represented inline as part of the city model, whereas they are referenced by the Version feature using XLink references. This example refers to Requirement /req/global/alternativeaggregations.

Example 8: CityObjectGroups

A CityObjectGroup groups existing city objects that are usually represented inline somewhere else in the data set. Thus, CityObjectGroups represent alternative aggregations and have to use XLink to reference the city objects they are grouping. This example refers to Requirement /req/global/alternativeaggregations.

Referencing features from multiple and different contexts

The same feature can also be used in multiple and different contexts without being able to distinguish between a natural and alternative aggregations. Nevertheless, also in such scenarios it is recommended to store the feature only once and to reference it from every other context using XLinks in order to avoid duplication and to ensure a non-redundant representation. For this reason, referencing features using XLinks is allowed beyond the scope of Requirement /req/global/alternativeaggregations even between top-level features. The following examples illustrate some of these scenarios.

Example 9: Building rooms belonging to a Storey

BuildingRooms are usually represented inline as part of the Building they belong to. In addition, Storeys can group BuildingRooms to indicate which BuildingRoom belongs to which Storey. In this case, when the BuildingRooms are already represented inline the Building, the Storeys would reference the BuildingRooms using XLinks to avoid duplication. However, since there is no clear distinction between a natural and alternative aggregations in this example, the BuildingRooms could also be contained inline the corresponding Storey and be referenced from the Building feature.

Example 10: A Building installation spanning across several Building Parts

Installations that are spanning across several building parts are to be physically modeled as part of one building part. All other building parts reference the installation using XLinks, expressing in this way that the installation does not exclusively belong to one building part only. Since there is no natural or alternative aggregation in this example either, one can choose which building part should contain the installation and which building parts should rather use XLink references.

Example 11: Intersection as part of two Roads

In Figure 12, two Roads (=top-level features) are shown both of which have two Sections and one Intersection. The two Roads cross each other at the Intersection. Although the Intersection and, thus, also its geometry is shared by both Roads, it exists in reality only once; i.e., the Intersection is an integral part of both Roads. In contrast to Requirement /req/global/referencinggeometries4, this should not be expressed by duplicating the Intersection to represent it inline of both Roads and link the duplicates using CityObjectRelations. Instead, the Intersection should be represented inline as part of one Road (here: Road 2) and be referenced by the other Road (here: Road 3) using an XLink that references the ID of the Intersection feature. Also in this example, the roads cannot be semantically distinguished as natural or alternative aggregation of the Intersection.

The GML file is available on the CityGML 3.0 GML Encoding GitHub.

The two Roads and the Intersection from the GML file are illustrated in the object diagram in Figure 13. The XLink reference is highlighted in red.