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 specification 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 be a SQLite [5] database file using version 3 of the SQLite file format [6] [7]. The first 16 bytes of a GeoPackage SHALL contain “SQLite format 3” [1] in ASCII [B4]. [2]
A GeoPackage SHALL contain 0x47503130 ("GP10" in ASCII) in the application id field of the SQLite database header to indicate a GeoPackage version 1.0 file. [3]
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 SHALL 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 specification but extend that to contain any of these elements are referred to as Extended GeoPackages throughout this specification.
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. [4]
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. [5]
The SQLite [8] library has many compile time and run time options that MAY be used to configure SQLite for different uses. Certain elements of the GeoPackage specification depend on the availability of SQLite functionality at runtime. This clause specifies the set of compile time options that SHALL or SHALL NOT be used.
Every GeoPackage SQLite Configuration SHALL have the SQLite library compile and run time options specified in clause 1.1.1.2.2 table Every GeoPackage SQLite Configuration.
| Setting | Option | Shall / Not | Discussion |
|---|---|---|---|
compile |
SQLITE_OMIT_* |
Not |
SHALL NOT include any OMIT options from http://www.sqlite.org/compile.html#omitfeatures. |
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) specifications.
| 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 SHALL define the Spatial Reference Systems used by feature geometries and tile images, unless these SRS are unknown and therefore undefined as specified in [_requirement-11]. Values SHALL be 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.
A GeoPackage file SHALL include a gpkg_contents table per table Contents Table or View Definition and [gpkg_contents_sql].
The purpose of the gpkg_contents table is to provide identifying and descriptive information that an application can display to a user in a menu of geospatial data that is available for access and/or update.
| 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:. “features” per clause [features], “tiles” per clause [tiles], or an implementer-defined value for other data tables per clause in an Extended GeoPackage. |
no |
||
|
TEXT |
A human-readable identifier (e.g. short name) for the table_name content |
yes |
||
|
TEXT |
A human-readable description for the table_name content |
yes |
'' |
|
|
DATETIME |
timestamp value in ISO 8601 format as defined by the strftime function '%Y-%m-%dT%H:%M:%fZ' format string applied to the current time |
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 |
The gpkg_contents table is intended to provide a list of all geospatial contents in a GeoPackage.
The data_type specifies the type of content.
The bounding box (min_x, min_y, max_x, max_y) provides an informative bounding box (not necessarily minimum bounding box) of the content.
If the srs_id column value references a geographic coordinate reference system (CRS), then the min/max x/y values are in decimal degrees; otherwise, the srs_id references a projected CRS and the min/max x/y values are in the units specified by that CRS.
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.
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. [6]
Values of the gpkg_contents table srs_id column SHALL reference values in the gpkg_spatial_ref_sys table srs_id column.