1. Introduction

The purpose of this guide is present a set of capabilities that could be implemented through GeoPackage software. While the GeoPackage Encoding Standard does not specify software requirements, there are certain expectations that GeoPackage creators had when the standard was developed, as well as expectations that have emerged from the user community as GeoPackage has been more broadly adopted. This guide attempts to articulate those expectations so that developers produce consistent software.

Warning

This document is not an OGC Standard and may not be referred to as such. This document is an implementation guide and is not an official position of the OGC membership. It is distributed for informational purposes only and is subject to change without notice.

Terms and Definitions

GeoPackage Software - software capable of reading and/or writing GeoPackages

GeoPackage Client - software capable of (at a minimum) accessing GeoPackage content in a read-only mode.

GeoPackage-writing Software - software capable of (at a minimum) producing or modifying a GeoPackage

Note

Where appropriate, the roles of GeoPackage-writing software (producers and editors) are differentiated from clients.

Capability Levels

Where possible, the guidelines are presented in a tiered approach using multiple capability levels.

  • Capability Level 0 indicates a fair and reasonable use of GeoPackage for closed scenarios but that will not provide interoperability with other use cases or applications and therefore falls short of what can be considered compliant.

  • Capability Level 1 indicates the minimum level of interoperability.

  • Capability Level 2 indicates an increased level of capability and compliance.

  • Capability Level 3 generally indicates the long-term vision for GeoPackage support.

Where possible, the guide also presents an example client operation for each capability level. If a GeoPackage client can perform the indicated operation, it is capable of meeting this capability level. The compliance of GeoPackage-writing software is easier to define: if it can produce a GeoPackage that can be used in place of the file referenced in the sample, then it is compliant.

This approach allows developers to develop their software incrementally, achieving useful capabilities at a pace aligned with their own roadmaps and business models. There is no expectation that any particular piece of software support any particular capability or capability level. Consider this more of a catalog or taxonomy for GeoPackage support capabilities, things that could be supported in GeoPackage software.

Note

This approach also gives guidance back to the SWG – some capability levels are not achievable today and these will be considered by the SWG for higher priority in future activities.

Core

1. Contents

GeoPackages are self-describing and GeoPackage software should use this feature of the format to express (for GeoPackage-writing software) and determine (for clients) what content to load.

1.1. Level 0

GeoPackage client loads and utilizes one or more sets of contents (tiles or features) using hard-coded table names.

1.2. Level 1

GeoPackage client loads and utilizes a single set of contents (tiles or features) by picking the first item in gpkg_contents.

Tip

Example (tiles): Open https://portal.opengeospatial.org/files/?artifact_id=74983. Client loads the tiles without interaction with the user.

1.3. Level 2

GeoPackage client loads the contents from gpkg_contents, presents the user a list of contents to utilize, and allows the user to open one or more of them.

Tip

Open https://portal.opengeospatial.org/files/?artifact_id=74984. Client presents a list with two contents (one tiles, one feature) User can select one or both contents for use.

1.4. Level 3

GeoPackage client loads a list of OWS Context files, each representing a specific use case or scenario, and allows the user to select one for use.

Note

The specification for this capability is still being developed.

2. Spatial Reference System (SRS)

GeoPackages are expected to use SRSs to ensure the consistency of coordinates.

2.1. Level 0

GeoPackage contents are utilized without recognition of SRSs.

2.2. Level 1

GeoPackage software supports the three built-in SRSs of EPSG::4326 (WGS-84), 0 (undefined geographic coordinate reference systems), and -1 (undefined Cartesian coordinate reference systems) that are listed by default in the gpkg_spatial_ref_sys table.

Tip

Open https://portal.opengeospatial.org/files/?artifact_id=74984. This GeoPackage contains tiles and features, both in EPSG::4326. The client should be able to use these contents normally.

2.3. Level 2

GeoPackage software supports arbitrary SRSs that are listed in gpkg_spatial_ref_sys. The software performs any transformations needed if multiple SRSs are in use at the same time.

Tip

Example (features): Open http://www.geopackage.org/data/sample1_2.gpkg. This GeoPackage contains features in different SRSs. The client should be able to use these contents normally.

2.4. Level 3

GeoPackage software supports arbitrary SRSs that are encoded in CRS WKT2 using the WKT for CRS Extension.

Tip

Example 1 (features): Open http://www.geopackage.org/data/sample1_2F10.gpkg. This GeoPackage contains features in different SRSs encoded using CRS WKT2. The client should be able to use these contents normally.

Features Option

The actual utilization of feature data is very open-ended. Many systems visualize feature data, but feature data is also well-suited to a number of analysis operations.

1. Geometries

1.1. Level 0

GeoPackage software supports at least one simple geometry type (point, line, or polygon).

1.2. Level 1

GeoPackage software supports all six "simple features" primitive geometry types (point, line, polygon, multipoint, multiline, and multipolygon).

Tip

