The required capabilities specified in this clause serve as the base for options specified in clause [_options] and extensions specified in clause [registered_extensions]. All gpkg_* tables and views and all tiles user data tables specified in this standard SHALL have only the specified columns and table constraints. Any features user data tables MAY have columns in addition to those specified. All specified table, view, column, trigger, and constraint name values SHALL be lowercase.
The mandatory core capabilities defined in sub clauses and requirement statements of this clause SHALL be implemented by every GeoPackage and GeoPackage SQLite Configuration.
The SQLite software library provides a self-contained, single-file, cross-platform, serverless, transactional, open source RDBMS container. The GeoPackage standard defines a SQL database schema designed for use with the SQLite software library. Using SQLite as the basis for GeoPackage simplifies production, distribution and use of GeoPackages and assists in guaranteeing the integrity of the data they contain.
"Self-contained" means that container software requires very minimal support from external libraries or from the operating system. "Single-file" means that a container not currently opened by any software application consists of a single file in a file system supported by a computing platform operating system. "Cross-platform" means that a container file MAY be created and loaded with data on one computing platform, and used and updated on another, even if they use different operating systems, file systems, and byte order (endian) conventions. "Serverless" means that the RDBMS container is implemented without any intermediary server process, and accessed directly by application software. "Transactional" means that RDBMS transactions guarantee that all changes to data in the container are Atomic, Consistent, Isolated, and Durable (ACID) despite program crashes, operating system crashes, and power failures.
A GeoPackage SHALL contain a value of 0x47504B47 ("GPKG" in ASCII) in the "application_id" field of the SQLite database header to indicate that it is a GeoPackage. [3] A GeoPackage SHALL contain an appropriate value in "user_version" field of the SQLite database header to indicate its version. The value SHALL be in integer with a major version, two-digit minor version, and two-digit bug-fix. For GeoPackage Version 1.2 this value is 0x000027D8 (the hexadecimal value for 10200). [4]
The maximum size of a GeoPackage file is about 140TB. In practice a lower size limit MAY be imposed by the filesystem to which the file is written. Many mobile devices require external memory cards to be formatted using the FAT32 file system which imposes a maximum size limit of 4GB.
A GeoPackage SHALL have the file extension name ".gpkg".
It is RECOMMENDED that Extended GeoPackages use the file extension ".gpkx", but this is NOT a GeoPackage requirement.
A GeoPackage SHALL only contain data elements, SQL constructs and GeoPackage extensions with the "gpkg" author name specified in this encoding standard.
In order to guarantee maximum interoperability between applications, GeoPackages should not contain data elements (tables or columns), SQL constructs (data types, indexes, constraints or triggers) or extensions that are not specified in this encoding standard. SQLite databases that use constructs from the GeoPackage standard but extend those constructs to contain elements not specified in the core GeoPackage standard are referred to as Extended GeoPackages throughout this standard.
The columns of tables in a GeoPackage SHALL only be declared using one of the data types specified in table GeoPackage Data Types.
| Data Type | Size and Description | BOOLEAN | A boolean value representing true or false. Stored as SQLite INTEGER with value 0 for false or 1 for true | TINYINT | 8-bit signed two’s complement integer. Stored as SQLite INTEGER with values in the range [-128, 127] |
|---|---|---|---|---|---|
SMALLINT |
16-bit signed two’s complement integer. Stored as SQLite INTEGER with values in the range [-32768, 32767] |
MEDIUMINT |
32-bit signed two’s complement integer. Stored as SQLite INTEGER with values in the range [-2147483648, 2147483647] |
INT, INTEGER |
64-bit signed two’s complement integer. Stored as SQLite INTEGER with values in the range [-9223372036854775808, 9223372036854775807] |
FLOAT |
32-bit IEEE floating point number. Stored as SQLite REAL limited to values that can be represented as a 4-byte IEEE floating point number |
DOUBLE, REAL |
64-bit IEEE floating point number. Stored as SQLite REAL |
TEXT{(maxchar_count)} |
Variable length string encoded in either UTF-8 or UTF-16, determined by PRAGMA encoding; see http://www.sqlite.org/pragma.html#pragma_encoding. The optional maxchar_count defines the maximum number of characters in the string. If not specified, the length is unbounded. The count is provided for informational purposes, and applications MAY choose to truncate longer strings if encountered. When present, it is best practice for applications to adhere to the character count. Stored as SQLite TEXT |
BLOB{(max_size)} |
Variable length binary data. The optional max_size defines the maximum number of bytes in the blob. If not specified, the length is unbounded. The size is provided for informational purposes. When present, it is best practice for applications adhere to the maximum blob size. Stored as SQLite BLOB |
<geometry_type_name> |
Geometry encoded as per clause [_geometry_encoding]. <geometry type_name> is one of the geometry types listed in [geometry_types] encoded per clause 2.1.3 or a user-defined geometry type encoded per clause 3.1.2 and [extension_geometry_encoding]. Geometry Types XY, XYZ, XYM and XYZM geometries use the same data type. Stored as SQLite BLOB |
DATE |
ISO-8601 date string in the form YYYY-MM-DD encoded in either UTF-8 or UTF-16. See TEXT. Stored as SQLite TEXT |
The SQLite PRAGMA integrity_check SQL command SHALL return "ok" for a GeoPackage file. [5]
The SQLite PRAGMA foreign_key_check SQL with no parameter value SHALL return an empty result set indicating no invalid foreign key values for a GeoPackage file.
A GeoPackage SQLite Configuration SHALL provide SQL access to GeoPackage contents via SQLite version 3 [6] software APIs. [6]
The SQLite [8] library has many compile time and run time options that MAY be used to configure SQLite for different uses. Use of SQLITE_OMIT options is not recommended because certain elements of the GeoPackage standard depend on the availability of SQLite functionality at runtime.
Every GeoPackage SQLite Configuration SHALL have the SQLite library compile time options specified in clause 1.1.1.2.2 table [every_gpkg_sqlite_config_table].
A GeoPackage SHALL include a gpkg_spatial_ref_sys table per clause 1.1.2.1.1 Table Definition, Table Spatial Ref Sys Table Definition and Table [gpkg_spatial_ref_sys_sql].
A table named gpkg_spatial_ref_sys is the first component of the standard SQL schema for simple features described in clause [sfsql_intro] below.
The coordinate reference system definitions it contains are referenced by the GeoPackage gpkg_contents and gpkg_geometry_columns tables to relate the vector and tile data in user tables to locations on the earth.
The gpkg_spatial_ref_sys table includes the columns specified in SQL/MM (ISO 13249-3) [12] and shown in Spatial Ref Sys Table Definition below containing data that defines spatial reference systems.
Views of this table MAY be used to provide compatibility with the SQL/MM [12] (see [sqlmm_gpkg_spatial_ref_sys_sql]) and OGC Simple Features SQL [9][10][11] (Table 21) standards.
| Column Name | Column Type | Column Description | Null |
|---|---|---|---|
Key |
|
TEXT |
Human readable name of this SRS |
no |
|
INTEGER |
|
Unique identifier for each Spatial Reference System within a GeoPackage |
no |
PK |
|
TEXT |
Case-insensitive name of the defining organization e.g. EPSG or epsg |
no |
|
|
INTEGER |
Numeric ID of the Spatial Reference System assigned by the organization |
no |
|
TEXT |
Well-known Text [32] Representation of the Spatial Reference System |
|
no |
|
TEXT |
Definition column WKT values in the gpkg_spatial_ref_sys table define the Spatial Reference Systems used by feature geometries and tile images, unless these SRSs are unknown and therefore undefined as specified in [_requirement-11]. Values are constructed per the EBNF syntax in [32] clause 7. EBNF name and number values may be obtained from any specified authority, e.g. [13][14]. For example, see the return value in [spatial_ref_sys_data_values_default] Test Method step (3) used to test the definition for WGS-84 per [_requirement-11]:
The gpkg_spatial_ref_sys table SHALL contain at a minimum the records listed in Spatial Ref Sys Table Records. The record with an srs_id of 4326 SHALL correspond to WGS-84 [15] as defined by EPSG [B3] in 4326 [13][14]. The record with an srs_id of -1 SHALL be used for undefined Cartesian coordinate reference systems. The record with an srs_id of 0 SHALL be used for undefined geographic coordinate reference systems.
srs_name |
srs_id |
organization |
organization_coordsys_id |
|---|---|---|---|
|
|
any |
4326 |
|
4326 |
any |
any |
any |
-1 |
|
-1 |
|
any |
any |
0 |
|
0 |
|
any |
The gpkg_spatial_ref_sys table in a GeoPackage SHALL contain records to define all spatial reference systems used by features and tiles in a GeoPackage.
The gpkg_contents table is intended to provide a list of all geospatial contents in a GeoPackage. It provides identifying and descriptive information that an application can display to a user as a menu of geospatial data that is available for access and/or update.
A GeoPackage file SHALL include a gpkg_contents table per table Contents Table Definition and [gpkg_contents_sql].
| Column Name | Type | Description | Null | Default | Key |
|---|---|---|---|---|---|
|
TEXT |
The name of the tiles, or feature table |
no |
PK |
|
|
TEXT |
Type of data stored in the table |
no |
||
|
TEXT |
A human-readable identifier (e.g. short name) for the table_name content |
yes |
UNIQUE |
|
|
TEXT |
A human-readable description for the table_name content |
yes |
'' |
|
|
DATETIME |
timestamp of last change to content, in ISO 8601 format |
no |
|
|
|
DOUBLE |
Bounding box minimum easting or longitude for all content in table_name |
yes |
||
|
DOUBLE |
Bounding box minimum northing or latitude for all content in table_name |
yes |
||
|
DOUBLE |
Bounding box maximum easting or longitude for all content in table_name |
yes |
||
|
DOUBLE |
Bounding box maximum northing or latitude for all content in table_name |
yes |
||
|
INTEGER |
Spatial Reference System ID: |
yes |
FK |
See [gpkg_contents_sql].
The table_name column value in a gpkg_contents table row SHALL contain the name of a SQLite table or view.
The data_type specifies the type of content contained in the table, for example "features" per clause [features], "attributes" per clause [attributes], "tiles" per clause [tiles], or an implementer-defined value for other data tables per clause in an Extended GeoPackage.
The last_change SHOULD contain the timestamp of when the content in the referenced table was last updated, in ISO8601 format. Note that since it is not practical to ensure that this value is maintained properly in all cases, this value should be treated as informative.
Values of the gpkg_contents table last_change column SHALL be in ISO 8601 [29] format containing a complete date plus UTC hours, minutes, seconds and a decimal fraction of a second, with a 'Z' ('zulu') suffix indicating UTC. The ISO8601 format is as defined by the strftime function '%Y-%m-%dT%H:%M:%fZ' format string applied to the current time. [7]
The bounding box (min_x, min_y, max_x, max_y) provides an informative bounding box (not necessarily minimum bounding box) of the content. The values are in the units specified by that CRS.
Values of the gpkg_contents table srs_id column SHALL reference values in the gpkg_spatial_ref_sys table srs_id column.