Open Geospatial Consortium
External identifier of this OGC® document: http://www.opengis.net/doc/IS/geopackage/1.1
URL for this OGC® document: http://www.geopackage.org/spec
Internal reference number of this OGC® document: OGC 12-128r12
Version: 1.1 (HTML conversion)
Category: OGC® Encoding Standard
Editor: Jeff Yutzler
Editor Emeritus: Paul Daisey
Previous Version: http://www.opengis.net/doc/IS/geopackage/1.0.1
Publication Date: 2015-08-04
Approval Date: 2015-08-04
Submission Date: 2015-08-04
Original Version: http://www.opengis.net/doc/IS/geopackage/1.0
OGC® GeoPackage Encoding Standard
Copyright © 2016 Open Geospatial Consortium.
To obtain additional rights of use, visit http://www.opengeospatial.org/legal/
Warning
This document is an OGC Member approved international standard. This document is available on a royalty free, non-discriminatory basis. Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation. This is a technical amendment to OGC 12-128r1.
Note that the normative text for this standard is located on the OGC website: https://portal.opengeospatial.org/files/?artifact_id=64506. If there are any differences from this HTML document and the normative document, the normative document takes precedence. |
Document type: OGC® Publicly Available Standard
Document subtype: Encoding Standard
Document stage: Approved
Document language: English
License Agreement
Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.
If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.
THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD.
THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.
This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.
Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications.
This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it. None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.
Patent Call
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.
Abstract
This OGC® Encoding Standard defines GeoPackages for exchange and GeoPackage SQLite Extensions for direct use of vector geospatial features and / or tile matrix sets of earth images and raster maps at various scales. Direct use means the ability to access and update data in a "native" storage format without intermediate format translations in an environment (e.g. through an API) that guarantees data model and data set integrity and identical access and update results in response to identical requests from different client applications. GeoPackages are interoperable across all enterprise and personal computing environments, and are particularly useful on mobile devices like cell phones and tablets in communications environments with limited connectivity and bandwidth.
Keywords
ogcdoc, geopackage, sqlite, raster, tiles, vector, feature, data, storage, exchange, mobile, smartphone, tablet
- OGC® GeoPackage Encoding Standard
- License Agreement
- Patent Call
- Abstract
- Keywords
- Introduction
- 1. Base
- 2. Options
- 3. Security Considerations
- Annex A: Conformance / Abstract Test Suite (Normative)
- Annex B: Background and Context (Normative)
- B.1. Background
- B.2. Document terms and definitions
- B.3. Conventions
- B.4. Submitting Organizations (Informative)
- B.5. Document contributor contact points (Informative)
- B.6. Revision History (Informative)
- B.7. Changes to the OGC® Abstract Specification
- B.8. Changes to OGC® Implementation Standards
- B.9. Potential Future Work (Informative)
- B.10. UML Notation
- B.11. GeoPackage Tables Detailed Diagram
- B.12. GeoPackage Minimal Tables for Features Diagram
- B.13. GeoPackage Minimal Tables for Tiles Diagram
- Annex C: Table Definition SQL (Normative)
- Annex D: Trigger Definition SQL (Informative)
- Annex E: GeoPackage Extension Template (Informative)
- Annex F: Registered Extensions (Normative)
- F.1. GeoPackage Non-Linear Geometry Types
- F.2. User Defined Geometry Types Extension of GeoPackageBinary Geometry Encoding
- F.3. RTree Spatial Indexes
- F.4. Geometry Type Triggers
- F.5. Geometry SRS ID Triggers
- F.6. Zoom Other Intervals
- F.7. Tiles Encoding WebP
- F.8. Metadata
- F.9. Schema
- F.10. WKT for Coordinate Reference Systems
- Annex G: Geometry Types (Normative)
- Annex H: Tiles Zoom Times Two Example (Informative)
- Annex I: Normative References (Normative)
- Annex J: Bibliography (Informative)
Introduction
Mobile device users who require map/geospatial application services and operate in disconnected or limited network connectivity environments are challenged by limited storage capacity and the lack of open format geospatial data to support these applications. The current situation is that each map/geospatial application requires its own potentially proprietary geospatial data store. These separate application-specific data stores may contain the same geospatial data, wasting the limited storage available, and requiring custom applications for data translation, replication, and synchronization to enable different map/geospatial applications to share the same world view. In addition, many existing geospatial data stores are platform-specific, which means that users with different platforms must translate data to share it.
An open, standards-based, application-independent, platform-independent, portable, interoperable, self-describing, GeoPackage (GPKG) data container, API and manifest are needed to overcome these challenges and to effectively support multiple map/geospatial applications such as fixed product distribution, local data collection, and geospatially enabled analytics. This standard is intended to facilitate widespread adoption and use of GeoPackages by both COTS and open-source software applications on enterprise production platforms as well as mobile hand-held devices [B1] [B2], given that mobile hand held devices do not yet have the processing power or battery life to effectively tackle difficult geospatial product production and analysis tasks. An application that accesses a GPKG will make use of the GPKG capabilities it requires; few if any such applications will make use of all GPKG capabilities.
This OGC® Encoding Standard defines GeoPackages for exchange and GeoPackage SQLite Extensions for direct use of vector geospatial features and / or tile matrix sets of earth images and raster maps at various scales. Direct use means the ability to access and update data in a “native” format without intermediate format translations in an environment (e.g. through an API) that guarantees data model and data set integrity and identical access and update results in response to identical requests from different client applications.
A GeoPackage is a platform-independent SQLite [5] database file that contains GeoPackage data and metadata tables shown in GeoPackage Tables Overview below, with specified definitions, integrity assertions, format limitations and content constraints. The allowable content of a GeoPackage is entirely defined in this standard.
An Extended GeoPackage is a GeoPackage that contains any additional data elements (tables or columns) or SQL constructs (data types, functions, indexes, constraints or triggers) that are not specified in this encoding standard.
A GeoPackage MAY be “empty” (contain user data table(s) for vector features and/or tile matrix pyramids with no row record content) or contain one or many vector feature type records and /or one or many tile matrix pyramid tile images. GeoPackage metadata CAN describe GeoPackage data contents and identify external data synchronization sources and targets. A GeoPackage MAY contain spatial indexes on feature geometries and SQL triggers to maintain indexes and enforce content constraints.
A GeoPackage SQLite Configuration consists of the SQLite 3 software library and a set of compile- and runtime configurations options.
A GeoPackage SQLite Extension is a SQLite loadable extension that MAY provide SQL functions [12] to support spatial indexes and SQL triggers linked to a SQLite library with specified configuration requirements to provide SQL API [1] [2] [3] [4] access to a GeoPackage file. This standard does not address the issues listed in the [_potential_future_work] clause in Background and Context (Normative), which MAY be addressed in a subsequent version of this standard or by other specifications.
1. Base
The required capabilities specified in this clause serve as the base for options specified in clause Options and extensions specified in clause Registered Extensions (Normative). 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.
1.1. Core
The mandatory core capabilities defined in sub clauses and requirement statements of this clause SHALL be implemented by every GeoPackage and GeoPackage SQLite Configuration.
1.1.1. SQLite Container
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.
Data
File Format
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 0x47503131 ("GP11" in ASCII) in the application id field of the SQLite database header to indicate a GeoPackage version 1.1 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.
File Extension Name
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.
File Contents
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 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 (Normative) encoded per clause 2.1.3 or a user-defined geometry type encoded per clause 3.1.2 and User Defined Geometry Types Extension of GeoPackageBinary 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 |
File Integrity
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.
API
Structured Query Language (SQL)
A GeoPackage SQLite Configuration SHALL provide SQL access to GeoPackage contents via SQLite version 3 [6] software APIs. [5]
Every GPKG SQLite Configuration
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 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. |
1.1.2. Spatial Reference Systems
Data
Table Definition
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 Table Definition SQL.
A table named gpkg_spatial_ref_sys
is the first component of the standard SQL schema for simple features described in clause Simple Features SQL Introduction 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 SQL/MM View of gpkg_spatial_ref_sys Definition SQL (Informative)) 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 |
Table Data Values
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.
1.1.3. Contents
Data
Table Definition
A GeoPackage file SHALL include a gpkg_contents
table per table Contents Table or View Definition and gpkg_contents Table Definition 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 |
UNIQUE |
|
|
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.
Table Data Values
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.
2. Options
The optional capabilities specified in this clause depend on the required capabilities specified in clause Base above. Each subclause of this clause defines an indivisible module of functionality that can be used in GeoPackages. These modules are referred to as options. GeoPackages MAY use one or more options defined in this section. GeoPackages MAY omit the tables for options that are not used. As a minimum, a GeoPackage SHALL contain one user data table as defined by the Features or Tiles options in clauses Features and Tiles respectively.
A GeoPackage SHALL contain features per clause Features and/or tiles per clause Tiles and row(s) in the gpkg_contents
table with lowercase data_type
column values of “features” and/or “tiles” describing the user data tables.
2.1. Features
2.1.1. Simple Features SQL Introduction
Vector feature data represents geolocated entities including conceptual ones such as districts, real world objects such as roads and rivers, and observations thereof.
International standards [9][10][11][12] have standardized practices for the storage, access and use of vector geospatial features and geometries via SQL in relational databases.
The first component of the SQL schema for vector features in a GeoPackage is the gpkg_spatial_ref_sys
table defined in clause Spatial Reference Systems above.
Other components are defined below.
In a GeoPackage, “simple” features are geolocated using a linear geometry subset of the SQL/MM (ISO 13249-3) [12] geometry model shown in Core Geometry Model below.
The instantiable (not abstract) geometry types defined in this Standard are restricted to 0, 1 and 2-dimensional geometric objects that exist in 2, 3 or 4-dimensional coordinate space (R2, R3 or R4). Geometry values in R2 have points with coordinate values for x and y. Geometry values in R3 have points with coordinate values for x, y and z or for x, y and m. Geometry values in R4 have points with coordinate values for x, y, z and m. The interpretation of the coordinates is subject to the coordinate reference systems associated to the point. All coordinates within a geometry object should be in the same coordinate reference systems.
Geometries MAY include z coordinate values. The z coordinate value traditionally represents the third dimension (i.e. 3D). In a Geographic Information System (GIS) this may be height above or below sea level. For example: A map might have a point identifying the position of a mountain peak by its location on the earth, with the x and y coordinate values, and the height of the mountain, with the z coordinate value.
Geometries MAY include m coordinate values. The m coordinate value allows the application environment to associate some measure with the point values. For example: A stream network may be modeled as multilinestring value with the m coordinate values measuring the distance from the mouth of stream.
All geometry types described in this standard are defined so that instances of Geometry are topologically closed, i.e. all represented geometries include their boundary as point sets. This does not affect their representation, and open version of the same classes MAY be used in other circumstances, such as topological representations.
A brief description of each geometry type is provided below. A more detailed description can be found in ISO 13249-3 [12].
-
Geometry: the root of the geometry type hierarchy.
-
Point: a single location in space. Each point has an X and Y coordinate. A point MAY optionally also have a Z and/or an M value.
-
Curve: the base type for all 1-dimensional geometry types. A 1-dimensional geometry is a geometry that has a length, but no area. A curve is considered simple if it does not intersect itself (except at the start and end point). A curve is considered closed its start and end point are coincident. A simple, closed curve is called a ring.
-
LineString: A Curve that connects two or more points in space.
-
Surface: the base type for all 2-dimensional geometry types. A 2-dimensional geometry is a geometry that has an area.
-
CurvePolygon: A planar surface defined by an exterior ring and zero or more interior ring. Each ring is defined by a Curve instance.
-
Polygon: A restricted form of CurvePolygon where each ring is defined as a simple, closed LineString.
-
GeometryCollection: A collection of zero or more Geometry instances. [7]
-
MultiSurface: A restricted form of GeometryCollection where each Geometry in the collection must be of type Surface.
-
MultiPolygon: A restricted form of MultiSurface where each Surface in the collection must be of type Polygon.
-
MultiCurve: A restricted form of GeometryCollection where each Geometry in the collection must be of type Curve.
-
MultiLineString: A restricted form of MultiCurve where each Curve in the collection must be of type LineString.
-
MultiPoint: A restricted form of GeometryCollection where each Geometry in the collection must be of type Point.
2.1.2. Contents
Data
Contents Table – Features Row
The gpkg_contents
table SHALL contain a row with a lowercase data_type
column value of “features” for each vector features user data table or view.
2.1.3. Geometry Encoding
Data
BLOB Format
A GeoPackage SHALL store feature table geometries with or without optional elevation (Z) and/or measure (M) values in SQL BLOBs using the Standard GeoPackageBinary format specified in table GeoPackage SQL Geometry Binary Format and clause BLOB Format.
GeoPackageBinaryHeader { byte[2] magic = 0x4750; (1) byte version; (2) byte flags; (3) int32 srs_id; double[] envelope; (4) } StandardGeoPackageBinary { GeoPackageBinaryHeader header; (5) WKBGeometry geometry; (6) }
1 | 'GP' in ASCII |
2 | 8-bit unsigned integer, 0 = version 1 |
3 | see bit layout of GeoPackageBinary flags byte |
4 | see flags envelope contents indicator code below |
5 | The X bit in the header flags field must be set to 0. |
6 | per OGC 06-103r4 [9] [8][9][10] |
bit |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
use |
R |
R |
X |
Y |
E |
E |
E |
B |
flag bits use:
-
R: reserved for future use; set to 0
-
X: GeoPackageBinary type
-
0: StandardGeoPackageBinary. See below
-
1: ExtendedGeoPackageBinary. See User Defined Geometry Types Extension of GeoPackageBinary Geometry Encoding.
-
-
Y: empty geometry flag
-
0: non-empty geometry
-
1: empty geometry
-
-
E: envelope contents indicator code (3-bit unsigned integer)
-
0: no envelope (space saving slower indexing option), 0 bytes
-
1: envelope is [minx, maxx, miny, maxy], 32 bytes
-
2: envelope is [minx, maxx, miny, maxy, minz, maxz], 48 bytes
-
3: envelope is [minx, maxx, miny, maxy, minm, maxm], 48 bytes
-
4: envelope is [minx, maxx, miny, maxy, minz, maxz, minm, maxm], 64 bytes
-
5-7: invalid
-
-
B: byte order for header values (1-bit Boolean)
-
0: Big Endian (most significant byte first)
-
1: Little Endian (least significant byte first)
-
Well-Known Binary as defined in OGC 06-103r4 [9] does not provide a standardized encoding for an empty point set (i.e., 'Point Empty' in Well-Known Text). In GeoPackages these points SHALL be encoded as a Point where each coordinate value is set to an IEEE-754 quiet NaN value. GeoPackages SHALL use big endian 0x7ff8000000000000 or little endian 0x000000000000f87f as the binary encoding of the NaN values.
When the WKBGeometry in a GeoPackageBinary is empty, either the envelope contents indicator code SHALL be 0 indicating no envelope, or the envelope SHALL have its values set to NaN as defined for an empty point.
2.1.4. SQL Geometry Types
Data
Core Types
A GeoPackage SHALL store feature table geometries with the basic simple feature geometry types (Geometry, Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeomCollection) in Geometry Types (Normative) Geometry Type Codes (Core) in the GeoPackageBinary geometry encoding format.
2.1.5. Geometry Columns
Data
Table Definition
A GeoPackage with a gpkg_contents
table row with a “features” data_type
SHALL contain a gpkg_geometry_columns
table or updateable view per Geometry Columns Table or View Definition and gpkg_geometry_columns Table Definition SQL.
The second component of the SQL schema for vector features in a GeoPackage is a gpkg_geometry_columns
table that
identifies the geometry columns and geometry types in tables that contain user data representing features.
Column Name | Type | Description | Key |
---|---|---|---|
|
TEXT |
Name of the table containing the geometry column |
PK, FK |
|
TEXT |
Name of a column in the feature table that is a Geometry Column |
PK |
|
TEXT |
Name from Geometry Type Codes (Core) or Geometry Type Codes (Extension) in Geometry Types (Normative) |
|
|
INTEGER |
Spatial Reference System ID: |
FK |
|
TINYINT |
0: z values prohibited; 1: z values mandatory; 2: z values optional |
|
|
TINYINT |
0: m values prohibited; 1: m values mandatory; 2: m values optional |
The FK on gpkg_geometry_columns.srs_id
references the PK on gpkg_spatial_ref_sys.srs_id
to ensure that geometry columns are only defined in feature tables for defined spatial reference systems.
Views of this table or view MAY be used to provide compatibility with the SQL/MM [12] SQL/MM View of gpkg_geometry_columns Definition SQL (Informative) and OGC Simple Features SQL [9][10][11] SF/SQL VIEW of gpkg_geometry_columns Definition SQL (Informative) specifications.
Table Data Values
The gpkg_geometry_columns
table or updateable view SHALL contain one row record for the geometry column in each vector feature data table (clause Vector Feature User Data Tables) in a GeoPackage.
Values of the gpkg_geometry_columns
table_name
column SHALL reference values in the gpkg_contents
table_name
column for rows with a data_type
of 'features'.
The column_name
column value in a gpkg_geometry_columns
row SHALL be the name of a column in the table or view specified by the table_name
column value for that row.
The geometry_type_name
value in a gpkg_geometry_columns
row SHALL be one of the uppercase geometry type names specified in Geometry Types (Normative).
The srs_id
value in a gpkg_geometry_columns
table row SHALL be an srs_id
column value from the gpkg_spatial_ref_sys
table.
The z value in a gpkg_geometry_columns
table row SHALL be one of 0, 1, or 2.
The m value in a gpkg_geometry_columns
table row SHALL be one of 0, 1, or 2.
2.1.6. Vector Feature User Data Tables
Data
Table Definition
The third component of the SQL schema for vector features in a GeoPackage described in clause Simple Features SQL Introduction above are tables that contain user data representing features. Feature attributes are columns in a feature table, including geometries. Features are rows in a feature table. [11]
A GeoPackage MAY contain tables or updateable views containing vector features. Every such feature table or view in a GeoPackage SHALL have a column with column type INTEGER and 'PRIMARY KEY AUTOINCREMENT' column constraints per EXAMPLE : Sample Feature Table or View Definition and sample_feature_table Table Definition SQL (Informative).
The integer primary key of a feature table allows features to be linked to row level metadata records in the gpkg_metadata
table by rowid [B5] values in the gpkg_metadata_reference
table as described in clause Metadata Reference Table below.
A feature table SHALL have only one geometry column.
Feature data models [B23] from non-GeoPackage implementations that have multiple geometry columns per feature table MAY be transformed into GeoPackage implementations with a separate feature table for each geometry type whose rows have matching integer primary key values that allow them to be joined in a view with the same column definitions as the non-GeoPackage feature data model with multiple geometry columns.
The declared SQL type of the geometry column in a vector feature user data table SHALL be the uppercase geometry type name from Annex G specified by the geometry_type_name column for that column_name and table_name in the gpkg_geometry_columns table.
Column Name | Type | Description | Null | Default | Key |
---|---|---|---|---|---|
|
INTEGER |
Autoincrement primary key |
no |
PK |
|
|
GEOMETRY |
GeoPackage Geometry |
yes |
||
|
TEXT |
Text attribute of feature |
yes |
||
|
REAL |
Real attribute of feature |
yes |
||
|
BOOLEAN |
Boolean attribute of feature |
yes |
||
|
BLOB |
Photograph of the area |
yes |
Table Data Values
A feature geometry is stored in a geometry column specified by the geometry_column
value for the feature table in the gpkg_geometry_columns
table defined in clause Geometry Columns above.
The geometry type of a feature geometry column specified in the gpkg_geometry_columns
table geometry_type_name
column is a name from Geometry Types (Normative).
Feature table geometry columns SHALL contain geometries of the type or assignable for the type specified for the column by the gpkg_geometry_columns
table geometry_type_name
uppercase column value [12].
Geometry subtypes are assignable as defined in Geometry Types (Normative) and shown in part in Core Geometry Model.
For example, if the geometry_type_name
value in the gpkg_geometry_columns
table is for a geometry type like POINT that has no subtypes, then the feature table geometry column MAY only contain geometries of that type.
If the geometry type_name
value in the gpkg_geometry_columns
table is for a geometry type like GEOMCOLLECTION that has subtypes, then the feature table geometry column MAY only contain geometries of that type or any of its direct or indirect subtypes.
If the geometry type_name
is GEOMETRY (the root of the geometry type hierarchy) then the feature table geometry column MAY contain geometries of any geometry type.
The presence or absence of optional elevation (Z) and/or measure (M) values in a geometry does not change its type or assignability. The unit of measure for optional elevation(Z) values is determined by the CRS of the geometry; it is as-defined by a 3D CRS, and undefined for a 2D CRS. The unit of measure for optional measure (M) values is determined by the CRS of the geometry.
The spatial reference system type of a feature geometry column specified by a gpkg_geometry_columns
table srs_id
column value is a code from the gpkg_spatial_ref_sys
table srs_id
column.
Feature table geometry columns SHALL contain geometries with the srs_id
specified for the column by the gpkg_geometry_columns
table srs_id
column value.
2.2. Tiles
2.2.1. Tile Matrix Introduction
There are a wide variety of commercial and open source conventions for storing, indexing, accessing and describing tiles in tile pyramids. Unfortunately, no applicable existing consensus, national or international specifications have standardized practices in this domain. In addition, various image file formats have different representational capabilities, and include different self-descriptive metadata.
The tile store data / metadata model and convention described below support direct use of tiles in a GeoPackage in two ways. First, they specify how existing application MAY create SQL Views of the data /metadata model on top of existing application tables that that follow different interface conventions. Second, they include and expose enough metadata information at both the dataset and record level to allow applications that use GeoPackage data to discover its characteristics without having to parse all of the stored images. Applications that store GeoPackage tile data, which are presumed to have this information available, SHALL store sufficient metadata to enable its intended use.
The GeoPackage tile store data model MAY be implemented directly as SQL tables in a SQLite database for maximum performance, or as SQL views on top of tables in an existing SQLite tile store for maximum adaptability and loose coupling to enable widespread implementation.
A GeoPackage CAN store multiple raster and tile pyramid data sets in different tables or views in the same container. [13] “Tile pyramid” refers to the concept of pyramid structure of tiles of different spatial extent and resolution at different zoom levels, and the tile data itself. “Tile matrix” refers to rows and columns of tiles that all have the same spatial extent and resolution at a particular zoom level. “Tile matrix set” refers to the definition of a tile pyramid’s tiling structure.
The tables or views that implement the GeoPackage tile store data / metadata model are described and discussed individually in the following subsections.
2.2.2. Contents
Data
Contents Table – Tiles Row
The gpkg_contents
table SHALL contain a row with a data_type
column value of “tiles” for each tile pyramid user data table or view.
2.2.3. Zoom Levels
In a GeoPackage, zoom levels are integers in sequence from 0 to n that identify tile matrix layers in a tile matrix set that contain tiles of decreasing spatial extent and finer spatial resolution. Adjacent zoom levels immediately preceed or follow each other and differ by a value of 1. Pixel sizes are real numbers in the terrain units of the spatial reference system of a tile image specifying the dimensions of the real world area represented by one pixel. Pixel size MAY vary by a constant factor or by different factors or intervals between some or all adjacent zoom levels in a tile matrix set. In the commonly used "zoom times two" convention, pixel sizes vary by a factor of 2 between all adjacent zoom levels, as shown in the example in Tiles Zoom Times Two Example (Informative). Other "zoom other intervals" conventions use different factors or irregular intervals with pixel sizes chosen for intuitive cartographic representation of raster data, or to coincide with the original pixel size of commonly used global image products. See Web Map Tile Service (WMTS) [16] Annex E for additional examples of both conventions.
Data
Zoom Times Two
In a GeoPackage that contains a tile pyramid user data table that contains tile data, by default [14], zoom level pixel sizes for that table SHALL vary by a factor of 2 between adjacent zoom levels in the tile matrix metadata table.
2.2.4. Tile Encoding PNG
2.2.5. Tile Encoding JPEG
2.2.6. Tile Matrix Set
Data
Table Definition
A GeoPackage that contains a tile pyramid user data table SHALL contain gpkg_tile_matrix_set
table or view per Table Definition, Tile Matrix Set Table or View Definition and gpkg_tile_matrix_set Table Creation SQL.
Column Name | Column Type | Column Description | Null | Default | Key |
---|---|---|---|---|---|
|
TEXT |
Tile Pyramid User Data Table Name |
no |
PK, FK |
|
|
INTEGER |
Spatial Reference System ID: gpkg_spatial_ref_sys.srs_id |
no |
FK |
|
|
DOUBLE |
Bounding box minimum easting or longitude for all content in table_name |
no |
||
|
DOUBLE |
Bounding box minimum northing or latitude for all content in table_name |
no |
||
|
DOUBLE |
Bounding box maximum easting or longitude for all content in table_name |
no |
||
|
DOUBLE |
Bounding box maximum northing or latitude for all content in table_name |
no |
The gpkg_tile_matrix_set table or updateable view defines the spatial reference system (srs_id) and the maximum bounding box (min_x, min_y, max_x, max_y) for all possible tiles in a tile pyramid user data table. All tiles present in the tile pyramid SHALL fall within this bounding box. However, the bounding box MAY be larger than the minimum bounding rectangle around the actual tiles in that pyramid.
Table Data Values
The minimum bounding box defined in the gpkg_tile_matrix_set table or view for a tile pyramid user data table SHALL be exact so that the bounding box coordinates for individual tiles in a tile pyramid MAY be calculated based on the column values for the user data table in the gpkg_tile_matrix table or view. For example, because GeoPackages use the upper left tile origin convention defined in clause Table Data Values below, the gpkg_tile_matrix_set (min_x, max_y) ordinate is the upper-left corner of tile (0,0) for all zoom levels in a table_name tile pyramid user data table.
Values of the gpkg_tile_matrix_set
table_name
column SHALL reference values in th gpkg_contents table_name column for rows with a data type of "tiles".
The gpkg_tile_matrix_set table or view SHALL contain one row record for each tile pyramid user data table.
Values of the gpkg_tile_matrix_set
srs_id
column SHALL reference values in the gpkg_spatial_ref_sys
srs_id
column.
2.2.7. Tile Matrix
Data
Table Definition
A GeoPackage that contains a tile pyramid user data table SHALL contain a gpkg_tile_matrix
table or view per clause 2.2.7.1.1 Table Definition, Table Tile Matrix Metadata Table or View Definition and Table gpkg_tile_matrix Table Creation SQL.
Column Name | Column Type | Column Description | Null | Key |
---|---|---|---|---|
|
TEXT |
Tile Pyramid User Data Table Name |
no |
PK, FK |
|
INTEGER |
0 ⇐ |
no |
PK |
|
INTEGER |
Number of columns (>= 1) in tile matrix at this zoom level |
no |
|
|
INTEGER |
Number of rows (>= 1) in tile matrix at this zoom level |
no |
|
|
INTEGER |
Tile width in pixels (>= 1)for this zoom level |
no |
|
|
INTEGER |
Tile height in pixels (>= 1) for this zoom level |
no |
|
|
DOUBLE |
In |
no |
|
|
DOUBLE |
In |
no |
The gpkg_tile_matrix
table or updateable view documents the structure of the tile matrix at each zoom level in each tiles table.
It allows GeoPackages to contain rectangular as well as square tiles (e.g. for better representation of polar regions).
It allows tile pyramids with zoom levels that differ in resolution by factors of 2, irregular intervals, or regular intervals other than factors of 2.
Table Data Values
Values of the gpkg_tile_matrix
table_name
column SHALL reference values in the gpkg_contents
table_name
column for rows with a data_type
of “tiles”.
The gpkg_tile_matrix
table or view SHALL contain one row record for each zoom level that contains one or more tiles in each tile pyramid user data table or view.
The width of a tile matrix (the difference between min_x
and max_x
in gpkg_tile_matrix_set
) SHALL equal the product of matrix_width
, tile_width
, and pixel_x_size
for that zoom level.
Similarly, height of a tile matrix (the difference between min_y
and max_y
in gpkg_tile_matrix_set
) SHALL equal the product of matrix_height
, tile_height
, and pixel_y_size
for that zoom level.
The gpkg_tile_matrix
table or view MAY contain row records for zoom levels in a tile pyramid user data table that do not contain tiles.
GeoPackages follow the most frequently used conventions of a tile origin at the upper left and a zoom-out-level of 0 for the smallest map scale “whole world” zoom level view [17], as specified by WMTS [16]. The tile coordinate (0,0) always refers to the tile in the upper left corner of the tile matrix at any zoom level, regardless of the actual availability of that tile.
The zoom_level
column value in a gpkg_tile_matrix
table row SHALL not be negative.
The matrix_width
column value in a gpkg_tile_matrix
table row SHALL be greater than 0.
The matrix_height
column value in a gpkg_tile_matrix
table row SHALL be greater than 0.
The tile_width
column value in a gpkg_tile_matrix
table row SHALL be greater than 0.
The tile_height
column value in a gpkg_tile_matrix
table row SHALL be greater than 0.
The pixel_x_size
column value in a gpkg_tile_matrix
table row SHALL be greater than 0.
The pixel_y_size
column value in a gpkg_tile_matrix
table row SHALL be greater than 0.
The pixel_x_size
and pixel_y_size
column values for zoom_level
column values in a gpkg_tile_matrix
table sorted in ascending order SHALL be sorted in descending order.
Tiles MAY or MAY NOT be provided for level 0 or any other particular zoom level. [18]
This means that a tile matrix set can be sparse, i.e. not contain a tile for any particular position at a certain tile zoom level.
[19] This does not affect the informative spatial extent stated by the min/max x/y columns values in the gpkg_contents
record for the same table_name
, the exact spatial extent stated by the min/max x/y columns values in the gpkg_tile_matrix_set
record for the same table name, or the tile matrix width and height at that level. [20]
2.2.8. Tile Pyramid User Data Tables
Data
Table Definition
Each tile matrix set in a GeoPackage SHALL be stored in a different tile pyramid user data table or updateable view with a unique name that SHALL have a column named "id" with column type INTEGER and 'PRIMARY KEY AUTOINCREMENT' column constraints per Clause 2.2.8.1.1 Table Definition, Tiles Table or View Definition and EXAMPLE: tiles table Create Table SQL (Informative).
Column Name | Column Type | Column Description | Null | Default | Key |
---|---|---|---|---|---|
|
INTEGER |
Autoincrement primary key |
no |
PK |
|
|
INTEGER |
min(zoom_level) ⇐ |
no |
0 |
UK |
|
INTEGER |
0 to |
no |
0 |
UK |
|
INTEGER |
0 to |
no |
0 |
UK |
|
BLOB |
Of an image MIME type specified in clauses Tile Encoding PNG, Tile Encoding JPEG, [tile_enc_webp] |
no |
Table Data Values
Each tile pyramid user data table or view [21] MAY contain tile matrices at zero or more zoom levels of different spatial resolution (map scale).
For each distinct table_name
from the gpkg_tile_matrix
(tm) table, the tile pyramid (tp) user data table zoom_level
column value in a GeoPackage SHALL be in the range min(tm.zoom_level) ⇐ tp.zoom_level ⇐ max(tm.zoom_level).
For each distinct table_name
from the gpkg_tile_matrix
(tm) table, the tile pyramid (tp) user data table tile_column
column value in a GeoPackage SHALL be in the range 0 ⇐ tp.tile_column ⇐ tm.matrix_width – 1 where the tm and tp zoom_level
column values are equal.
For each distinct table_name
from the gpkg_tile_matrix
(tm) table, the tile pyramid (tp) user data table tile_row
column value in a GeoPackage SHALL be in the range 0 ⇐ tp.tile_row ⇐ tm.matrix_height – 1 where the tm and tp zoom_level
column values are equal.
All tiles at a particular zoom level have the same pixel_x_size
and pixel_y_size
values specified in the gpkg_tile_matrix
row record for that tiles table and zoom level. [22]
2.3. Extension Mechanism
2.3.1. Introduction
A GeoPackage extension is a set of one or more requirements clauses that are documented by filling out the GeoPackage Extension Template in GeoPackage Extension Template (Informative). 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[23] used in Extended GeoPackages.
2.3.2. Extensions
Data
Table Definition
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 Table Definition SQL.
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 |
Unique |
|
TEXT |
Name of the column that requires the extension. When NULL, the extension is required for the entire table. |
yes |
Unique |
|
TEXT |
The case sensitive name of the extension that is required, in the form <author>_<extension_name>. |
no |
Unique |
|
TEXT |
Definition of the extension in the form specfied by the template in GeoPackage Extension Template (Informative) or reference thereto. |
no |
|
|
TEXT |
Indicates scope of extension effects on readers / writers: 'read-write' or 'write-only' in lowercase. |
no |
Table Data Values
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 SHALL reference values in the gpkg_contents
table_name
column or be NULL.
They SHALL NOT be NULL for rows where the column_name
value is not NULL.
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.
Complete examples of how to fill out the GeoPackage Extension Template in GeoPackage Extension Template (Informative) are provided by Annex F.
The definition column value in a gpkg_extensions
row for those extensions SHALL contain the sub-annex name and as a reference (e.g., F.3 RTree Spatial Indexes).
Partial examples of how to fill out the GeoPackage Extension Template in GeoPackage Extension Template (Informative) are provided by the templates in GeoPackage Non-Linear Geometry Types and User Defined Geometry Types Extension of GeoPackageBinary Geometry Encoding. Extension definitions created using those template and other extension definitions MAY be provided in the definition column, preferably as ASCII text, or as a reference such as a URI [23] or email address whereby the definition may be obtained.
The definition column value in a gpkg_extensions
row SHALL contain or reference the text that results from documenting an extension by filling out the GeoPackage Extension Template in GeoPackage Extension Template (Informative).
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”.
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.
The author value “gpkg” is reserved for GeoPackage extensions that are developed and maintained by OGC. Requirements for extension names for the “gpkg” author name are defined in the clauses listed in 14 below. GeoPackage implementers use their own author names to register other extensions.
3. Security Considerations
Security considerations for implementations utilizing GeoPackages are in the domain of the implementing application, deployment platform, operating system and networking environment. The GeoPackage standard does not place any constraints on application, platform, operating system level or network security.
Annex A: Conformance / Abstract Test Suite (Normative)
A.1. Base
A.1.1. Core
SQLite Container
Data
File Format
Test Case ID |
/base/core/container/data/file_format |
Test Purpose |
Verify that the Geopackage is an SQLite version_3 database |
Test Method |
Pass if the first 16 bytes of the file contain “SQLite format 3” in ASCII. |
Reference |
Clause 1.1.1.1.1 Req 1: |
Test Type |
Basic |
Test Case ID |
/base/core/container/data/file_format/application_id |
Test Purpose |
Verify that the SQLite database header application id field indicates GeoPackage version 1.0 |
Test Method |
Pass if the application id field of the SQLite database header contains “GP10” in ASCII. |
Reference |
Clause 1.1.1.1.1 Req 2: |
Test Type |
Basic |
File Extension Name
Test Case ID |
/base/core/container/data/file_extension_name |
Test Purpose |
Verify that the geopackage extension is ".gpkg" |
Test Method |
Pass if the geopackage file extension is ".gpkg" |
Reference |
Clause 1.1.1.1.2 Req 3: |
Test Type |
Basic |
File Contents
Test Case ID |
/base/core/container/data/file_contents |
Test Purpose |
Verify that the Geopackage only contains specified contents |
Test Method |
|
Reference |
Clause 1.1.1.1.3 Req 4: |
Test Type |
Basic |
Test Case ID |
/base/core/container/data/table_data_types |
Test Purpose |
Verify that the data types of GeoPackage columns include only the types specified by GeoPackage Data Types. |
Test Method |
|
Reference |
GeoPackage Data Types Req 5: |
Test Type |
Basic |
Integrity Check
Test Case ID |
/base/core/container/data/file_integrity |
Test Purpose |
Verify that the geopackage passes the SQLite integrity check. |
Test Method |
Pass if PRAGMA integrity_check returns “ok" |
Reference |
Clause File Integrity Req 6: |
Test Type |
Capability |
Test Case ID |
/base/core/container/data/foreign_key_integrity |
Test Purpose |
Verify that the geopackage passes the SQLite foreign_key_check. |
Test Method |
Pass if PRAGMA foreign_key_check() with no parameter value returns an empty result set |
Reference |
Clause File Integrity Req 7: |
Test Type |
Capability |
API
Structured Query Language
Test Case ID |
/base/core/container/api/sql |
Test Purpose |
Test that the GeoPackage SQLite Extension provides the SQLite SQL API interface. |
Test Method |
|
Reference |
Clause 1.1.1.2.1 Req 8: |
Test Type |
Capability |
Every GPKG SQLite Configuration
Test Case ID |
/base/core/container/api/every_gpkg_sqlite_config |
Test Purpose |
Verify that a GeoPackage SQLite Extension has the Every GeoPackage SQLite Configuration compile and run time options. |
Test Method |
|
Reference |
Clause 1.1.1.2.2 Req 9: |
Test Type |
Basic |
Spatial Reference Systems
Data
Table Definition
Test Case ID |
/base/core/gpkg_spatial_ref_sys/data/table_def |
Test Purpose |
Verify that the gpkg_spatial_ref_sys table exists and has the correct definition. |
Test Method |
|
Reference |
Clause 1.1.2.1.1 Req 10: |
Test Type |
Basic |
Table Data Values
Test Case ID |
/base/core/gpkg_spatial_ref_sys/data_values_default |
Test Purpose |
Verify that the spatial_ref_sys table contains the required default contents. |
Test Method |
|
Reference |
Clause 1.1.2.1.2 Requirement 11: |
Test Type |
Capability |
Test Case ID |
/base/core/spatial_ref_sys/data_values_required |
Test Purpose |
Verify that the spatial_ref_sys table contains rows to define all srs_id values used by features and tiles in a GeoPackage. |
Test Method |
|
Reference |
Clause Clause 1.1.2.1.2 Req 12: |
Test Type |
Capability |
Contents
Data
Table Definition
Test Case ID |
/base/core/contents/data/table_def |
Test Purpose |
Verify that the gpkg_contents table exists and has the correct definition. |
Test Method |
|
Reference |
Clause 1.1.3.1.1 Req 13: |
Test Type |
Basic |
Table Data Values
Test Case ID |
/base/core/contents/data/data_values_table_name |
Test Purpose |
Verify that the table_name column values in the gpkg_contents table are valid. |
Test Method |
|
Reference |
Clause 1.1.3.1.2 Req 14: |
Test Type |
Capability |
Test Case ID |
/base/core/contents/data/data_values_last_change |
Test Purpose |
Verify that the gpkg_contents table last_change column values are 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. |
Test Method |
|
Reference |
Clause 1.1.3.1.2 Req 15: |
Test Type |
Capability |
Test Case ID |
/base/core/contents/data/data_values_srs_id |
Test Purpose |
Verify that the gpkg_contents table srs_id column values reference gpkg_spatial_ref_sys srs_id column values. |
Test Method |
|
Reference |
Clause 1.1.3.1.2 Req 16: |
Test Type |
Capability |
A.2. Options
Test Case ID |
/opt/valid_geopackage |
Test Purpose |
Verify that a GeoPackage contains a features or tiles table and gpkg_contents table row describing it. |
Test Method |
|
Reference |
Clause 2 Req 17: |
Test Type |
Capability |
A.2.1. Features
Simple Features SQL Introduction
Contents
Data
Contents Table Feature Row
Test Case ID |
/opt/features/contents/data/features_row |
Test Purpose |
Verify that the gpkg_contents table_name value table exists, and is apparently a feature table for every row with a data_type column value of “features” |
Test Method |
|
Reference |
Clause 2.1.2.1.1 Req 18: |
Test Type |
Capability |
Geometry Encoding
Data
BLOB Format
Test Case ID |
/opt/features/geometry_encoding/data/blob |
Test Purpose |
Verify that geometries stored in feature table geometry columns are encoded in the StandardGeoPackageBinary format. |
Test Method |
|
Reference |
Clause 2.1.3.1.1 Req 19: |
Test Type |
Capability |
SQL Geometry Types
Data
Core Types
Test Case ID |
/opt/features/geometry_encoding/data/core_types_existing_sparse_data |
Test Purpose |
Verify that existing basic simple feature geometries are stored in valid GeoPackageBinary format encodings. |
Test Method |
|
Reference |
Clause 2.1.4.1.1 Req 20: |
Test Type |
Capability |
Test Case ID |
/opt/features/geometry_encoding/data/core_types_all_types_test_data |
Test Purpose |
Verify that all basic simple feature geometry types and options are stored in valid GeoPackageBinary format encodings. |
Test Method |
|
Reference |
Clause 2.1.4.1.1 Req 20: |
Test Type |
Capability |
Geometry Columns
Data
Table Definition
Test Case ID |
/opt/features/geometry_columns/data/table_def |
Test Purpose |
Verify that the gpkg_geometry_columns table exists and has the correct definition. |
Test Method |
|
Reference |
Clause 2.1.5.1.1 Req 21: |
Test Type |
Basic |
Table Data Values
Test Case ID |
/opt/features/geometry_columns/data/data_values_geometry_columns |
Test Purpose |
Verify that gpkg_geometry_columns contains one row record for each geometry column in each vector feature user data table. |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 22: |
Test Type |
Capability |
Test Case ID |
/opt/features/geometry_columns/data/data_values_table_name |
Test Purpose |
Verify that the table_name column values in the gpkg_geometry_columns table are valid. |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 23: |
Test Type |
Capability |
Test Case ID |
/opt/features/geometry_columns/data/data_values_column_name |
Test Purpose |
Verify that the column_name column values in the gpkg_geometry_columns table are valid. |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 24: |
Test Type |
Capability |
Test Case ID |
/opt/features/geometry_columns/data/data_values_geometry_type_name |
Test Purpose |
Verify that the geometry_type_name column values in the gpkg_geometry_columns table are valid. |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 25: |
Test Type |
Capability |
Test Case ID |
/opt/features/geometry_columns/data/data_values_srs_id |
Test Purpose |
Verify that the gpkg_geometry_columns table srs_id column values are valid. |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 26: |
Test Type |
Capability |
Test Case ID |
/opt/features/geometry_columns/data/data_values_z |
Test Purpose |
Verify that the gpkg_geometry_columns table z column values are valid. |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 27: |
Test Type |
Capability |
Test Case ID |
/opt/features/geometry_columns/data/data_values_m |
Test Purpose |
Verify that the gpkg_geometry_columns table m column values are valid. |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 28: |
Test Type |
Capability |
Vector Features User Data Tables
Data
Table Definition
Test Case ID |
/opt/features/vector_features/data/feature_table_integer_primary_key |
Test Purpose |
Verify that every vector features user data table has an integer primary key. |
Test Method |
|
Reference |
Clause 2.1.6.1.1 Req 29: |
Test Type |
Basic |
Test Case ID |
/opt/features/vector_features/data/feature_table_one_geometry_column |
Test Purpose |
Verify that every vector features user data table has one geometry column. |
Test Method |
|
Reference |
Clause 2.1.6.1.1 Req 30: |
Test Type |
Capability |
Test Case ID |
/opt/features/vector_features/data/feature_table_geometry_column_type |
Test Purpose |
Verify that the declared SQL type of a feature table geometry column is the uppercase geometry type name from Annex G specified by the geometry_type_name column for that column_name and table_name in the gpkg_geometry_columns table. |
Test Method |
|
Reference |
Clause 2.1.6.1.1 Req 31: |
Test Type |
Capability |
Table Data Values
Test Case ID |
/opt/features/vector_features/data/data_values_geometry_type |
Test Purpose |
Verify that the geometry type of feature geometries are of the type or are assignable for the geometry type specified by the gpkg_geometry columns table geometry_type_name column value. |
Test Method |
|
Reference |
Clause 2.1.6.1.2 Req 32: |
Test Type |
Capability |
Test Case ID |
/opt/features/vector_features/data/data_value_geometry_srs_id |
Test Purpose |
Verify the the srs_id of feature geometries are the srs_id specified for the gpkg_geometry_columns table srs_id column value. |
Test Method |
|
Reference |
Clause 2.1.6.1.2 Req 33: |
Test Type |
Capability |
A.2.2. Tiles
Contents
Data
Contents Table – Tiles Row
Test Case ID |
/opt/tiles/contents/data/tiles_row |
Test Purpose |
Verify that the gpkg_contents table_name value table exists and is apparently a tiles table for every row with a data_type column value of “tiles”. |
Test Method |
|
Reference |
Clause 2.2.2.1.1 Req 34: |
Test Type |
Capability |
Zoom Levels
Data
Zoom Times Two
Test Case ID |
/opt/tiles/zoom_levels/data/zoom_times_two |
Test Purpose |
Verify that zoom level pixel sizes for tile matrix user data tables vary by factors of 2 between adjacent zoom levels in the tile matrix metadata table. |
Test Method |
|
Reference |
Clause 2.2.3.1.1 Req 35: |
Test Type |
Capability |
Tile Encoding PNG
Data
MIME Type PNG
Test Case ID |
/opt/tiles/tiles_encoding/data/mime_type_png |
Test Purpose |
Verify that a tile matrix user data table that contains tile data that is not MIME type image/jpeg by default contains tile data in MIME type image/png. |
Test Method |
|
Reference |
Clause 2.2.4.1.1 Req 36: |
Test Type |
Capability |
Tile Encoding JPEG
Data
MIME Type JPEG
Test Case ID |
/opt/tiles/tiles_encoding/data/mime_type_jpeg |
Test Purpose |
Verify that a tile matrix user data table that contains tile data that is not MIME type image/png by default contains tile data in MIME type image/jpeg. |
Test Method |
|
Reference |
Clause 2.2.5.1.1 Req 37: |
Test Type |
Capability |
Tile Matrix Set
Data
Table Definition
Test Case ID |
/opt/tiles/gpkg_tile_matrix_set/data/table_def |
Test Purpose |
Verify that the gpkg_tile_matrix_set table exists and has the correct definition. |
Test Method |
|
Reference |
Clause 2.2.6.1.1 Req 38: |
Test Type |
Capability |
Table Data Values
Test Case ID |
/opt/tiles/gpkg_tile_matrix_set/data/data_values_table_name |
Test Purpose |
Verify that values of the gpkg_tile_matrix_set table_name column reference values in the gpkg_contents table_name column for rows with a data type of “tiles”. |
Test Method |
|
Reference |
Clause 2.2.6.1.2 Req 39: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix_set/data/data_values_row_record |
Test Purpose |
Verify that the gpkg_tile_matrix_set table contains a row record for each tile pyramid user data table . |
Test Method |
|
Reference |
Clause 2.2.6.1.2 Req 40: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix_set/data/data_values_srs_id |
Test Purpose |
Verify that the gpkg_tile_matrix_set table srs_id column values reference gpkg_spatial_ref_sys srs_id column values. |
Test Method |
|
Reference |
Clause 2.2.6.1.2 Req 41: |
Test Type |
Capability |
Tile Matrix
Data
Table Definition
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/table_def |
Test Purpose |
Verify that the gpkg_tile_matrix table exists and has the correct definition. |
Test Method |
|
Reference |
Clause 2.2.7.1.1 Req 42: |
Test Type |
Basic |
Table Data Values
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_table_name |
Test Purpose |
Verify that values of the gpkg_tile_matrix table_name column reference values in the gpkg_contents table_name column for rows with a data type of “tiles”. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 43: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_zoom_level_rows |
Test Purpose |
Verify that the gpkg_tile_matrix table contains a row record for each zoom level that contains one or more tiles in each tile pyramid user data table. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 44: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_width_height |
Test Purpose |
Verify that the tile matrix extents in gpkg_tile_matrix_set match the contents of the gpkg_tile_matrix table. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 45: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_zoom_level |
Test Purpose |
Verify that zoom level column values in the gpkg_tile_matrix table are not negative. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 46: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_matrix_width |
Test Purpose |
Verify that the matrix_width values in the gpkg_tile_matrix table are valid. |
Test Method |
|
Reference: |
Clause 2.2.7.1.2 Req 47: |
Test Type: |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_matrix_height |
Test Purpose |
Verify that the matrix_height values in the gpkg_tile_matrix table are valid. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 48: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_tile_width |
Test Purpose |
Verify that the tile_width values in the gpkg_tile_matrix table are valid. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 49: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_tile_height |
Test Purpose |
Verify that the tile_height values in the gpkg_tile_matrix table are valid. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 50: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_pixel_x_size |
Test Purpose |
Verify that the pixel_x_size values in the gpkg_tile_matrix table are valid. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 51: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_pixel_y_size |
Test Purpose |
Verify that the pixel_y_size values in the gpkg_tile_matrix table are valid. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 52: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/data_values_pixel_size_sort |
Test Purpose |
Verify that the pixel_x_size and pixel_y_size column values for zoom level column values in a gpkg_tile_matrix table sorted in ascending order are sorted in descending order, showing that lower zoom levels are zoomed “out”. |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 53: |
Test Type |
Capability |
Tile Pyramid User Data
Data
Table Definition
Test Case ID |
/opt/tiles/tile_pyramid/data/table_def |
Test Purpose |
Verify that multiple tile pyramids are stored in different tiles tables with unique names containing the required columns. |
Test Method |
|
Reference |
Clause 2.2.8.1.1 Req 54: |
Test Type |
Basic |
Table Data Values
Test Case ID |
/opt/tiles/tile_pyramid/data/data_values_zoom_levels |
Test Purpose |
Verify that the zoom level column values in each tile pyramid user data table are within the range of zoom levels defined by rows in the gpkg_tile_matrix table. |
Test Method |
|
Reference |
Clause 2.2.8.1.2 Req 55: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/tile_pyramid/data/data_values_tile_column |
Test Purpose |
Verify that the tile_column column values for each zoom level value in each tile pyramid user data table are within the range of columns defined by rows in the gpkg_tile_matrix table. |
Test Method |
|
Reference |
Clause 2.2.8.1.2 Req 56: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/tile_pyramid_data/data_values_tile_row |
Test Purpose |
Verify that the tile_row column values for each zoom level value in each tile pyramid user data table are within the range of rows defined by rows in the gpkg_tile_matrix table. |
Test Method |
|
Reference |
Clause 2.2.8.1.2 Req 57: |
Test Type |
Capability |
A.2.3. Extension Mechanism
Extensions
Data
Table Definition
Test Case ID |
/opt/extension_mechanism/extensions/data/table_def |
Test Purpose |
Verify that a gpkg_extensions table exists and has the correct definition. |
Test Method |
|
Reference |
Clause 2.3.2.1.1 Req 58: |
Test Type |
Basic |
Table Data Values
Test Case ID |
/opt/extension_metchanism/extensions/data/data_values_for_extensions |
Test Purpose |
Verify that every extension of a GeoPackage is registered in a row in the gpkg_extensions table |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 59: |
Test Type |
Capability |
Test Case ID |
/opt/extension_metchanism/extensions/data/data_values_table_name |
Test Purpose |
Verify that the table_name column values in the gpkg_extensions table are valid. |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 60: |
Test Type |
Capability |
Test Case ID |
/opt/extension_metchanism/extensions/data/data_values_column_name |
Test Purpose |
Verify that the column_name column values in the gpkg_extensions table are valid. |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 61: |
Test Type |
Capability |
Test Case ID |
/opt/extension_mechanism/extensions/data/data_values_extension_name |
Test Purpose |
Verify that the extension_name column values in the gpkg_extensions table are valid. |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 62: |
Test Type |
Capability |
Test Case ID |
/opt/extension_mechanism/extensions/data/data_values_definition |
Test Purpose |
Verify that the definition column value contains or references extension documentation |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 63: |
Test Type |
Capability |
Test Case ID |
/opt/extension_mechanism/extensions/data/data_values_scope |
Test Purpose |
Verify that the scope column value is “read-write” or “write-only” |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 64: |
Test Type |
Capability |
Annex B: Background and Context (Normative)
B.1. Background
An open standard non-proprietary platform-independent GeoPackage container for distribution and direct use of all kinds of geospatial data will increase the cross-platform interoperability of geospatial applications and web services. Standard APIs for access and management of GeoPackage data will provide consistent query and update results across such applications and services. Increased interoperability and result consistency will enlarge the potential market for such applications and services, particularly in resource-constrained mobile computing environments like cell phones and tablets. GeoPackages will become the standard containers for "MyGeoData" that are used as a transfer format by users and Geospatial Web Services and a storage format on personal and enterprise devices.
This OGC® GeoPackage Encoding Standard defines a GeoPackage as a self-contained, single-file, cross-platform, serverless, transactional, open source SQLite data container with table definitions, relational integrity constraints, an SQL API exposed via a "C" CLI and JDBC, and manifest tables that together act as an exchange and direct-use format for multiple types of geospatial data including vector features, features with raster attributes and tile matrix pyramids, especially on mobile / hand held devices in disconnected or limited network connectivity environments.
Table formats, definitions of geometry types and metadata tables, relational integrity constraints, and SQL API are interdependent specification facets of the SF-SQL [9][10][11] and SQL-MM (Spatial) [12] standards that serve as normative references for the vector feature portion of this standard.
This standard attempts to support and use relevant raster types, storage table definitions, and metadata from widely adopted implementations and existing standards such as WMTS [16] and ISO metadata [28], to integrate use of rasters as attributes of geospatial features, and to define relational integrity constraints and an SQL API thereon to provide a raster analogy to the SF-SQL and SF-MM data access and data quality assurance capabilities.
Conformance classes for this standard are classified as core (mandatory) and extension (optional). The simple core of an Empty GeoPackage contains two SQL tables.
Future versions of this standard may include requirements for elevation data and routes. Future enhancements to this standard, a future GeoPackage Web Service specification, and modifications to existing OGC Web Service (OWS) specifications to use GeoPackages as exchange formats may allow OWS to support provisioning of GeoPackages throughout an enterprise or information community.
B.2. Document terms and definitions
This document uses the standard terms defined in Subclause 5.3 of [OGC 06-121], which is based on the ISO/IEC Directives, Part 2. Rules for the structure and drafting of International Standards. In particular, the word "shall" (not "must") is the verb form used to indicate a requirement to be strictly followed to conform to this standard.
For the purposes of this document, the following terms and definitions apply.
- Empty GeoPackage
-
A GeoPackage that contains a
gpkg_spatial_ref_sys
table, agpkg_contents
table with row record(s) withdata_type
column values of "features" or "tiles", and corresponding features tables per clause Features and/or tiles tables per clause Tiles where the user data tables per clauses 2.1.6. and 2.2.8 exist but contain no rows. - Extended GeoPackage
-
A GeoPackage that contains any additional data elements (tables or columns) or SQL constructs (data types, indexes, constraints or triggers) that are not specified in this encoding standard.
- geolocate
-
identify a real-world geographic location
- GeoPackage file
-
a platform-independent SQLite database file that contains GeoPackage data and metadata tables with specified definitions, integrity assertions, format limitations and content constraints.
- GeoPackage SQLite Configuration
-
consists of the SQLite 3 software library and a set of compile- and runtime configurations options.
- GeoPackage SQLite Extension
-
a SQLite loadable extension that MAY provide SQL functions to support spatial indexes and SQL triggers linked to a SQLite library with specified configuration requirements to provide SQL API access to a GeoPackage.
- georectified
-
raster whose pixels have been regularly spaced in a geographic (i.e., latitude / longitude) or projected map coordinate system using ground control points so that any pixel can be geolocated given its grid coordinate and the grid origin, cell spacing, and orientation.
- orthorectified
-
georectified raster that has also been corrected to remove image perspective (camera angle tilt), camera and lens induced distortions, and terrain induced distortions using camera calibration parameters and DEM elevation data to accurately align with real world coordinates, have constant scale, and support direct measurement of distances, angles, and areas.
- Valid GeoPackage
-
A GeoPackage that contains features per clause Features and/or tiles per clause Tiles and row(s) in the
gpkg_contents
table withdata_type
column values of "features" and/or "tiles" describing the user data tables.
B.3. Conventions
Symbols (and abbreviated terms)
- ACID
-
Atomic, Consistent, Isolated, and Durable
- ASCII
-
American Standard Code for Information Interchange
- API
-
Application Program Interface
- BLOB
-
Binary Large OBject
- CLI
-
Call-Level Interface
- COTS
-
Commercial Off The Shelf
- DEM
-
Digital Elevation Model
- GPKG
-
GeoPackage
- GRD
-
Ground Resolved Distance
- EPSG
-
European Petroleum Survey Group
- FK
-
Foreign Key
- IETF
-
Internet Engineering Task Force
- IIRS
-
Image Interpretability Rating Scale
- IRARS
-
Imagery Resolution Assessments and Reporting Standards (Committee)
- ISO
-
International Organization for Standardization
- JDBC
-
Java Data Base Connectivity
- JPEG
-
Joint Photographics Expert Group (image format)
- MIME
-
Multipurpose Internet Mail Extensions
- NIIRS
-
National Imagery Interpretability Rating Scale
- OGC
-
Open Geospatial Consortium
- PK
-
Primary Key
- PNG
-
Portable Network Graphics (image format)
- RDBMS
-
Relational Data Base Management System
- RFC
-
Request For Comments
- SQL
-
Structured Query Language
- SRID
-
Spatial Reference (System) Identifier
- UML
-
Unified Modeling Language
- UTC
-
Coordinated Universal Time
- XML
-
eXtensible Markup Language
- 1D
-
One Dimensional
- 2D
-
Two Dimensional
- 3D
-
Three Dimensional
B.4. Submitting Organizations (Informative)
The following organizations submitted this Encoding Standard to the Open Geospatial Consortium as a Request For Comment (RFC).
-
Envitia
-
Luciad
-
Sigma Bravo
-
The Carbon Project
-
U.S. Army Geospatial Center
-
U.S. National Geospatial Intelligence Agency
B.5. Document contributor contact points (Informative)
All questions regarding this document should be directed to the editor or the contributors:
Name | Organization | |
---|---|---|
Brett Antonides |
LNM Solutions |
brett.antonides<at>lmnsolutions.com |
Kevin Backe |
U.S. Army Geospatial Center GASD |
Kevin.Backe<at>usace.army.mil |
Roger Brackin |
Envitia |
roger.brackin<at>envitia.com |
Scott Clark |
LNM Solutions |
scott.clark<at>lmnsolutions.com |
David Cray |
U.S. Army Geospatial Center GASD |
David.Cray<at>usace.army.mil |
Paul Daisey |
Image Matters |
pauld<at>imagemattersllc.com |
Nathan P. Frantz |
U.S. Army Geospatial Center ERDC |
Nathan.P.Frantz<at>usace.army.mil |
Alessandro Furieri |
Spatialite |
a.furieri<at>lqt.it |
Randy Gladish |
Image Matters |
randyg<at>imagemattersllc.com |
Eric Gundersen |
MapBox |
eric<at>mapbox.com |
Brad Hards |
Sigma Bravo |
bhards<at>sigmabravo.com |
Jeff Harrison |
The Carbon Project |
jharrison<at>thecarbonproject.com |
Chris Holmes |
OpenGeo |
cholmes<at>9eo.org |
Sean Hogan |
Compusult |
sean<at>compusult.net |
Kirk Jensen |
Image Matters |
kirkj<at>imagemattersllc.com |
(chinese chars not working) Joshua |
Feng China University |
joshua<at>gis.tw |
Terry A. Idol |
U.S. National Geospatial Intelligence Agency |
Terry.A.Idol<at>nga.mil |
Drew Kurry |
Digital Globe |
dkurry<at>digitalglobe.com |
Steven Lander |
Reinventing Geospatial |
steven.lander<at>rgi-corp.com |
Tom MacWright |
MapBox |
tom<at>mapbox.com |
Joan Maso Pau |
Universitat Autònoma de Barcelona (CREAF) |
joan.maso<at>uab.es |
Kevin S. Mullane |
U.S. Army Geospatial Center GASD |
Kevin.S.Mullane<at>usace.army.mil |
(chinese chars not working) Yi-Min Huang |
Feng China University |
niner<at>gis.tw |
Andrea Peri |
Regione Toscana Italy |
andrea.peri<at>regione.toscana.it |
Paul Ramsey |
OpenGeo |
pramsey<at>opengeo.org |
Matthew L. Renner |
U.S. Army Geospatial Center ERDC |
Matthew.L.Renner<at>usace.army.mil |
Even Rouault |
Mines-Paris |
even.rouault<at>mines-paris.org |
Keith Ryden |
Environmental Systems Research Institute |
kryden<at>esri.com |
Scott Simmons |
CACI |
scsimmons<at>caci.com |
Ingo Simonis |
International Geospatial Services Institute |
ingo.simonis<at>igsi.eu |
Raj Singh |
Open Geospatial Consortium |
rsingh<at>opengeospatial.org |
Steve Smyth |
Open Site Plan |
steve<at>opensiteplan.org |
Donald V. Sullivan |
U.S. National Aeronautics and Space Administration |
donald.v.sullivan<at>nasa.gov |
Christopher Tucker |
Mapstory |
tucker<at>mapstory.org |
Benjamin T. Tuttle |
U.S. National Geospatial Intelligence Agency |
Benjamin.T.Tuttle<at>nga.mil |
Pepijn Van Eeckhoudt |
Luciad |
pepijn.vaneeckhoudt<at>luciad.com |
David G. Wesloh |
U.S. National Geospatial Intelligence Agency |
David.G.Wesloh<at>nga.mil |
Jeff Yutzler |
Image Matters |
jeffy<at>imagemattersllc.com |
Eric Zimmerman |
U.S. Army Geospatial Center ERDC |
Eric.Zimmerman<at>usace.army.mil |
B.6. Revision History (Informative)
Date | Rel | Editor | Paragraph modified | Description |
---|---|---|---|---|
2014-07-14 |
R11 |
Paul Daisey |
1.1.2.1.1 |
Remove “at a minimum” after “includes” in 2nd paragraph, 1st sentence; conflicts with Clause 1 |
2014-07-14 |
R11 |
Paul Daisey |
2.1.4.1.1 |
Req 20 42in insert space between 42 and in |
2014-07-14 |
R11 |
Paul Daisey |
2.2.8.1.1 |
Change Table 30 to Table 29 |
2014-07-14 |
R11 |
Paul Daisey |
2.5.2.1.1 |
Change access to accesses in 1st paragraph, 2nd sentence |
2014-07-14 |
R11 |
Paul Daisey |
Annex A, A.3.1.1.1 |
inAnnex E insert space between in and Annex |
2014-07-14 |
R11 |
Paul Daisey |
Annex A, A.3.1.1.1 |
43without insert space between 43 and without |
2014-07-14 |
R11 |
Paul Daisey |
Annex B, B.5 |
Change pepijn.vaneeckhoudt email from gmail to Luciad |
2014-07-14 |
R11 |
Paul Daisey |
Annex B, B.5 |
Change all "@" to “<at>” |
2014-07-14 |
R11 |
Paul Daisey |
Annex C, C.10 |
Remove UNIQUE from PK constraint |
2014-12-12 |
R11 |
Paul Daisey |
2.1.1 |
Add a footnote to "GeometryCollection" description |
2014-12-12 |
R11 |
Paul Daisey |
2.1.6.1.1 |
Add new Req 30b |
2014-12-12 |
R11 |
Paul Daisey |
Annex A, A.2.1.6.1.1 |
Add feature_table_geometry_column_type test |
2014-12-12 |
R11 |
Paul Daisey |
2.1.5.1.1 |
Add “and geometry types” to 1st paragraph 1st sentence |
2014-12-12 |
R11 |
Paul Daisey |
1.1.1.1.4 |
Add footnote to Req 6 |
2014-12-12 |
R11 |
Paul Daisey |
2.1.3.1.1 |
replace ISO 13249-3 with OGC 06-103r4 |
2014-12-12 |
R11 |
Paul Daisey |
2.1.3.1.1 |
Correct references in footnote 1: [13] becomes [9] and [16] becomes [12] |
2014-12-12 |
R11 |
Paul Daisey |
1.1.1.2.2 |
Remove “and run” from clause and Req 9 |
2014-12-12 |
R11 |
Paul Daisey |
1.1.1.2.2 |
Remove PRAGMA foreign_keys runtime option from Table 2 |
2014-12-12 |
R11 |
Paul Daisey |
Annex A, A.2.2.7.1.1 |
Change step 2 to “Not testable if less than 1” |
2014-12-12 |
R11 |
Paul Daisey |
Annex A, A.2.2.6.1.1 |
Remove obsolete provisions (unique, column order, other columns) from step 3 |
2014-12-12 |
R11 |
Paul Daisey |
2.1.6.1.2 |
Add sentences specifying unit of measure determination for geometry Z and M values. |
2014-12-12 |
R11 |
Paul Daisey |
1.1.3.1.1, Table 4 |
Change description column default value to ‘’ |
2014-12-12 |
R11 |
Paul Daisey |
Annex C, C.7, Table 29 |
Remove spurious “)” from tile_data column definition |
2014-12-12 |
R11 |
Paul Daisey |
Annex D, D.3, Table 39 |
Correct ISO 8601 timestamp GLOB expressions |
2015-03-16 |
R11 |
Scott Simmons |
entire document |
Minor format corrections |
2015-04-27 |
R11 |
Joe Brumley |
entire document |
Minor format corrections for corrigendum |
2015-06-10 |
R12 |
Brad Hards |
2.2.1 |
Fix typos |
2015-06-17 |
R12 |
Jeff Yutzler |
2.2.6.1.1 |
Clarify role of bounding box in Tile Matrix Set table https://github.com/opengeospatial/geopackage/issues/102 |
2015-06-17 |
R12 |
Jeff Yutzler |
2.2.7.1.2 |
Add new Req 44b https://github.com/opengeospatial/geopackage/issues/102 |
2015-06-24 |
R12 |
Jeff Yutzler |
1.1.2.1.2 |
Clarify Req 11 https://github.com/opengeospatial/geopackage/issues/110 |
2015-08-04 |
R12 |
Jeff Yutzler |
Figures 4, 5, 6 |
Correct multiplicity https://github.com/opengeospatial/geopackage/issues/117 |
2015-08-04 |
R12 |
Jeff Yutzler |
Annex I |
Update Footnote #18 (JFIF) to T.871 https://github.com/opengeospatial/geopackage/issues/104 |
2015-08-25 |
R12 |
Jeff Yutzler |
Whole document |
Remove revision markup https://github.com/opengeospatial/geopackage/issues/135 |
2015-08-25 |
R12 |
Jeff Yutzler |
Annex B, B.6 |
Remove old changes https://github.com/opengeospatial/geopackage/issues/133 |
2015-08-26 |
R12 |
Jeff Yutzler |
Annex B, B.6 |
Fix casing of minIsInclusive, maxIsInclusive, and description https://github.com/opengeospatial/geopackage/issues/130 |
2015-08-25 |
R12 |
Jeff Yutzler |
Annex B, B.6 |
Clarify rules for case sensitivity for views, triggers, constraints https://github.com/opengeospatial/geopackage/issues/131 |
2015-09-09 |
R12 |
Brad Hards |
Intro |
Fix typos |
2015-09-29 |
R12 |
Brad Hards |
1.1.3.1.1 |
Fix typos |
2015-09-29 |
R12 |
Jeff Yutzler |
1.1.3.1.1 |
User-defined tables do not need to have lowercase column names https://github.com/opengeospatial/geopackage/issues/144 |
2015-10-19 |
R12 |
Jeff Yutzler |
Annex F, F.4 |
|
2015-10-29 |
R12 |
Brad Hards |
1.1.3.1.1 |
Fix typos |
2015-11-09 |
R12 |
Jeff Yutzler |
Multiple |
Fix typos |
2015-11-19 |
R12 |
Jeff Yutzler |
Multiple |
Numerous administrative edits https://github.com/opengeospatial/geopackage/issues/160 |
2015-11-26 |
R12 |
Jeff Yutzler |
Annex F, F.9 |
|
2015-11-26 |
R12 |
Jeff Yutzler |
Annex F |
Collapse all extensions into a single annex https://github.com/opengeospatial/geopackage/issues/132 |
2015-11-26 |
R12 |
Jeff Yutzler |
Annex F, F.8, F.9 |
Demote Metadata and Schema sections to extensions https://github.com/opengeospatial/geopackage/issues/147 |
2015-11-26 |
R12 |
Jeff Yutzler |
Annex E |
Update extension template https://github.com/opengeospatial/geopackage/issues/165 |
2015-11-26 |
R12 |
Jeff Yutzler |
Annex F, F.10 |
Create new extension for CRS WKT https://github.com/opengeospatial/geopackage/issues/137 |
2015-12-02 |
R12 |
Jeff Yutzler |
Annex A, Annex F |
Clean ATS references https://github.com/opengeospatial/geopackage/issues/169 |
2015-12-04 |
R12 |
Jeff Yutzler |
2.3.2.1.2 |
Update rules for listing extensions https://github.com/opengeospatial/geopackage/issues/175 |
2015-12-04 |
R12 |
Jeff Yutzler |
All Annexes |
Scrub annex references https://github.com/opengeospatial/geopackage/issues/176 |
2015-12-26 |
R12 |
Brad Hards |
2.3.2.1 |
Fix typos |
2015-12-26 |
R12 |
Jeff Yutzler |
Annex F.9 |
Make "identifier" unique in Table 42, Table 45 https://github.com/opengeospatial/geopackage/issues/183 |
2015-12-28 |
R12 |
Jeff Yutzler |
Annex A.1.1.2 |
Fix column names in ATS tests |
2016-01-20 |
R12 |
Jeff Yutzler |
1.1.1.1.1 |
Bump version number https://github.com/opengeospatial/geopackage/issues/188 |
B.7. Changes to the OGC® Abstract Specification
The OGC® Abstract Specification does not require changes to accommodate this OGC® standard.
B.8. Changes to OGC® Implementation Standards
None at present.
B.9. Potential Future Work (Informative)
Future versions of this standard MAY do the following:
* investigate GeoPackage implementation on SQLite version 4 [B25].
* include requirements for elevation data and routes.
* Future enhancements to this standard, a future GeoPackage Web Service specification and modifications to existing OGC Web Service (OWS) specifications to use GeoPackages as exchange formats MAY allow OWS to support provisioning of GeoPackages throughout an enterprise.
* include additional raster / image formats, including fewer restrictions on the image/tiff format.
* include additional SQL API routines for interrogation and conversion of raster / image BLOBs.
* add infrastructure to the metadata tables such as a temporal_columns
table that refers to the time properties of data records.
* specify a streaming synchronization protocol for GeoPackage as part of a future GeoPackage Web Service specification, and/or a future version of the GeoPackage and/or Web Synchronization Service specification(s).
* address symbology and styling information.
* include geographic / geodesic geometry types.
* create a GeoPackage Abstract Object Model to support data encodings other than SQL.
* add UTFGrid support.
Future versions of this standard and/or one for a GeoPackage Web Service MAY do the following: * address utilities for importing and exporting vector, raster and tile data in various formats. * address encryption of GeoPackages and/or individual tables or column values.
B.10. UML Notation
The diagrams that appear in this standard are presented using the Unified Modeling Language (UML) [B14] static structure diagrams. The UML notations used in this standard for RDBMS tables in a GeoPackage are described in UML Notation for RDBMS Tables below.
In this standard, the following two stereotypes of UML classes are used to represent RDBMS tables:
-
<<table>> An instantiation of a UML class as an RDMBS table.
-
<<column>> An instantiation of a UML attribute as an RDBMS table column.
In this standard, the following standard data types are used for RDBMS columns:
-
NULL – The value is a NULL value.
-
INTEGER – A signed integer, stored in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value
-
REAL – The value is a floating point value, stored as an 8-byte IEEE floating point number.
-
TEXT – A sequence of characters, stored using the database encoding (UTF-8, UTF-16BE or UTF-16LE).
-
BLOB – The value is a blob of data, stored exactly as it was input.
-
NONE – The value is a Date / Time Timestamp