Open http://www.geopackage.org/data/sample1_2.gpkg. The client should be able to handle all of the 2D features (point2d, linestring2d, etc.) in this GeoPackage.

1.3. Level 2

GeoPackage software supports geometry collections (of arbitrary size and complexity) and generic geometries. It also supports 3D and 4D geometries using the Z and M coordinates. GeoPackage-writing software also supports the RTree Spatial Index Extension and uses this extension to improve spatial querying performance for clients.

Tip

Open http://www.geopackage.org/data/sample1_2.gpkg. The client should be able to handle all of the features in this GeoPackage.

1.4. Level 3

GeoPackage software supports extended geometry types using the Nonlinear Geometry Types Extension.

Tip

Open http://www.geopackage.org/data/gdal_sample_v1.2_spi_nonlinear_webp_elevation.gpkg. The client should be able to handle all of the features in this GeoPackage.

Attributes of Feature Data

1. Level 0

GeoPackage software supports hard-coded attributes.

2. Level 1

GeoPackage software supports arbitrary attributes of any name and supported data type. GeoPackage clients read these attributes from the user-defined feature table and present them to the user or utilize them where appropriate.

Tip

Open http://www.geopackage.org/data/sample1_2.gpkg. The client should be able to use all of the attributes on the features and their attributes in the "counties" layer.

3. Level 2

GeoPackage software supports arbitrary attributes that are defined using the Schema Extension. Where appropriate, the schema defines metadata that improves the readability of visualizations and query results.

Note

There is currently no example available at this time.

Feature Visualization

Not all GeoPackage clients visualize feature data, but those that do must consider how the styles (portrayal rules) are produced and selected by the user.

1. Level 1

Feature geometries and/or attributes are visualized using hard-coded styling rules.

Tip

Open https://portal.opengeospatial.org/files/?artifact_id=74984 and select the vegetation layer. The client then renders the features using hard-coded styling rules.

2. Level 2

Feature geometries and/or attributes are styled through the GeoPackage client using styling rules that are provided by the client or defined by the user through the client.

Tip

Open https://portal.opengeospatial.org/files/?artifact_id=74984 and select the vegetation layer. The client asks the user to select a styling rules set or to create one. The client then renders the features using the selected styling rules.

3. Level 3

Feature styles are encoded as part of Contexts (see above) that are included as part of the GeoPackage.

Note

This capability is still under development.

Tiles Option

Tiled raster data is primarily designed for visualization purposes.

##Tile Matrix Sets

.1. Level 0

GeoPackage software exclusively supports the Google Maps-compatible Tile Matrix Set.

Tip

Load the "rivers_tiles" tile pyramid from http://geopackage.org/data/rivers.gpkg. Zoom levels 0-6 should be available.

.2. Level 1

GeoPackage software supports any tile matrix set that has a power-of-2 interval between zoom levels. This tile matrix set may have global or regional extents.

Tip

Load the "MGCPPREVIEW5SKU" tile pyramid from https://portal.opengeospatial.org/files/?artifact_id=74863 Zoom levels 9-16 should be available. TODO: add additional sample files to this example.

.3. Level 2

GeoPackage software supports tile matrix sets with arbitrary zoom levels using the Zoom Other Intervals extension. When useful, this extension is used to preserve the quality of the highest zoom level and minimize the bloat of the GeoPackage.

Note

There is currently no example available at this time.

4. Tile Encoding

4.1. Level 1

GeoPackage software supports PNG and JPG tiles.

Note

Client support for JPG and PNG is so ubiquitous that it is unlikely that a visualization client would not be able to display either.

4.2. Level 2

GeoPackage-writing software produces heterogeneous tile sets for imagery overlays, using JPG files (with their superior compression) for central tiles and PNG (with alpha channel transparency) for border tiles so that the user is able to see the underlying layers at the edge of the imagery coverage area.

Note

Because of the aforementioned ubiquity of PNG and JPG support, this is more of a challenge for GeoPackage-writing software.

4.3. Level 3

GeoPackage software supports the WebP format using the Tiles Encoding WebP Extension. GeoPackage-writing software uses this format to reduce GeoPackage size when the expected clients are known to support it.

Tip

Load the "byte_webp" tile pyramid from http://www.geopackage.org/data/gdal_sample_v1.2_spi_nonlinear_webp_elevation.gpkg. A single tile should be available.

5. Tile Visualization

This section applies to generic map capabilities of a GeoPackage client.

5.1. Level 0

A GeoPackage client can render a fixed view of tiled raster data.

5.2. Level 1

A GeoPackage client can display the raster data (centered on the extents specified in the corresponding row of gpkg_contents), pan, switch zoom levels, and zoom to global extent.

Note

Any tiles example could be used to demonstrate the desired behavior.

5.3. Level 2

A GeoPackage client can display multiple tile matrix sets simultaneously, transforming into a single SRS if needed.

Note

There is currently no example available at this time.

5.4. Level 3

When a GeoPackage is loaded for visualization via an OWS Context (see above), the default view is read from the Context.

