Testbed-12 TopoJSON, GML Engineering Report

This OGC document evaluates TopoJSON as an encoding that may be delivered across a common, standard OGC service interface such as WFS.

All questions regarding this document should be directed to the editor or the contributors:

This Engineering Report recommends further investigation into TopoJSON as part of an overall API for representing geospatial Resources as GeoJSON. If some level of integration of TopoJSON and WFS can be achieved, interoperability for the geospatial community will be enhanced - resulting in more potential data reuse, reduced data and application development costs and enhanced understanding of shared environments represented as both features and arcs.

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

Rather than representing geometries discretely, geometries in TopoJSON files are stitched together from shared line segments called arcs.

The software component that can invoke an operation from a service.

One of a sequence of n numbers designating the position of a point in n-dimensional space.

An application object that represents a physical entity, e.g. a building, a river, or a person. A feature may or may not have geometric aspects.

GeoJSON is an open standard format designed for representing simple geographical features, along with their non-spatial attributes, based on JavaScript Object Notation. The features include points (therefore addresses and locations), line strings (therefore streets, highways and boundaries), polygons (countries, provinces, tracts of land), and multi-part collections of these types.

The geometry data type is used to house information on recognized objects, like points, lines, and polygons.

The named set of operations that characterize the behavior of a service.

The specification of a transformation or query that a service may be called to execute.

The distinct part of the functionality that is provided by an entity through interfaces.

TopoJSON is an extension of GeoJSON that encodes topology. As its name implies, TopoJSON is a topological geospatial data format. In contrast to a geometry, where each shape is encoded with separate (and often redundant) arrays of coordinates, a topology encodes sequences of coordinates in line fragments called arcs that can be shared. For example, the border between California and Nevada is an arc that is shared by both polygons. The main benefit of a topology is that it improves shape simplification by avoiding artifacts that would be caused by simplifying shapes independently. It also enables applications like map coloring and selective meshing, and makes the format more compact by removing redundant coordinates.

The Web Feature Service standard specifies the behavior of a service that provides transactions on and access to geographic features in a manner independent of the underlying data store.

Some more frequently used abbreviated terms in this document include:

This OGC document evaluates TopoJSON as an encoding that may be delivered across a common, standard OGC service interface such as WFS.

TopoJSON is an extension of GeoJSON that encodes topology. Rather than representing geometries discretely, geometries in TopoJSON files are stitched together from shared line segments called arcs. Arcs are sequences of points, while line strings and polygons are defined as sequences of arcs.

An encoding sample from https://github.com/mbostock/topojson/wiki/Introduction is shown below.

The main benefit of TopoJSON is that each arc is defined only once, but can be referenced several times by different shapes, thus reducing redundancy and decreasing the file size. It also enables applications like map coloring and selective meshing, and makes the format more compact by removing redundant coordinates.

A TopoJSON encoding always consists of a single topology object. A topology may contain any number of named geometry objects. The term TopoJSON object may refer to either a topology or a geometry object it contains. To include information on the coordinate range for a topology or geometry a TopoJSON object may have a member named “bbox” or Bounding Box. A geometry is a TopoJSON object where the type member’s value is one of the following strings: “Point”, “MultiPoint”, “LineString”, “MultiLineString”, “Polygon”, “MultiPolygon”, or “GeometryCollection”.

A single TopoJSON file can contain multiple feature collections without duplication, such as states and counties. Or, a TopoJSON file can efficiently represent both polygons (for fill) and boundaries (for stroke) as two feature collections that share the same arc mesh. As a result, TopoJSON is substantially more compact than GeoJSON. The shapefile below of U.S. counties is 2.2M as a GeoJSON file, 436K as a boundary mesh, a reduction of 80.4% even without simplification. TopoJSON can also be more efficient to render since shared control points need only be projected once. To further reduce file size, TopoJSON uses fixed-precision delta-encoding for integer coordinates rather than floats. Like GeoJSON, TopoJSON files are easily modified in a text editor and amenable to gzip compression.

In TopoJSON the Bounding Box member includes information on the coordinate range for a topology or geometry. The value of the bbox member must be a 2*n array where n is the number of dimensions represented in the contained geometries, with the lowest values for all axes followed by the highest values. The axes order of a bbox follows the axes order of geometries.

