A GeoPackage extension is a set of one or more requirements clauses that are documented by filling out the GeoPackage Extension Template in [extension_template]. A GeoPackage Extension either profiles / extends existing requirements clauses in the GeoPackage standard or adds new requirements clauses. Existing requirement clause extension examples include additional geometry types, additional SQL geometry functions, and additional tile image formats. New requirement clause extension examples include spatial indexes, triggers, additional tables, other BLOB column encodings, and other SQL functions.
GeoPackage extensions are identified by a name of the form <author>_<extension name> where <author> indicates the person or organization that developed and maintains the extension. The author value "gpkg" is reserved for GeoPackage extensions that are developed and maintained by OGC and used in GeoPackages. Implementers use their own author names to register other extensions[1] used in Extended GeoPackages.
A GeoPackage MAY contain a table or updateable view named gpkg_extensions. If present this table SHALL be defined per clause 2.3.2.1.1 Table Definition, GeoPackage Extensions Table or View Definition (Table or View Name: gpkg_extensions), and [gpkg_extensions_sql]. An extension SHALL NOT modify the definition or semantics of existing columns. An extension MAY define additional tables or columns. An extension MAY allow new values or encodings for existing columns.
The gpkg_extensions table or updateable view in a GeoPackage is used to indicate that a particular extension applies to a GeoPackage, a table in a GeoPackage or a column of a table in a GeoPackage.
An application that accesses a GeoPackage can query the gpkg_extensions table instead of the contents of all the user data tables to determine if it has the required capabilities to read or write to tables with extensions, and to "fail fast" and return an error message if it does not.
| Column Name | Col Type | Column Description | Null | Key |
|---|---|---|---|---|
|
TEXT |
Name of the table that requires the extension. When NULL, the extension is required for the entire GeoPackage. SHALL NOT be NULL when the column_name is not NULL. |
yes |
Jointly Unique |
|
TEXT |
Name of the column that requires the extension. When NULL, the extension is required for the entire table. |
yes |
Jointly Unique |
|
TEXT |
The case sensitive name of the extension that is required, in the form <author>_<extension_name>. |
no |
Jointly Unique |
|
TEXT |
Permalink, URI, or reference to a document that defines the extension |
no |
|
|
TEXT |
Indicates scope of extension effects on readers / writers: 'read-write' or 'write-only' in lowercase. |
no |
Every extension of a GeoPackage SHALL be registered in a corresponding row in the gpkg_extensions table. The absence of a gpkg_extensions table or the absence of rows in the gpkg_extensions table SHALL both indicate the absence of extensions to a GeoPackage.
Values of the gpkg_extensions table_name column MAY reference values in the gpkg_contents table_name, reference new tables required by that extension, or be NULL (to indicate an extension that requires no new tables).
The column_name column value in a gpkg_extensions row SHALL be the name of a column in the table specified by the table_name column value for that row, or be NULL.
Each extension_name column value in a gpkg_extensions row SHALL be a unique case sensitive value of the form <author>_<extension_name> where <author> indicates the person or organization that developed and
maintains the extension. The valid character set for <author> SHALL be [a-zA-Z0-9].
The valid character set for <extension_name> SHALL be [a-zA-Z0-9_].
An extension_name for the "gpkg" author name SHALL be one of those defined in this encoding standard or in an OGC document (e.g. Best Practices Document or Encoding Standard) that extends it.
The author value "gpkg" is reserved for GeoPackage extensions that are developed and maintained by OGC. GeoPackage implementers use their own author names to register other extensions.
The definition column value in a gpkg_extensions row SHALL contain a permalink, URI [23], or reference to a document defining the extension as per the [extension_template].
Examples of how to fill out the GeoPackage Extension Template in [extension_template] are provided in Annex F. This column is not unique because an extension may define multiple tables.
The scope column value in a gpkg_extensions row SHALL be lowercase "read-write" for an extension that affects both readers and writers, or "write-only" for an extension that affects only writers.
Some extensions do not impose any additional requirements on software that accesses a GeoPackage in a read-only fashion. An example of this is an extension that defines an SQL trigger that uses a non-standard SQL function defined in a GeoPackage SQLite Extension. Triggers are only invoked when data is written to the GeoPackage, so usage of this type of extension can be safely ignored for read-only access. This is indicated by a gpkg_extensions.scope column value of "write_only".