A GeoPackage extension is a set of one or more requirements clauses that 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. Files that use one or more extensions are by definition Extended GeoPackages. Extensions that have been already approved by OGC are presented in [registered_extensions]. However, additional extensions MAY be approved by OGC outside of the release cycle of this document.
We acknowledge that there are use cases not covered by this standard. Implementers are welcome to use the extension mechanism defined here to develop their own extensions. The extension mechanism provides advantages including discoverability (the extensions in use can be discovered by scanning a single table) and uniformity (declaring that an extension is in use indicates that a defined set of requirements are being met). However, this is a decision that should be made carefully as custom extensions do introduce interoperability risks.
OGC is unable to endorse extensions developed externally. Therefore an Extended GeoPackage containing extensions not developed by OGC will fail [r4]. However, a community of interest MAY waive that requirement in its own GeoPackage profile, with the caveat that it must bear the responsibility of endorsing the new extension(s).
Implementers that are interested in developing their own extensions are encouraged to contact OGC to ensure that the extensions are developed in accordance with OGC policies and in a way that minimizes risks to interoperability. OGC will consider adopting externally developed extensions that address a clear use case, have a sound technical approach, and have a commitment to implementation by multiple implementers.
GeoPackage extensions are documented using the GeoPackage Extension Template in [extension_template]. 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 extensions that are developed, maintained, and approved by OGC. Implementers must use their own author names to register other extensions used in Extended GeoPackages.
A GeoPackage MAY contain a table named gpkg_extensions.
If present this table SHALL be defined per clause 2.3.2.1.1 Table Definition, Table 1, 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 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 |
In an Extended GeoPackage, every extension SHALL be registered in a corresponding row in the gpkg_extensions table. 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.
Either the absence of a gpkg_extensions table or the absence of rows in the gpkg_extensions table SHALL indicate that the file is a GeoPackage (as opposed to an Extended 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).
|
Note
|
Implementers should be aware of the fact that SQLite table names are not case sensitive and that table names in |
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 [I23], 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".