The OGC Web Feature Service (WFS) Implementation Specification allows a client to retrieve geospatial data encoded in Geography Markup Language (GML) and other formats from multiple Web Feature Services. The specification defines operations for data access and manipulation operations on geographic features, using HTTP as the distributed computing platform. Via these interfaces, a Web user or service can combine, use and manage geodata — the feature information behind a map image.

This International Standard specifies the behavior of a service that provides transactions on and access to geographic features in a manner independent of the underlying data store. It specifies discovery operations, query operations, locking operations, transaction operations and operations to manage stored parameterized query expressions:

This International Standard defines eleven operations:

Some WFS servers may also support additional non-GML feature encodings and client applications may access them using the outputFormat parameter domains. However, the WFS International Standard does not describe how a server would operate upon such encodings. This is an important distinction for TopoJSON interoperability testing, demonstration and operational implementation.

The OGC Filter Encoding Implementation Specification describes an XML and KVP encoding of a system neutral syntax for expressing projections, selection and sorting clauses collectively called a ‘query expression’. As background, a fundamental operation performed on a set of data or resources is that of querying in order to obtain a subset of the data which contains certain desired information that satisfies some query criteria and which is also, perhaps, sorted in some specified manner.

This International Standard defines the XML encoding for the following predicates.

Given the structure of WFS operations, the WFS OutputFormat and BBox parameters of the Getfeature request may be potential 'integration points' for TopoJSON. The source data for TopoJSON WFS output formats may be common feature representations currently used on WFS including GML and GeoJSON.

The optional WFS outputFormat parameter specifies the format used to encode feature data in the response to a query operation. The default value is "application/gml+xml; version=3.2" indicating that feature data in the response document shall be encoded using GML (see ISO 19136:2007). Every WFS that conforms to the WFS International Standard must support this default value.

However, a WFS may advertise additional values for the outputFormat parameter in its capabilities document indicating that multiple output formats, including previous versions of GML and other encodings like TopoJSON, are supported.

Given the structure of WFS operations, the WFS OutputFormat and BBox parameters of the Getfeature request were used as integration points for TopoJSON.

TopoJSON WFS output format may augment common feature representations currently used on WFS such as GeoJSON, shown below.

The optional WFS outputFormat parameter specifies the format used to encode feature data in the response to a query operation. The default value is "application/gml+xml; version=3.2" indicating that feature data in the response document shall be encoded using GML (see ISO 19136:2007). Every WFS that conforms to the WFS International Standard must support this default value.

A WFS may advertise additional values for the outputFormat parameter in its capabilities document indicating that multiple output formats, including previous versions of GML and other encodings like TopoJSON, are supported.

This section described the WFS implemented to satisfy the TopoJSON WFS requirement for Testbed 12.

This experiment was performed using one WFS from The Carbon Project. The table below lists the product version and endpoint of the server.

Capabilities of the prototype CarbonCloud server for TopoJSON are listed below.

The Carbon Project’s prototype client supporting Sync, Compression and TopoJSON for Testbed 12 is shown below.

In Testbed 12 the ability of WFS to support TopoJSON outoutformat was assessed by loading test data, including polygons representing schools in San Francisco, converting the test data to TopoJSON in response to a properly formated request sent to the Endpoint listed above.

The resulting TopoJSON encoding returned by the WFS is shown below.

Technology Integration Experiments conducted in Testbed 12 indicate -

TopoJSON is an extension of GeoJSON that encodes topology, mainly for size reduction purposes. Feature data like interconnected political regions represented as polygons can gain size reduction advantages using TopoJSON. However, processing TopoJSON may require different client tools than GeoJSON, and the format is often converted into GeoJSON after transfer.

It is also to note that although a 'GetFeatures' operation is used to access the outputFormat parameter for TopoJSON, the result set is technically an arc, not a feature.

However, the overall movement in the open geospatial community is towards representing geospatial assets as Resources instead of Services. JSON is a key encoding format for future geospatial Resources.

Accordingly, this Engineering Report recommends further investigation into TopoJSON as part of an overall API for representing geospatial Resources as GeoJSON. If some level of integration of TopoJSON and WFS can be achieved, interoperability for the geospatial community will be enhanced - resulting in more potential data reuse, reduced data and application development costs and enhanced understanding of shared environments represented as both features and arcs.