Note

The specification for this capability is still being developed.

6. Attributes Option

Attributes tables are non-spatial data that may be joined as part of a view. This eliminates a potential source of redundancy and bloat in GeoPackage files.

6.1. Level 0

Attribute information is duplicated across multiple feature tables instead of being stored in a separate attributes table.

6.2. Level 1

GeoPackage-writing software creates one or more attributes tables. GeoPackage clients support joining these attributes with existing feature tables.

6.3. Level 2a

GeoPackage-writing software creates views to join feature tables and attribute tables. (GeoPackage clients are then able to utilize these views as they would a table, but only in a read-only mode.)

6.4. Level 2b

GeoPackage-writing software uses the "updatable view" technique to produce updatable views that combine the flexibility of joining multiple tables together with the insert/update/delete capabilities of a table. (GeoPackage clients are then able to utilize these views as they would a table.)

Note

While this capability is possible today, there is currently not clear guidance on how this should be done.

6.5. Level 3

GeoPackage software supports many-to-many relationships between features and attributes using the Related Tables Extension.

Note

There is currently no example available at this time.

7. Extensions

7.1. Metadata

7.1.1. General Use

Level 1

GeoPackage-writing software fully populates the gpkg_contents table for each set of contents and GeoPackage clients present this information to the user.

Note

Any compliant GeoPackage could be used to demonstrate the desired behavior.
Level 2

GeoPackage software supports the Metadata Extension. GeoPackage-writing software populates the two metadata tables with information regarding each dataset and GeoPackage clients make this metadata available to the user upon request.

Tip

Load https://portal.opengeospatial.org/files/?artifact_id=74984. There is metadata for the whole GeoPackage and for the "Veg_DC" layer.
Level 3

GeoPackage software supports hierarchical metadata in conjunction with the Metadata Extension. Metadata is traceable from the tile or feature level up to the GeoPackage level.

Note

There is currently no example available at this time.

8. Data Provenance

8.1. Level 0

By default, GeoPackage does not indicate the provenance of the data inside it.

8.2. Level 1

GeoPackage Providers version GeoPackage data when publishing it. As part of this process, the provider should provide a checksum with the file so that the recipient can confirm that the file is correct and has not been tampered with.

Note

This capability is outside of the scope of the GeoPackage Encoding Standard so there is no example for it.

8.3. Level 2

GeoPackage Providers add a row to gpkg_metadata with a md_scope of "dataset" for each dataset listed in gpkg_contents.

Note

There is not currently a consensus on the specification for the metadata document to be used here.

8.4. Level 3

GeoPackage Providers add a row to gpkg_metadata with a md_scope of "collectionSession" for each independent editing session so that individual edits can be traced to a specific editing session.

Note

There is not currently a consensus on the specification for the metadata document to be used here.

9. Change Management

9.1. Level 0

By default, GeoPackage has no capabilities for change management. However, in conjunction with Level 3 of Data Provenance (see above),

9.2. Level 1

For each table that is modified, a GeoPackage Producer adds a row to gpkg_metadata_reference with a reference_scope of "table". This row is linked to a row in gpkg_metadata with a md_scope of "collectionSession". A GeoPackage Client can then read the gpkg_metadata_reference table to determine all tables that have been modified.

Note

There is currently no example available at this time.

9.3. Level 2

For each row that is modified, a GeoPackage Producer adds a row to gpkg_metadata_reference with a reference_scope of "row". This row is linked to a row in gpkg_metadata with a md_scope of "collectionSession". A GeoPackage Client can then read the gpkg_metadata_reference table to determine all rows that have been modified.

Note

There is currently no example available at this time.

9.4. Level 3

For each column value that is modified, a row is added to gpkg_metadata_reference with a reference_scope of "row/col". This row is linked to a row in gpkg_metadata with a md_scope of "collectionSession". A GeoPackage Client can then read the gpkg_metadata_reference table to determine all column values that have been modified.

Note

There is currently no example available at this time.

10. Vector Tiles

10.1. Attributes

10.1.1. Level 0

When no attributes are available in the vector tiles, the application can only display features with arbitrary styles.

10.1.2. Level 1

GeoPackage software embeds the attributes in the encoded files (Mapbox or GeoJSON).

Note

There is currently no example available at this time.

10.1.3. Level 2

GeoPackage software uses the attributes_table_name column of gpkgext_vt_layers to indicate the name of an attributes table that contains attributes for the features in that layer. This allows the attributes to be encoded more efficiently, without being duplicated across each vector tile that contains the feature.

Note

There is currently no example available at this time.

10.1.4. Level 3

GeoPackage software uses the Related Tables Extension to correlate features (by their feature ID) with tiles containing the feature. This allows GeoPackage clients to perform queries without having to search all of the available vector tiles to find tiles containing the features that satisfy the query.

Note

There is currently no example available at this time.

10.2. Tiled Gridded Coverage Data

Warning

TODO