Open Geospatial Consortium
External identifier of this OGC® document: http://www.opengis.net/doc/IS/geopackage/1.3
URL for this OGC® document: http://www.geopackage.org/spec
Internal reference number of this OGC® document: OGC 12-128r17
Version: 1.3
Category: OGC® Encoding Standard
Editor: Jeff Yutzler
Editor Emeritus: Paul Daisey
Previous Version: http://www.opengis.net/doc/IS/geopackage/1.2.1
Publication Date: TBD
_Approval Date: 2020-11-26
_Submission Date: 2020-08-19
_Original Version: http://www.opengis.net/doc/IS/geopackage/1.0
OGC® GeoPackage Encoding Standard
Copyright © 2021 Open Geospatial Consortium.
To obtain additional rights of use, visit http://www.opengeospatial.org/legal/
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. |
Document type: OGC® 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.
- 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
- F.11. Tiled Gridded Coverage Data
- F.12. Related Tables
- Annex G: Geometry Types (Normative)
- Annex H: Tiles Zoom Times Two Example (Informative)
- Annex I: Normative References (Normative)
- Annex J: Bibliography (Informative)
- Annex K: Endnotes
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
Introduction
A GeoPackage is an open, standards-based, platform-independent, portable, self-describing, compact format for transferring geospatial information. It is a platform-independent SQLite [I5] database file that contains the GeoPackage data and metadata tables shown in Figure 1 below.
The GeoPackage Encoding Standard (this document) describes a set of conventions for storing the following within an SQLite database:
-
vector features;
-
tile matrix sets of imagery and raster maps at various scales;
-
attributes (non-spatial data); and
-
extensions.
These conventions include table definitions, integrity assertions, format limitations, and content constraints. The required and supported content of a GeoPackage is entirely defined in the standard. These capabilities are built on a common base and the extension mechanism provides implementors a way to include additional functionality in their GeoPackages.
Since a GeoPackage is a database container, it supports direct use. This means that the data in a GeoPackage can be accessed and updated in a "native" storage format without intermediate format translations. GeoPackages that comply with the requirements in the standard and do not implement vendor-specific extensions are interoperable across all enterprise and personal computing environments. GeoPackages are particularly useful on mobile devices such as cell phones and tablets in communications environments where there is limited connectivity and bandwidth.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.
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 Extended GeoPackage is a GeoPackage that contains any additional data elements (tables or columns) or SQL constructs (views, data types, functions, indexes, constraints or triggers) that are not automatically maintained within the SQLite data file or that result in a change in behavior not specified in this encoding standard.
A GeoPackage MAY be "empty" (contain user data table(s) for vector features, non-spatial attributes, 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 [I12] to support spatial indexes and SQL triggers linked to a SQLite library with specified configuration requirements to provide SQL API [I1] [I2] [I3] [I4] access to a GeoPackage file. This standard does not address the issues listed in the Potential Future Work (Informative) 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.
SQLite is more flexible with regards to identifiers than many other RDBMS systems.
If GeoPackage data is to be used in other RDBMS systems, standard practices SHOULD be used to reduce potential interoperability risks.
For maximum interoperability, all GeoPackage table, view, column, trigger, and constraint name values SHOULD start with a lowercase character and only include lowercase characters, numbers 0-9, and underscores ( |
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.
1.1.1.1. Data
1.1.1.1.1. File Format
A GeoPackage SHALL contain a value of 0x47504B47 ("GPKG" in ASCII) in the "application_id" field of the SQLite database header to indicate that it is a GeoPackage. [K3] A GeoPackage SHALL contain an appropriate value in "user_version" field of the SQLite database header to indicate its version. The value SHALL be in integer with a major version, two-digit minor version, and two-digit bug-fix. For GeoPackage Version 1.3.0 this value is 0x0000283C (the hexadecimal value for 10300). [K4]
The maximum size of a GeoPackage file is about 140TB [K4a]. 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.
1.1.1.1.2. 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.
GeoPackage now has a registered media type (formerly MIME type) of |
1.1.1.1.3. File Contents
A GeoPackage SHALL only contain the data elements (tables, columns, or values) and SQL constructs (views, constraints, or triggers) specified in the core of this encoding standard (Features, Tiles, and Attributes). Extended GeoPackages MAY contain additional data elements and SQL constructs as specified through the Extension Mechanism.
The GeoPackage designation is designed to provide maximum interoperability between applications. In an Extended GeoPackage, the extension mechanism is used to provide additional capabilities in a way that maintains interoperability as much as possible. Developers are encouraged to consider the implications of extensions when designing their applications. Best practices include the following:
-
Designing in a way that anticipates the presence of unexpected extensions, e.g., gracefully handling unexpected columns, values, or encodings.
-
Using the RTree Spatial Indexes extension for GeoPackages containing a non-trivial amount of vector data.
-
Using the WKT for Coordinate Reference Systems extension, which is strongly recommended due to inherent weaknesses in the original standard for encoding coordinate reference systems.
The columns of tables in a GeoPackage SHALL only be declared using one of the data types specified in table Table 1. Extended GeoPackages MAY contain additional data types as specified through the Extension Mechanism.
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 core geometry types listed in Geometry Types (Normative) encoded per clause 2.1.3 or a geometry type encoded per an extension such as GeoPackage Non-Linear Geometry Types. 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. |
DATETIME |
ISO-8601 date/time string in the form YYYY-MM-DDTHH:MM:SS.SSSZ with T separator character and Z suffix for coordinated universal time (UTC) encoded in either UTF-8 or UTF-16. See TEXT. Stored as SQLite TEXT. |
1.1.1.1.4. File Integrity
The SQLite PRAGMA integrity_check SQL command SHALL return "ok" for a GeoPackage file. [K5]
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.
1.1.1.2. API
1.1.1.2.1. Structured Query Language (SQL)
A GeoPackage SQLite Configuration SHALL provide SQL access to GeoPackage contents via SQLite version 3 [I6] software APIs. [K6]
1.1.1.2.2. Every GPKG SQLite Configuration
The SQLite [I8] library has many compile time and run time options that MAY be used to configure SQLite for different uses. Use of SQLITE_OMIT options is not recommended because certain elements of the GeoPackage standard depend on the availability of SQLite functionality at runtime.
Every GeoPackage SQLite Configuration SHALL have the SQLite library compile time options specified in clause 1.1.1.2.2 table [every_gpkg_sqlite_config_table].
1.1.2. Spatial Reference Systems
1.1.2.1. Data
1.1.2.1.1. Table Definition
A GeoPackage SHALL include a gpkg_spatial_ref_sys
table per clause 1.1.2.1.1 Table Definition, Table Table 2 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 spatial reference system (SRS) 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) [I12] and shown in Table 2 below containing data that defines spatial reference systems.
Views of this table MAY be used to provide compatibility with the SQL/MM [I12] (see SQL/MM View of gpkg_spatial_ref_sys Definition SQL (Informative)) and OGC Simple Features SQL [I9][I10][I11] (Table 21) standards.
Column Name | Column Type | Column Description | NOT NULL flag | Key |
---|---|---|---|---|
|
TEXT |
Human readable name of this SRS |
true |
|
|
INTEGER |
Unique identifier for each Spatial Reference System within a GeoPackage |
true |
PK |
|
TEXT |
Case-insensitive name of the defining organization e.g. EPSG or epsg |
true |
|
|
INTEGER |
Numeric ID of the Spatial Reference System assigned by the organization |
true |
|
|
TEXT |
Well-known Text [I32] Representation of the Spatial Reference System |
true |
|
|
TEXT |
Human readable description of this SRS |
false |
1.1.2.1.2. Table Data Values
The srs_id
column is a primary key for this table and this primary key is used as a foreign key throughout GeoPackage.
The srd_id
column values are also found in the srs_id
attribute of the GeoPackage SQL Geometry Binary Format (see Requirement 33).
For convenience, srs_id
and organization_coordsys_id
values are typically the same.
However, there is no guarantee that SRS IDs will be globally unique across organizations.
GeoPackage clients should not make assumptions regarding the organization or definition of any SRS ID other than those defined in Requirement 11. |
Definition column WKT values in the gpkg_spatial_ref_sys
table define the Spatial Reference Systems used by feature geometries and tile images, unless these SRSs are unknown and therefore undefined as specified in Requirement 11. Values are constructed per the EBNF syntax in [I32] clause 7. EBNF name and number values may be obtained from any specified authority, e.g. [I13][I14]. 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 Table 3. The record with an srs_id
of 4326 SHALL correspond to WGS-84 [I15] as defined by EPSG [B3] in 4326 [I13][I14]. 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 |
definition |
description |
---|---|---|---|---|---|
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 GeoPackage contents (features, tiles, etc.).
1.1.3. Contents
The gpkg_contents
table is intended to provide a list of all geospatial contents in a GeoPackage. It provides identifying and descriptive information that an application can display to a user as a menu of geospatial data that is available for access and/or update.
1.1.3.1. Data
1.1.3.1.1. Table Definition
A GeoPackage file SHALL include a gpkg_contents
table per table Table 4 and gpkg_contents Table Definition SQL.
Column Name | Type | Description | Null | Default | Key |
---|---|---|---|---|---|
|
TEXT |
The name of the actual content (e.g., tiles, features, or attributes) table |
no |
PK |
|
|
TEXT |
Type of data stored in the table |
no |
||
|
TEXT |
A human-readable identifier (e.g. short name) for the table_name content |
yes |
UK |
|
|
TEXT |
A human-readable description for the table_name content |
yes |
'' |
|
|
DATETIME |
timestamp of last change to content, in ISO 8601 format |
no |
|
|
|
DOUBLE |
Bounding box minimum easting or longitude for all content in table_name. If tiles, this is informational and the tile matrix set should be used for calculating tile coordinates. |
yes |
||
|
DOUBLE |
Bounding box minimum northing or latitude for all content in table_name. If tiles, this is informational and the tile matrix set should be used for calculating tile coordinates. |
yes |
||
|
DOUBLE |
Bounding box maximum easting or longitude for all content in table_name. If tiles, this is informational and the tile matrix set should be used for calculating tile coordinates. |
yes |
||
|
DOUBLE |
Bounding box maximum northing or latitude for all content in table_name. If tiles, this is informational and the tile matrix set should be used for calculating tile coordinates. |
yes |
||
|
INTEGER |
Spatial Reference System ID: |
yes |
FK |
1.1.3.1.2. Table Data Values
The table_name
column value in a gpkg_contents
table row SHALL contain the name of a SQLite table or view.
The data_type
specifies the type of content contained in the table, for example "features" per clause Features, "attributes" per clause Attributes, "tiles" per clause Tiles, or an implementer-defined value for other data tables per clause in an Extended GeoPackage.
The last_change
SHOULD contain the timestamp of when the content in the referenced table was last updated, in ISO8601 format. Note that since it is not practical to ensure that this value is maintained properly in all cases, this value should be treated as informative.
Values of the gpkg_contents
table last_change
column SHALL be in ISO 8601 [I29] format containing a complete date plus UTC hours, minutes, seconds and a decimal fraction of a second, with a 'Z' ('zulu') suffix indicating UTC. The ISO8601 format is as defined by the strftime function '%Y-%m-%dT%H:%M:%fZ' format string applied to the current time. [K7]
The bounding box (min_x
, min_y
, max_x
, max_y
) provides an informative bounding box of the content. Applications may use this bounding box as the extents of a default view but there are no requirements that this bounding box be exact or represent the minimum bounding box of the content. The values are in the units specified by that CRS.
Values of the gpkg_contents
table srs_id
column SHALL reference values in the gpkg_spatial_ref_sys
table srs_id
column.
When |
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. At a minimum, a GeoPackage SHOULD contain at least one user data table as defined by the Features, Tiles, or Attributes options in clauses Features, Tiles, and Attributes respectively.
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 [I9][I10][I11][I12] 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) [I12] geometry model shown in Figure 2 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.
A brief description of each geometry type is provided below. A more detailed description can be found in ISO 13249-3 [I12].
-
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. [K8]
-
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
2.1.2.1. Data
2.1.2.1.1. 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
2.1.3.1. Data
2.1.3.1.1. 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; (4) double[] envelope; (5) } StandardGeoPackageBinary { GeoPackageBinaryHeader header; WKBGeometry geometry; (6) }
1 | 'GP' in ASCII |
2 | 8-bit unsigned integer, 0 = version 1 |
3 | see bit layout of GeoPackageBinary flags byte |
4 | the SRS ID, with the endianness specified by the byte order flag |
5 | see envelope contents indicator code below, with the endianness specified by the byte order flag |
6 | per OGC 06-103r4 [I9] [K9] [K10] |
The axis order in WKB stored in a GeoPackage follows the de facto standard for axis order in WKB and is therefore always (x,y{,z}{,m}) where x is easting or longitude, y is northing or latitude, z is optional elevation, and m is optional measure. This ordering explicitly overrides the axis order as specified in the SRS metadata, applying Case 4 from OGC 08-038r7, Revision to Axis Order Policy and Recommendations[K11]. This was done to maintain consistency with previous implementations of WKB that predated the OGC policy. |
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. For all core and extended geometry types. See Geometry Types (Normative).
-
1: ExtendedGeoPackageBinary. For user-defined geometry types. 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 SRS_ID and envelope values in header (1-bit Boolean)
-
0: Big Endian (most significant byte first)
-
1: Little Endian (least significant byte first)
-
The endianness specified by the B flag technically only pertains to header values, and not to the endianness of the WKBGeometry values themselves. The WKBGeometry has its own endianness flag as described in OGC 06-103r4. These values SHOULD be the same for consistency reasons. |
When the WKBGeometry in a GeoPackageBinary is empty, the following SHALL be done:
-
The empty geometry flag SHALL be set.
-
The envelope contents indicator code SHALL be 0 indicating no envelope.
-
If the geometry is a Point, it SHALL be encoded with each coordinate value 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. (This is because Well-Known Binary as defined in OGC 06-103r4 [I9] does not provide a standardized encoding for an empty point set, i.e., 'Point Empty' in Well-Known Text.)
In GeoPackage versions 1.2.1 and prior, the requirements for handling an empty geometry were underspecified. Some otherwise compliant GeoPackages before version 1.3.0 may not comply with all three sub-requirements. This may cause false negative results when querying for empty geometries. |
2.1.4. SQL Geometry Types
2.1.4.1. Data
2.1.4.1.1. Core Types
A GeoPackage SHALL store feature table geometries with the basic simple feature geometry types (Geometry, Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection) in Geometry Types (Normative) Table 21 in the GeoPackageBinary geometry encoding format.
2.1.5. Geometry Columns
2.1.5.1. Data
2.1.5.1.1. Table Definition
A GeoPackage with a gpkg_contents
table row with a "features" data_type
SHALL contain a gpkg_geometry_columns
table per Table 5 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 | Null | Key |
---|---|---|---|---|
|
TEXT |
Name of the table containing the geometry column |
no |
PK, FK |
|
TEXT |
Name of a column in the feature table that is a Geometry Column |
no |
PK |
|
TEXT |
Name from Table 21 or Table 22 in Geometry Types (Normative) |
no |
|
|
INTEGER |
Spatial Reference System ID: |
no |
FK |
|
TINYINT |
0: z values prohibited; 1: z values mandatory; 2: z values optional |
no |
|
|
TINYINT |
0: m values prohibited; 1: m values mandatory; 2: m values optional |
no |
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 MAY be used to provide compatibility with the SQL/MM [I12] SQL/MM View of gpkg_geometry_columns Definition SQL (Informative) and OGC Simple Features SQL [I9][I10][I11] SF/SQL VIEW of gpkg_geometry_columns Definition SQL (Informative) specifications.
2.1.5.1.2. Table Data Values
The gpkg_geometry_columns
table 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 srs_id
value in a gpkg_geometry_columns
table row SHALL match the srs_id
column value from the corresponding row in the gpkg_contents
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
2.1.6.1. Data
2.1.6.1.1. 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. [K12]
A GeoPackage MAY contain tables containing vector features.
Every such feature table SHALL be structured consistently with Table 6 and sample_feature_table Table Definition SQL (Informative).
A feature table SHALL have a primary key column of type INTEGER and that column SHALL act as a rowid
alias.
The integer primary key of a feature table allows features to be linked to row level metadata records in the |
A GeoPackage MAY contain views containing vector features. Every such feature view SHALL have a first column of type INTEGER and that column SHALL contain unique values for each row.
Since the concept of primary keys does not exist for views in SQLite, this requirement provides a way to produce a compliant feature view with a discoverable key-like column[K17]. |
A feature table or view 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 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[K6a] primary key |
N/A[K6b] |
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 |
2.1.6.1.2. 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 [K13].
Allowed geometry types are defined in Geometry Types (Normative) and shown in part in Figure 2.
If the geometry type_name
value is "GEOMETRY" then the feature table geometry column MAY contain geometries of any allowed geometry type.
This type name is to be used when the geometry type is unknown or if multiple geometry types will be present in the same table (e.g., POLYGON and MULTIPOLYGON).
If the geometry type_name
value is "GEOMETRYCOLLECTION" then the feature table geometry column MAY contain geometries of type GeometryCollection containing zero or more geometries of any allowed 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
The Tiles option specifies a mechanism for storing raster data in tile pyramids. "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" refers to an individual raster image such as a PNG or JPEG that covers a specific geographic area. "Tile matrix" refers to rows and columns of tiles that all have the same spatial extent and resolution at a particular zoom level[K14] "Tile matrix set" refers to the definition of a tile pyramid’s tiling structure. This mechanism is based on the model for tile matrix sets described in Section 6 of [I16].
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. The tables or views that implement the GeoPackage tile store data / metadata model are described and discussed individually in the following subsections.
The tile store data / metadata model and conventions 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, should store sufficient metadata to enable its intended use.
2.2.2. Contents
2.2.2.1. Data
2.2.2.1.1. 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 precede 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) [I16] Annex E for additional examples of both conventions.
2.2.3.1. Data
2.2.3.1.1. Zoom Times Two
In a GeoPackage that contains a tile pyramid user data table that contains tile data, by default [K15], 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.5.1. Data
2.2.5.1.1. MIME Type JPEG
Requirements 36 and 37 in combination allow a tile pyramid user data table to contain PNG or JPG tiles. They may be mixed and matched within the same table. |
2.2.6. Tile Matrix Set
2.2.6.1. Data
2.2.6.1.1. Table Definition
The gpkg_tile_matrix_set table 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.
A GeoPackage that contains a tile pyramid user data table SHALL contain gpkg_tile_matrix_set
table per Table Definition, Table 7 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 the tile matrix set |
no |
||
|
DOUBLE |
Bounding box minimum northing or latitude for the tile matrix set |
no |
||
|
DOUBLE |
Bounding box maximum easting or longitude for the tile matrix set |
no |
||
|
DOUBLE |
Bounding box maximum northing or latitude for the tile matrix set |
no |
2.2.6.1.2. Table Data Values
The bounding box defined by min_x
, max_x
, min_y
, and max_y
SHALL be exact so that the bounding box coordinates for individual tiles in a tile pyramid MAY be calculated from those values. All tiles present in the tile pyramid SHALL fall within this bounding box.
Since 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.
A bounding box MAY be larger than the minimum bounding rectangle around the actual tiles in that pyramid. This allows tile matrix pyramids to be sparsely populated or even empty.
Values of the gpkg_tile_matrix_set
table_name
column SHALL reference values in the gpkg_contents
table_name
column for rows with a data type of "tiles"[K18].
The gpkg_tile_matrix_set table 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.
The srs_id
value in a gpkg_tile_matrix_set
table row SHALL match the srs_id
column value from the corresponding row in the gpkg_contents
table.
2.2.7. Tile Matrix
2.2.7.1. Data
2.2.7.1.1. Table Definition
A GeoPackage that contains a tile pyramid user data table SHALL contain a gpkg_tile_matrix
table per clause 2.2.7.1.1 Table Definition, Table Table 8 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 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.
2.2.7.1.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".[K19]
The gpkg_tile_matrix
table 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.
Tile matrices are numbered from top left to bottom right (zero-indexed) so the top left tile is (0,0). (This follows the convention used by by WMTS [I16].) Tile matrices may be sparsely populated – no specific tile or even tile matrix must be present. If the global tile matrix set covers the whole earth, then zoom level 0, tile (0,0) is the whole world.
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.
When zoom_level
column values in the gpkg_tile_matrix
table are sorted in ascending order, the pixel_x_size
and pixel_y_size
column values in the gpkg_tile_matrix
table SHALL appear sorted in descending order.
Tiles MAY or MAY NOT be provided for level 0 or any other particular zoom level. [K21]
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.
[K22] 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. [K23]
2.2.8. Tile Pyramid User Data Tables
2.2.8.1. Data
2.2.8.1.1. Table Definition
A GeoPackage MAY contain tables containing tile pyramid user data for a single tile matrix set.
Every such tile pyramid user data table SHALL be structured consistently with Table Definition and EXAMPLE: tiles table Create Table SQL (Informative).
A table SHALL have a primary key column of type INTEGER and that column SHALL act as a rowid
alias.
The integer primary key of a tile pyramid user data table allows tiles to be linked to row level metadata records in the |
A GeoPackage MAY contain views containing tile pyramid user data for a single tile matrix set. Every such tile pyramid user data view SHALL have a first column of type INTEGER and that column SHALL contain unique values for each row.
Since the concept of primary keys does not exist for views in SQLite, this requirement provides a way to produce a compliant tile pyramid user data view with a discoverable key-like column[K17]. |
Column Name | Column Type | Column Description | Null | Key |
---|---|---|---|---|
|
INTEGER |
Autoincrement[K6a] primary key |
N/A[K6b] |
PK |
|
INTEGER |
min(zoom_level) <= |
no |
UK |
|
INTEGER |
0 to |
no |
UK |
|
INTEGER |
0 to |
no |
UK |
|
BLOB |
Of an image MIME type specified in clauses Tile Encoding PNG, Tile Encoding JPEG, Tiles Encoding WebP |
no |
Though this standard does not technically mandate the use of an indexing mechanism in a tiles table, the lack of such an index, e.g., a |
2.2.8.1.2. Table Data Values
Each tile pyramid user data table or view [K24] 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. [K25]
2.3. Extension Mechanism
2.3.1. Introduction
A GeoPackage extension is a set of one or more requirements clauses that either profiles / extends existing requirements clauses in the GeoPackage standard or adds new requirements clauses. Existing requirement clause extension examples include additional geometry types, additional SQL geometry functions, and additional tile image formats. New requirement clause extension examples include spatial indexes, triggers, additional tables, other BLOB column encodings, and other SQL functions. Files that use one or more extensions are by definition Extended GeoPackages. Extensions that have been already approved by OGC are presented in Registered Extensions (Normative). However, additional extensions MAY be approved by OGC outside of the release cycle of this document.
We acknowledge that there are use cases not covered by this standard. Implementers are welcome to use the extension mechanism defined here to develop their own extensions. The extension mechanism provides advantages including discoverability (the extensions in use can be discovered by scanning a single table) and uniformity (declaring that an extension is in use indicates that a defined set of requirements are being met). However, this is a decision that should be made carefully as custom extensions do introduce interoperability risks.
OGC is unable to endorse extensions developed externally. Therefore an Extended GeoPackage containing extensions not developed by OGC will fail Requirement 4. However, a community of interest MAY waive that requirement in its own GeoPackage profile, with the caveat that it must bear the responsibility of endorsing the new extension(s).
Implementers that are interested in developing their own extensions are encouraged to contact OGC to ensure that the extensions are developed in accordance with OGC policies and in a way that minimizes risks to interoperability. OGC will consider adopting externally developed extensions that address a clear use case, have a sound technical approach, and have a commitment to implementation by multiple implementers.
GeoPackage extensions are documented using the GeoPackage Extension Template in GeoPackage Extension Template (Informative). Extensions are identified by a name of the form <author>_<extension name> where <author> indicates the person or organization that developed and maintains the extension. The author value "gpkg" is reserved for extensions that are developed, maintained, and approved by OGC. Implementers must use their own author names to register other extensions used in Extended GeoPackages.
2.3.2. Extensions
2.3.2.1. Data
2.3.2.1.1. Table Definition
A GeoPackage MAY contain a table named gpkg_extensions
.
If present this table SHALL be defined per clause 2.3.2.1.1 Table Definition, Table 10, and gpkg_extensions Table Definition SQL. An extension SHALL NOT modify the definition or semantics of existing columns. An extension MAY define additional tables or columns. An extension MAY allow new values or encodings for existing columns.
The gpkg_extensions
table in a GeoPackage is used to indicate that a particular extension applies to a GeoPackage, a table in a GeoPackage, or a column of a table in a GeoPackage.
An application that accesses a GeoPackage can query the gpkg_extensions
table instead of the contents of all the user data tables to determine if it has the required capabilities to read or write to tables with extensions, and to "fail fast" and return an error message if it does not.
Column Name | Col Type | Column Description | Null | Key |
---|---|---|---|---|
|
TEXT |
Name of the table that requires the extension. When NULL, the extension is required for the entire GeoPackage. SHALL NOT be NULL when the column_name is not NULL. |
yes |
Jointly Unique |
|
TEXT |
Name of the column that requires the extension. When NULL, the extension is required for the entire table. |
yes |
Jointly Unique |
|
TEXT |
The case sensitive name of the extension that is required, in the form <author>_<extension_name>. |
no |
Jointly Unique |
|
TEXT |
Permalink, URI, or reference to a document that defines the extension |
no |
|
|
TEXT |
Indicates scope of extension effects on readers / writers: 'read-write' or 'write-only' in lowercase. |
no |
2.3.2.1.2. Table Data Values
In an Extended GeoPackage, every extension SHALL be registered in a corresponding row in the gpkg_extensions
table. An extension SHALL NOT modify the definition or semantics of existing columns. An extension MAY define additional tables or columns. An extension MAY allow new values or encodings for existing columns.
Either the absence of a gpkg_extensions
table or the absence of rows in the gpkg_extensions
table SHALL indicate that the file is a GeoPackage (as opposed to an Extended GeoPackage).
Values of the gpkg_extensions
table_name
column MAY reference values in the gpkg_contents
table_name
, reference new tables required by that extension, or be NULL (to indicate an extension that requires no new tables).
Implementers should be aware of the fact that SQLite table names are not case sensitive and that table names in |
The column_name
column value in a gpkg_extensions
row SHALL be the name of a column in the table specified by the table_name
column value for that row, or be NULL.
Each extension_name
column value in a gpkg_extensions
row SHALL be a unique case sensitive value of the form <author>_<extension_name> where <author> indicates the person or organization that developed and
maintains the extension. The valid character set for <author> SHALL be [a-zA-Z0-9].
The valid character set for <extension_name> SHALL be [a-zA-Z0-9_].
An extension_name
for the "gpkg" author name SHALL be one of those defined in this encoding standard or in an OGC document (e.g., Best Practices Document or Encoding Standard) that extends it.
The author value "gpkg" is reserved for GeoPackage extensions that are developed and maintained by OGC. GeoPackage implementers use their own author names to register other extensions.
The definition column value in a gpkg_extensions
row SHALL contain a permalink, URI [I23], or reference to a document defining the extension as per the GeoPackage Extension Template (Informative).
Examples of how to fill out the GeoPackage Extension Template in GeoPackage Extension Template (Informative) are provided in Annex F. This column is not unique because an extension may define multiple tables.
The scope column value in a gpkg_extensions
row SHALL be lowercase "read-write" for an extension that affects both readers and writers, or "write-only" for an extension that affects only writers.
Some extensions do not impose any additional requirements on software that accesses a GeoPackage in a read-only fashion. An example of this is an extension that defines an SQL trigger that uses a non-standard SQL function defined in a GeoPackage SQLite Extension. Triggers are only invoked when data is written to the GeoPackage, so usage of this type of extension can be safely ignored for read-only access. This is indicated by a gpkg_extensions.scope column value of "write-only".
2.4. Attributes
2.4.1. Introduction
Non-spatial attribute data are sets (or tuples or rows) of observations that may not have an explicit geometry property. In GeoPackage, this data is stored in user-defined attribute tables. These tables may contain properties such as an ID or geo-locatable address that allow them to be relationally linkable to rows in other attribute, feature or tile tables.
Examples of attribute data include:
-
meteorological readings from a weather station
-
flow readings from a stream gauge
-
traffic volumes from embedded highway sensors
-
lists of customers
-
delivery stops
-
work orders
2.4.2. Contents
2.4.2.1. Data
2.4.2.1.1. Contents Table - Attributes Row
The gpkg_contents
table SHALL contain a row with a data_type
column value of "attributes" for each attributes data table or view.
2.4.3. Attributes User Data Tables
2.4.3.1. Data
2.4.3.1.1. Table Definition
Non-spatial attribute data is stored in user-defined Attribute tables. Attribute sets are rows in an Attribute table. The attributes are columns in a Attribute table. (A GeoPackage is not required to contain any Attribute data tables. Attribute data tables in a GeoPackage may be empty.)
A GeoPackage MAY contain tables containing attribute sets. Every such attribute table SHALL be structured consistently with Table 11 and EXAMPLE: Attributes table Create Table SQL (Informative).
A table SHALL have a primary key column of type INTEGER and that column SHALL act as a rowid
alias.
The integer primary key of an attributes table allows features to be linked to row level metadata records in the |
A GeoPackage MAY contain views containing attributes. Every such attributes view SHALL have a first column of type INTEGER and that column SHALL contain unique values for each row.
Since the concept of primary keys does not exist for views in SQLite, this requirement provides a way to produce a compliant attributes view with a discoverable key-like column[K17]. |
Column Name | Col Type | Column Description | Null | Key |
---|---|---|---|---|
|
INTEGER |
Autoincrement[K6a] primary key |
N/A[K6b] |
PK |
|
TEXT |
Text attribute of feature |
yes |
|
|
REAL |
Real attribute of feature |
yes |
|
|
BOOLEAN |
Boolean attribute of feature |
yes |
|
|
BLOB |
Photo of the area |
yes |
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.
Since GeoPackage is dependent on SQLite, implementors should monitor for security alerts related to SQLite and respond accordingly.
Annex A: Conformance / Abstract Test Suite (Normative)
A.1. Base
A.1.1. Core
A.1.1.1. SQLite Container
A.1.1.1.1. 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.x |
Test Method |
|
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 Table 1. |
Test Method |
|
Reference |
Table 1 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 |
A.1.1.1.2. 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 |
A.1.1.2. Spatial Reference Systems
A.1.1.2.1. Data
Table Definition
Test Case ID |
/base/core/gpkg_spatial_ref_sys/data/table_def |
Test Purpose |
Verify that the |
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 |
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 |
Test Method |
|
Reference |
Clause Clause 1.1.2.1.2 Req 12: |
Test Type |
Capability |
A.1.1.3. Contents
A.1.1.3.1. Data
Table Definition
Test Case ID |
/base/core/contents/data/table_def |
Test Purpose |
Verify that the |
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 |
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 |
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 |
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 |
Test Method |
|
Reference |
Clause 2 Req 17: |
Test Type |
Capability |
A.2.1. Features
Note: Some of these tests require a spatial engine or custom code beyond simple SQL. These tests are marked with a *.
A.2.1.1. Simple Features SQL Introduction
A.2.1.2. Contents
A.2.1.2.1. Data
Contents Table Feature Row
Test Case ID |
/opt/features/contents/data/features_row |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.1.2.1.1 Req 18: |
Test Type |
Capability |
A.2.1.3. Geometry Encoding
A.2.1.3.1. 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 |
Empty Geometries
Test Case ID |
/opt/features/geometry_encoding/data/empty_geometry |
Test Purpose |
Verify that empty geometries are encoded consistently in the StandardGeoPackageBinary format. |
Test Method |
|
Reference |
Clause 2.1.3.1.1 Req 152: |
Test Type |
Basic |
A.2.1.4. SQL Geometry Types
A.2.1.4.1. 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 |
A.2.1.5. Geometry Columns
A.2.1.5.1. Data
Table Definition
Test Case ID |
/opt/features/geometry_columns/data/table_def |
Test Purpose |
Verify that the |
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 |
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 |
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 |
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 |
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 |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 26: |
Test Type |
Capability |
Test Case ID |
/opt/features/geometry_columns/data/data_values_srs_id_match |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 146: |
Test Type |
Capability |
Test Case ID |
/opt/features/geometry_columns/data/data_values_z |
Test Purpose |
Verify that the |
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 |
Test Method |
|
Reference |
Clause 2.1.5.1.2 Req 28: |
Test Type |
Capability |
A.2.1.6. Vector Features User Data Tables
A.2.1.6.1. Data
Table Definition
Test Case ID |
/opt/features/vector_features/data/feature_table |
Test Purpose |
Verify that every vector feature table or view is present and that each has a discoverable integer primary key or key-like column. |
Test Method |
|
Reference |
Clause 2.1.6.1.1 Req 29: |
Reference |
Clause 2.1.6.1.1 Req 150: |
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 |
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 specified by the |
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 |
Test Method |
|
Reference |
Clause 2.1.6.1.2 Req 33: |
Test Type |
Capability |
A.2.2. Tiles
A.2.2.1. Contents
A.2.2.1.1. Data
Contents Table – Tiles Row
Test Case ID |
/opt/tiles/contents/data/tiles_row |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.2.2.1.1 Req 34: |
Test Type |
Capability |
A.2.2.2. Zoom Levels
A.2.2.2.1. 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 |
A.2.2.3. Tile Encoding PNG
A.2.2.3.1. 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 |
A.2.2.4. Tile Encoding JPEG
A.2.2.4.1. 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 |
A.2.2.5. Tile Matrix Set
A.2.2.5.1. Data
Table Definition
Test Case ID |
/opt/tiles/gpkg_tile_matrix_set/data/table_def |
Test Purpose |
Verify that the |
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 |
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 |
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 |
Test Method |
|
Reference |
Clause 2.2.6.1.2 Req 41: |
Test Type |
Capability |
Test Case ID |
/opt/tiles/gpkg_tile_matrix_set/data/data_values_srs_id_match |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.2.6.1.2 Req 147: |
Test Type |
Capability |
A.2.2.6. Tile Matrix
A.2.2.6.1. Data
Table Definition
Test Case ID |
/opt/tiles/gpkg_tile_matrix/data/table_def |
Test Purpose |
Verify that the |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
Test Method |
|
Reference |
Clause 2.2.7.1.2 Req 53: |
Test Type |
Capability |
A.2.2.7. Tile Pyramid User Data
A.2.2.7.1. Data
Table Definition
Test Case ID |
/opt/tiles/tile_pyramid/data/table_def |
Test Purpose |
Verify that the tile pyramids each have a table or view, that all required columns are present, and that the "id" column has unique values. |
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 |
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 |
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 |
Test Method |
|
Reference |
Clause 2.2.8.1.2 Req 57: |
Test Type |
Capability |
A.2.3. Extension Mechanism
A.2.3.1. Extensions
A.2.3.1.1. Data
Table Definition
Test Case ID |
/opt/extension_mechanism/data/table_def |
Test Purpose |
Verify that a |
Test Method |
|
Reference |
Clause 2.3.2.1.1 Req 58: |
Test Type |
Basic |
Table Data Values
Test Case ID |
/opt/extension_mechanism/data/data_values_for_extensions |
Test Purpose |
Verify that every extension of a GeoPackage is registered in a row in the |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 59: |
Test Type |
Capability |
Test Case ID |
/opt/extension_mechanism/data/data_values_table_name |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 60: |
Test Type |
Capability |
Test Case ID |
/opt/extension_mechanism/data/data_values_column_name |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 61: |
Test Type |
Capability |
Test Case ID |
/opt/extension_mechanism/data/data_values_extension_name |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 62: |
Test Type |
Capability |
Test Case ID |
/opt/extension_mechanism/data/data_values_definition |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 63: |
Test Type |
Capability |
Test Case ID |
/opt/extension_mechanism/data/data_values_scope |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.3.2.1.2 Req 64: |
Test Type |
Capability |
A.2.4. Attributes
A.2.4.1. Contents
A.2.4.1.1. Data
Contents Table – Attributes Row
Test Case ID |
/opt/attributes/contents/data/attributes_row |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Clause 2.4.2.1.1 Req 118 |
Reference |
Clause 2.4.3.1.1 Req 119 |
Reference |
Clause 2.4.3.1.1 Req 151 |
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 [I9][I10][I11] and SQL-MM (Spatial) [I12] 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 [I16] and ISO metadata [I28], 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.
- tile
-
a rectangular pictorial representation of geographic data, often part of a set of such elements, covering a spatially contiguous extent and sharing similar information content and graphical styling, which can be uniquely defined by a pair of indexes for the column and row along with an identifier for the tile matrix.
- tile matrix
-
a collection of tiles for a fixed scale
- tile pyramid
-
a collection of tile matrices defined at different scales
- 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
- UK
-
Unique Key
- 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 |
Chris Clark |
Compusult |
chrisc<at>compusult.net |
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 |
Rich Fecher |
Radiant Solutions |
richard.fecher<at>radiantsolutions.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 |
Frederic Houbie |
Luciad |
frederic.houbie<at>luciad.com |
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 |
Brian Osborn |
CACI |
bosborn<at>caci.com |
(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-02-10 |
R10 |
Paul Daisey |
All |
1.0.0 |
2015-04-20 |
R11 |
Paul Daisey |
All |
1.0.1 |
2015-08-04 |
R12 |
Jeff Yutzler |
All |
1.1.0 |
2017-08-25 |
R14 |
Jeff Yutzler |
All |
1.2.0 |
2018-09-06 |
R15 |
Jeff Yutzler |
All |
1.2.1 |
Detailed release notes for this version of GeoPackage are available at: https://gitlab.com/imagemattersllc/ogc18-066/-/blob/master/rn.adoc. |
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 Figure 3 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
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)
C.1. gpkg_spatial_ref_sys
CREATE TABLE gpkg_spatial_ref_sys (
srs_name TEXT NOT NULL,
srs_id INTEGER PRIMARY KEY,
organization TEXT NOT NULL,
organization_coordsys_id INTEGER NOT NULL,
definition TEXT NOT NULL,
description TEXT
);
CREATE VIEW st_spatial_ref_sys AS
SELECT
srs_name,
srs_id,
organization,
organization_coordsys_id,
definition,
description
FROM gpkg_spatial_ref_sys;
CREATE VIEW spatial_ref_sys AS
SELECT
srs_id AS srid,
organization AS auth_name,
organization_coordsys_id AS auth_srid,
definition AS srtext
FROM gpkg_spatial_ref_sys;
C.2. gpkg_contents
CREATE TABLE gpkg_contents (
table_name TEXT NOT NULL PRIMARY KEY,
data_type TEXT NOT NULL,
identifier TEXT UNIQUE,
description TEXT DEFAULT '',
last_change DATETIME NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
min_x DOUBLE,
min_y DOUBLE,
max_x DOUBLE,
max_y DOUBLE,
srs_id INTEGER,
CONSTRAINT fk_gc_r_srs_id FOREIGN KEY (srs_id) REFERENCES gpkg_spatial_ref_sys(srs_id)
);
C.3. gpkg_geometry_columns
CREATE TABLE gpkg_geometry_columns (
table_name TEXT NOT NULL,
column_name TEXT NOT NULL,
geometry_type_name TEXT NOT NULL,
srs_id INTEGER NOT NULL,
z TINYINT NOT NULL,
m TINYINT NOT NULL,
CONSTRAINT pk_geom_cols PRIMARY KEY (table_name, column_name),
CONSTRAINT uk_gc_table_name UNIQUE (table_name),
CONSTRAINT fk_gc_tn FOREIGN KEY (table_name) REFERENCES gpkg_contents(table_name),
CONSTRAINT fk_gc_srs FOREIGN KEY (srs_id) REFERENCES gpkg_spatial_ref_sys (srs_id)
);
CREATE VIEW st_geometry_columns AS
SELECT
table_name,
column_name,
"ST_" || geometry_type_name,
g.srs_id,
srs_name
FROM gpkg_geometry_columns as g JOIN gpkg_spatial_ref_sys AS s
WHERE g.srs_id = s.srs_id;
CREATE VIEW geometry_columns AS
SELECT
table_name AS f_table_name,
column_name AS f_geometry_column,
code4name (geometry_type_name) AS geometry_type,
2 + (CASE z WHEN 1 THEN 1 WHEN 2 THEN 1 ELSE 0 END) + (CASE m WHEN 1 THEN 1 WHEN 2 THEN 1 ELSE 0 END) AS coord_dimension,
srs_id AS srid
FROM gpkg_geometry_columns;
Implementer must provide code4name(geometry_type_name) SQL function |
C.4. sample_feature_table (Informative)
CREATE TABLE sample_feature_table (
id INTEGER PRIMARY KEY AUTOINCREMENT,
geometry GEOMETRY,
text_attribute TEXT,
real_attribute REAL,
boolean_attribute BOOLEAN,
raster_or_photo BLOB
);
C.5. gpkg_tile_matrix_set
CREATE TABLE gpkg_tile_matrix_set (
table_name TEXT NOT NULL PRIMARY KEY,
srs_id INTEGER NOT NULL,
min_x DOUBLE NOT NULL,
min_y DOUBLE NOT NULL,
max_x DOUBLE NOT NULL,
max_y DOUBLE NOT NULL,
CONSTRAINT fk_gtms_table_name FOREIGN KEY (table_name) REFERENCES gpkg_contents(table_name),
CONSTRAINT fk_gtms_srs FOREIGN KEY (srs_id) REFERENCES gpkg_spatial_ref_sys (srs_id)
);
C.6. gpkg_tile_matrix
CREATE TABLE gpkg_tile_matrix (
table_name TEXT NOT NULL,
zoom_level INTEGER NOT NULL,
matrix_width INTEGER NOT NULL,
matrix_height INTEGER NOT NULL,
tile_width INTEGER NOT NULL,
tile_height INTEGER NOT NULL,
pixel_x_size DOUBLE NOT NULL,
pixel_y_size DOUBLE NOT NULL,
CONSTRAINT pk_ttm PRIMARY KEY (table_name, zoom_level),
CONSTRAINT fk_tmm_table_name FOREIGN KEY (table_name) REFERENCES gpkg_contents(table_name)
);
INSERT INTO gpkg_tile_matrix VALUES (
"sample_tile_pyramid",
0,
1,
1,
512,
512,
2.0,
2.0
);
C.7. sample_tile_pyramid (Informative)
CREATE TABLE sample_tile_pyramid (
id INTEGER PRIMARY KEY AUTOINCREMENT,
zoom_level INTEGER NOT NULL,
tile_column INTEGER NOT NULL,
tile_row INTEGER NOT NULL,
tile_data BLOB NOT NULL,
UNIQUE (zoom_level, tile_column, tile_row)
)
INSERT INTO sample_matrix_pyramid VALUES (
NULL,
1,
1,
1,
"BLOB VALUE"
)
C.8. gpkg_extensions
CREATE TABLE gpkg_extensions (
table_name TEXT,
column_name TEXT,
extension_name TEXT NOT NULL,
definition TEXT NOT NULL,
scope TEXT NOT NULL,
CONSTRAINT ge_tce UNIQUE (table_name, column_name, extension_name)
);
C.9. sample_attributes_table (Informative)
CREATE TABLE sample_attributes (
id INTEGER PRIMARY KEY AUTOINCREMENT,
text_attribute TEXT,
real_attribute REAL,
boolean_attribute BOOLEAN,
raster_or_photo BLOB
)
INSERT INTO sample_attributes(text_attribute, real_attribute, boolean_attribute, raster_or_photo) VALUES (
"place",
1,
true,
"BLOB VALUE"
)
Annex D: Trigger Definition SQL (Informative)
This annex describes triggers that MAY be created in GeoPackages to verify conformance to specific requirements. GeoPackage clients SHOULD recognize that these triggers may be present in GeoPackages and be prepared to handle errors raised by the triggers. It is possible that new GeoPackage extensions may extend certain GeoPackage requirements in ways that would make one or more of these triggers unnecessary or incorrect. It is the responsibility of the system adding the extension to the GeoPackage to check for the presence of relevant triggers and to replace them with corrected or benign ones. Simply dropping the triggers may not be sufficient as some systems could naively reinstate them if they are detected to be missing.
D.1. gpkg_tile_matrix
CREATE TRIGGER 'gpkg_tile_matrix_zoom_level_insert'
BEFORE INSERT ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'insert on table ''gpkg_tile_matrix'' violates constraint: zoom_level cannot be less than 0')
WHERE (NEW.zoom_level < 0);
END
CREATE TRIGGER 'gpkg_tile_matrix_zoom_level_update'
BEFORE UPDATE of zoom_level ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'update on table ''gpkg_tile_matrix'' violates constraint: zoom_level cannot be less than 0')
WHERE (NEW.zoom_level < 0);
END
CREATE TRIGGER 'gpkg_tile_matrix_matrix_width_insert'
BEFORE INSERT ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'insert on table ''gpkg_tile_matrix'' violates constraint: matrix_width cannot be less than 1')
WHERE (NEW.matrix_width < 1);
END
CREATE TRIGGER 'gpkg_tile_matrix_matrix_width_update'
BEFORE UPDATE OF matrix_width ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'update on table ''gpkg_tile_matrix'' violates constraint: matrix_width cannot be less than 1')
WHERE (NEW.matrix_width < 1);
END
CREATE TRIGGER 'gpkg_tile_matrix_matrix_height_insert'
BEFORE INSERT ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'insert on table ''gpkg_tile_matrix'' violates constraint: matrix_height cannot be less than 1')
WHERE (NEW.matrix_height < 1);
END
CREATE TRIGGER 'gpkg_tile_matrix_matrix_height_update'
BEFORE UPDATE OF matrix_height ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'update on table ''gpkg_tile_matrix'' violates constraint: matrix_height cannot be less than 1')
WHERE (NEW.matrix_height < 1);
END
CREATE TRIGGER 'gpkg_tile_matrix_pixel_x_size_insert'
BEFORE INSERT ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'insert on table ''gpkg_tile_matrix'' violates constraint: pixel_x_size must be greater than 0')
WHERE NOT (NEW.pixel_x_size > 0);
END
CREATE TRIGGER 'gpkg_tile_matrix_pixel_x_size_update'
BEFORE UPDATE OF pixel_x_size ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'update on table ''gpkg_tile_matrix'' violates constraint: pixel_x_size must be greater than 0')
WHERE NOT (NEW.pixel_x_size > 0);
END
CREATE TRIGGER 'gpkg_tile_matrix_pixel_y_size_insert'
BEFORE INSERT ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'insert on table ''gpkg_tile_matrix'' violates constraint: pixel_y_size must be greater than 0')
WHERE NOT (NEW.pixel_y_size > 0);
END
CREATE TRIGGER 'gpkg_tile_matrix_pixel_y_size_update'
BEFORE UPDATE OF pixel_y_size ON 'gpkg_tile_matrix'
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'update on table ''gpkg_tile_matrix'' violates constraint: pixel_y_size must be greater than 0')
WHERE NOT (NEW.pixel_y_size > 0);
END
D.2. sample_feature_table
CREATE TRIGGER "sample_feature_table_real_insert"
BEFORE INSERT ON "sample_feature_table"
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'insert on table ''sample_feature_table''
violates constraint: real_attribute must be greater than 0')
WHERE NOT (NEW.real_attribute > 0);
END
CREATE TRIGGER "sample_feature_table_real_update"
BEFORE UPDATE OF "real_attribute" ON "sample_feature_table"
FOR EACH ROW BEGIN
SELECT RAISE (ABORT, 'update of ''real_attribute'' on table
''sample_feature_table'' violates constraint: real_attribute value
must be > 0')
WHERE NOT (NEW.real_attribute > 0);
END
where <t> and <c> are replaced with the names of the feature table and geometry column being inserted or updated.
D.3. sample_tile_pyramid
CREATE TRIGGER "sample_tile_pyramid_zoom_insert"
BEFORE INSERT ON "sample_tile_pyramid"
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'insert on table ''sample_tile_pyramid'' violates constraint: zoom_level not specified for table in gpkg_tile_matrix')
WHERE NOT (NEW.zoom_level IN (SELECT zoom_level FROM gpkg_tile_matrix WHERE table_name = 'sample_tile_pyramid')) ;
END
CREATE TRIGGER "sample_tile_pyramid_zoom_update"
BEFORE UPDATE OF zoom_level ON "sample_tile_pyramid"
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'update on table ''sample_tile_pyramid'' violates constraint: zoom_level not specified for table in gpkg_tile_matrix')
WHERE NOT (NEW.zoom_level IN (SELECT zoom_level FROM gpkg_tile_matrix WHERE table_name = 'sample_tile_pyramid')) ;
END
CREATE TRIGGER "sample_tile_pyramid_tile_column_insert"
BEFORE INSERT ON "sample_tile_pyramid"
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'insert on table ''sample_tile_pyramid'' violates constraint: tile_column cannot be < 0')
WHERE (NEW.tile_column < 0) ;
SELECT RAISE(ABORT, 'insert on table ''sample_tile_pyramid'' violates constraint: tile_column must by < matrix_width specified for table and zoom level in gpkg_tile_matrix')
WHERE NOT (NEW.tile_column < (SELECT matrix_width FROM gpkg_tile_matrix WHERE table_name = 'sample_tile_pyramid' AND zoom_level = NEW.zoom_level));
END
CREATE TRIGGER "sample_tile_pyramid_tile_column_update"
BEFORE UPDATE OF tile_column ON "sample_tile_pyramid"
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'update on table ''sample_tile_pyramid'' violates constraint: tile_column cannot be < 0')
WHERE (NEW.tile_column < 0) ;
SELECT RAISE(ABORT, 'update on table ''sample_tile_pyramid'' violates constraint: tile_column must by < matrix_width specified for table and zoom level in gpkg_tile_matrix')
WHERE NOT (NEW.tile_column < (SELECT matrix_width FROM gpkg_tile_matrix WHERE table_name = 'sample_tile_pyramid' AND zoom_level = NEW.zoom_level));
END
CREATE TRIGGER "sample_tile_pyramid_tile_row_insert"
BEFORE INSERT ON "sample_tile_pyramid"
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'insert on table ''sample_tile_pyramid'' violates constraint: tile_row cannot be < 0')
WHERE (NEW.tile_row < 0) ;
SELECT RAISE(ABORT, 'insert on table ''sample_tile_pyramid'' violates constraint: tile_row must by < matrix_height specified for table and zoom level in gpkg_tile_matrix')
WHERE NOT (NEW.tile_row < (SELECT matrix_height FROM gpkg_tile_matrix WHERE table_name = 'sample_tile_pyramid' AND zoom_level = NEW.zoom_level));
END
CREATE TRIGGER "sample_tile_pyramid_tile_row_update"
BEFORE UPDATE OF tile_row ON "sample_tile_pyramid"
FOR EACH ROW BEGIN
SELECT RAISE(ABORT, 'update on table ''sample_tile_pyramid'' violates constraint: tile_row cannot be < 0')
WHERE (NEW.tile_row < 0) ;
SELECT RAISE(ABORT, 'update on table ''sample_tile_pyramid'' violates constraint: tile_row must by < matrix_height specified for table and zoom level in gpkg_tile_matrix')
WHERE NOT (NEW.tile_row < (SELECT matrix_height FROM gpkg_tile_matrix WHERE table_name = 'sample_tile_pyramid' AND zoom_level = NEW.zoom_level));
END
Annex E: GeoPackage Extension Template (Informative)
Extension Title
Title of the Extension
Introduction
Description of extension
Extension Author
Author of extension, author_name.
Extension Name or Template
Name of the extension or definition of the template to create the name of extensions that should be used in gpkg_extensions
Extension Type
"Extension of Existing Requirement in Clause(s) XXX" or "New Requirement Dependent on Clause(s) YYY"
Applicability
Tables and/or columns on which this extension may be applied
Scope
Read-write or write-only with clarification if necessary
Requirements
Definition of extension and interdependencies with other extensions if any.
GeoPackage
Definition of extension data or MIME type(s)
Definition of extension tables or table templates
Definition of triggers or trigger templates
GeoPackage SQLite Configuration
Definition of SQLite configuration settings
Setting compile or runtime | Option | Shall / Not (Value) | Discussion |
---|---|---|---|
GeoPackage SQLite Extension
Definition of SQL functions
SQL Function | Description | Use |
---|---|---|
foo(bar, baz) : datatype |
Returns r when w |
Abstract Test Suite
All test cases required to verify conformance to this extension.
Examples (Informative)
Any example or samples demonstrating the extension in use.
Annex F: Registered Extensions (Normative)
This clause specifies requirements for GeoPackage extensions. Definitions of those extensions are in the form specified by the template in GeoPackage Extension Template (Informative).
Extension Name | Content Type |
---|---|
features |
|
features |
|
tiles |
|
tiles |
|
general |
|
features |
|
spatial reference systems |
|
coverages |
|
related tables |
F.1. GeoPackage Non-Linear Geometry Types
Introduction
This extension of clause SQL Geometry Types defines additional geometry types.
Clause 2.1.4 of the GeoPackage Version 1 Encoding Standard specifies support for the Geometry, Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection geometry types in the GeoPackageBinary geometry encoding format specified in clause 2.1.3. This extension specifies support for the additional CircularString, CompoundCurve, CurvePolygon, MultiCurve, MultiSurface, Curve, and Surface geometry types in the GeoPackage Binary geometry encoding format using the codes from Table 22.
Extension Author
GeoPackage SWG, author_name gpkg
Extension Name or Template
Extension names are constructed from the gpkg_geom_<gname> template where <gname> is the uppercase name of the extension geometry type from Table 22.
Extension Type
Extension of Existing Requirement in clause SQL Geometry Types
Applicability
This extension applies to any column specified in the gpkg_geometry_columns
table.
Scope
Read-write
Requirements
GeoPackage
(extends Requirement 25) The geometry_type_name
value in a gpkg_geometry_columns
row MAY be one of the uppercase extended non-linear geometry type names specified in Geometry Types (Normative).
The GeoPackageBinary geometry encoding format specified in clause Geometry Encoding SHALL be used to encode non-linear geometry types using the type codes in Geometry Types (Normative) table Table 22.
An extension name to specify a feature geometry extension type SHALL be defined for the "gpkg" author name using the "gpkg_geom_<gname>" template where <gname> is the uppercase name of the extension geometry type from Geometry Types (Normative) used in a GeoPackage.
A GeoPackage that contains a gpkg_geometry_columns
table or view with row records that specify extension geometry_type_name
column values SHALL contain a gpkg_extensions
table that contains row records with table_name
and column_name
values from the gpkg_geometry_columns
row records that identify extension type uses, and extension_name
column values for each of those geometry types constructed per the previous requirement [extension_geometry_types_extensions_name].
GeoPackage SQLite Configuration
None
GeoPackage SQLite Extension
SQL functions that operate on GeoPackageBinary geometries as specified in other extensions SHALL operate correctly on the non-linear geometries specified in this extension.
Abstract Test Suite
GeoPackage Extension Types
Test Case ID |
/extensions/geometry_types/data_values_geometry_type_name |
Test Purpose |
Verify that only allowed geometry types (including extended non-linear geometry types) are in use. |
Test Method |
|
Reference |
Annex F.1 Req 65: |
Test Type |
Capability |
Test Case ID |
/extensions/geometry_types/all_types_test_data |
Test Purpose |
Verify that geometries non-linear geometry types are stored in valid GeoPackageBinary format encodings. |
Test Method |
|
Reference |
Annex F.1 Req 66: |
Test Type |
Capability |
Extensions Name
Test Case ID |
/extensions/geometry_types/extension_name |
Test Purpose |
Verify that an extension name in the form gpkg_geom_<gname> is defined for each <gname> extension geometry type from Annex G used in a GeoPackage. |
Test Method |
|
Reference |
Annex F.1 Req 67: |
Test Type |
Basic |
Extensions Row
Test Case ID |
/extensions/geometry_types/extension_row |
Test Purpose |
Verify that the gpkg_extensions table contains a row with an extension_name in the form gpkg_geom_<gname> for each table_name and column_name in the gpkg_geometry_columns table with a <gname> geometry_type_name. |
Test Method |
|
Reference |
Annex F.1 Req 68: |
Test Type |
Capability |
F.2. User Defined Geometry Types Extension of GeoPackageBinary Geometry Encoding
On August 15, 2016 the GeoPackage SWG voted to remove this extension from the standard due to interoperability concerns. For more information see the release notes. The original extension may be found in http://www.geopackage.org/spec110/#extension_geometry_encoding. |
F.3. RTree Spatial Indexes
Introduction
The RTree Spatial Indexes extension provides a means to encode an RTree index for geometry values in a GeoPackage. An RTree index provides a significant performance advantage for searches with basic envelope spatial criteria that return subsets of the rows in a feature table with a non-trivial number (thousands or more) of rows.[K26]
Extension Author
GeoPackage SWG, author_name gpkg
.
Extension Name or Template
gpkg_rtree_index
Extension Type
New Requirement dependent on clauses Geometry Encoding and User Defined Geometry Types Extension of GeoPackageBinary Geometry Encoding.
Applicability
This extension applies to any column specified in the gpkg_geometry_columns
table.
Scope
Write-only, because it does not change the result of reads, although it may improve their performance.
Requirements
This extension uses the rtree implementation provided by the SQLite R*Tree Module extension documented at http://www.sqlite.org/rtree.html.
GeoPackage
The "gpkg_rtree_index" extension name SHALL be used as a gpkg_extensions
table extension_name
column value to specify implementation of spatial indexes on a geometry column.
A GeoPackage that implements spatial indexes SHALL have a gpkg_extensions
table that contains a row for each spatially indexed column with extension_name
"gpkg_rtree_index", the table_name
of the table with a spatially indexed column, the column_name
of the spatially indexed column, and a scope
of "write-only".
A GeoPackage SHALL implement spatial indexes on feature table geometry columns using the SQLite Virtual Table RTrees and triggers specified below.
The tables below contain SQL templates with variables.
Replace the following template variables with the specified values to create the required SQL statements:
<t>: The name of the feature table containing the geometry column
<c>: The name of the geometry column in <t> that is being indexed
<i>: The name of the integer primary key column in <t> as specified in Requirement 29
Create Virtual Table
RTree spatial indexes on geometry columns SHALL be created using the SQLite Virtual Table RTree extension. An application that creates a spatial index SHALL create it using the following SQL statement template:
CREATE VIRTUAL TABLE rtree_<t>_<c> USING rtree(id, minx, maxx, miny, maxy)
where <t> and <c> are replaced with the names of the feature table and geometry column being indexed. The rtree function id parameter becomes the virtual table 64-bit signed integer primary key id column, and the min/max x/y parameters are min- and max-value pairs (stored as 32-bit floating point numbers) for each dimension that become the virtual table data columns that are populated to create the spatial rtree index.
Load Spatial Index Values
The indexes provided by the SQLite Virtual Table RTree extension are not automatic indexes. This means the index data structure needs to be manually populated, updated and queried. Each newly created spatial index SHALL be populated using the following SQL statement
INSERT OR REPLACE INTO rtree_<t>_<c>
SELECT <i>, ST_MinX(<c>), ST_MaxX(<c>), ST_MinY(<c>), ST_MaxY(<c>) FROM <t> WHERE <c> NOT NULL AND NOT ST_IsEmpty(<c>);
where <t> and <c> are replaced with the names of the feature table and geometry column being indexed and <i> is replaced with the name of the feature table integer primary key column.
Define Triggers to Maintain Spatial Index Values
For each spatial index in a GeoPackage, corresponding insert, update and delete triggers that update the spatial index SHALL be present on the indexed geometry column. These spatial index triggers SHALL be defined as follows:
/* Conditions: Insertion of non-empty geometry
Actions : Insert record into rtree */
CREATE TRIGGER rtree_<t>_<c>_insert AFTER INSERT ON <t>
WHEN (new.<c> NOT NULL AND NOT ST_IsEmpty(NEW.<c>))
BEGIN
INSERT OR REPLACE INTO rtree_<t>_<c> VALUES (
NEW.<i>,
ST_MinX(NEW.<c>), ST_MaxX(NEW.<c>),
ST_MinY(NEW.<c>), ST_MaxY(NEW.<c>)
);
END;
/* Conditions: Update of geometry column to non-empty geometry
No row ID change
Actions : Update record in rtree */
CREATE TRIGGER rtree_<t>_<c>_update1 AFTER UPDATE OF <c> ON <t>
WHEN OLD.<i> = NEW.<i> AND
(NEW.<c> NOTNULL AND NOT ST_IsEmpty(NEW.<c>))
BEGIN
INSERT OR REPLACE INTO rtree_<t>_<c> VALUES (
NEW.<i>,
ST_MinX(NEW.<c>), ST_MaxX(NEW.<c>),
ST_MinY(NEW.<c>), ST_MaxY(NEW.<c>)
);
END;
/* Conditions: Update of geometry column to empty geometry
No row ID change
Actions : Remove record from rtree */
CREATE TRIGGER rtree_<t>_<c>_update2 AFTER UPDATE OF <c> ON <t>
WHEN OLD.<i> = NEW.<i> AND
(NEW.<c> ISNULL OR ST_IsEmpty(NEW.<c>))
BEGIN
DELETE FROM rtree_<t>_<c> WHERE id = OLD.<i>;
END;
/* Conditions: Update of any column
Row ID change
Non-empty geometry
Actions : Remove record from rtree for old <i>
Insert record into rtree for new <i> */
CREATE TRIGGER rtree_<t>_<c>_update3 AFTER UPDATE ON <t>
WHEN OLD.<i> != NEW.<i> AND
(NEW.<c> NOTNULL AND NOT ST_IsEmpty(NEW.<c>))
BEGIN
DELETE FROM rtree_<t>_<c> WHERE id = OLD.<i>;
INSERT OR REPLACE INTO rtree_<t>_<c> VALUES (
NEW.<i>,
ST_MinX(NEW.<c>), ST_MaxX(NEW.<c>),
ST_MinY(NEW.<c>), ST_MaxY(NEW.<c>)
);
END;
/* Conditions: Update of any column
Row ID change
Empty geometry
Actions : Remove record from rtree for old and new <i> */
CREATE TRIGGER rtree_<t>_<c>_update4 AFTER UPDATE ON <t>
WHEN OLD.<i> != NEW.<i> AND
(NEW.<c> ISNULL OR ST_IsEmpty(NEW.<c>))
BEGIN
DELETE FROM rtree_<t>_<c> WHERE id IN (OLD.<i>, NEW.<i>);
END;
/* Conditions: Row deleted
Actions : Remove record from rtree for old <i> */
CREATE TRIGGER rtree_<t>_<c>_delete AFTER DELETE ON <t>
WHEN old.<c> NOT NULL
BEGIN
DELETE FROM rtree_<t>_<c> WHERE id = OLD.<i>;
END;
where <t> and <c> are replaced with the names of the feature table and geometry column being indexed and <i> is replaced with the name of the feature table integer primary key column.
GeoPackage Versions 1.2.0 and prior have an incorrect update3 trigger that will fail in certain circumstances. It is strongly recommended to update older GeoPackages with the correct trigger presented here. The GeoPackage Executable Test Suite has been updated to accept either version of the trigger in older versions and to mandate the corrected version in versions after 1.2.0. |
GeoPackage SQLite Configuration
Definition of SQLite configuration settings
Setting compile or runtime | Option | Shall / Not (Value) | Discussion |
---|---|---|---|
compile |
SQLITE_ENABLE_RTREE |
Shall |
RTrees ares used for GeoPackage Spatial Indexes |
compile |
SQLITE_RTREE_INT_ONLY |
Not |
RTrees with floating point values are used for GeoPackage spatial indexes |
GeoPackage SQLite Extension
Definition of SQL functions
SQL Function | Description | Use |
---|---|---|
ST_IsEmpty(geom Geometry): integer |
Returns 1 if geometry value is empty, 0 if not empty, NULL if geometry value is NULL |
Test if a geometry value corresponds to the empty set |
ST_MinX(geom Geometry): real |
Returns the minimum X value of the bounding envelope of a geometry |
Update the spatial index on a geometry column in a feature table |
ST_MaxX(geom Geometry): real |
Returns the maximum Y value of the bounding envelope of a geometry |
Update the spatial index on a geometry column in a feature table |
ST_MinY(geom Geometry): real |
Returns the minimum X value of the bounding envelope of a geometry |
Update the spatial index on a geometry column in a feature table |
ST_MaxY(geom Geometry): real |
Returns the maximum Y value of the bounding envelope of a geometry |
Update the spatial index on a geometry column in a feature table |
The SQL functions on geometries in this SQLite Extension SHALL operate correctly on extended geometry types specified by User Defined Geometry Types Extension of GeoPackageBinary Geometry Encoding and/or GeoPackage Non-Linear Geometry Types when those extensions are also implemented.
The minimum bounding indexes created within the RTree Extension for GeoPackage should reflect the appropriate bounding area for the indexed feature. However, due to varying precision implementations, it is not practical to assert this practice through a requirement or test. Clients should exercise care when using these indexes during queries because the SQLite RTree module might round bounding boxes slightly outward (up to 0.000012%). Queries using spatial indexes should contain slightly expanded bounding boxes to guard against this. |
Abstract Test Suite
Extension Name
Test Case ID |
/extensions/rtree/extension_name |
Test Purpose |
Verify that spatial index extensions are registered using the "gpkg_rtree_index" name in the gpkg_extensions table. |
Test Method |
|
Reference |
Annex F.3 Req 75 |
Test Type |
Capability |
Extensions Row
Test Case ID |
/extensions/rtree/extension_row |
Test Purpose |
Verify that the "gpkg_rtree_index" extension name is used to register spatial index extensions. |
Test Method |
|
Reference |
Annex F.3 Req 76 |
Test Type |
Basic |
Implementation
Test Case ID |
/reg_ext/features/spatial_indexes/implementation |
Test Purpose |
Verify the correct implementation of spatial indexes on feature table geometry columns. |
Test Method |
|
Reference |
Annex F.3 Req 77 |
Test Type |
Capability |
Test Case ID |
/reg_ext/features/spatial_indexes/implementation/sql_functions |
Test Purpose |
Verify the correct implementation of sql functions used in spatial indexes on feature table geometry columns. |
Test Method |
|
Reference |
Annex F.3 Req 78 |
Test Type |
Capability |
F.4. Geometry Type Triggers
On August 15, 2016 the GeoPackage SWG voted to remote this extension from the standard due to interoperability concerns. For more information see the release notes. The original extension may be found in http://www.geopackage.org/spec110/#extension_geometry_type_triggers. |
F.5. Geometry SRS ID Triggers
On August 15, 2016 the GeoPackage SWG voted to remote this extension from the standard due to interoperability concerns. For more information see the release notes. The original extension may be found in http://www.geopackage.org/spec110/#extension_geometry_srsid_triggers. |
F.6. Zoom Other Intervals
Introduction
This extension of clause Zoom Levels allows zoom level intervals other than a factor of two.
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 precede 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 sizes 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_factor2_example_appendix].
This extension enables use of "zoom other intervals" conventions with 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 WMTS [I16] Annex E for additional examples of both conventions.
Extension Author
GeoPackage SWG, author_name gpkg
Extension Name or Template
gpkg_zoom_other
Extension Type
Extension of Existing Requirement in clause 2.2.3.
Applicability
This extension applies to any table listed in the gpkg_contents
table with a data_type of tiles
.
Scope
Read-write
Requirements
GeoPackage
The "gpkg_zoom_other" extension name SHALL be used as a gpkg_extensions table extension name column value to specify implementation of other zoom intervals on a tile pyramid user data table as specified in Zoom Other Intervals.
A GeoPackage that implements other zoom intervals SHALL have a gpkg_extensions table that contains a row for each tile pyramid user data table with other zoom intervals with extension_name "gpkg_zoom_other", the table_name of the table with other zoom intervals, and the "tile_data" column_name.
Tile pyramid user data tables MAY have pixel sizes that vary by irregular intervals or by regular intervals other than a factor of two (the default) between adjacent zoom levels. Extends Requirement 35.
The pixel_x_size
and / or pixel_y_size
column values in the gpkg_tile_matrix
table vary by irregular intervals or by regular intervals other than a factor of two (the default) between adjacent zoom levels for a particular tile matrix set pyramid table.
GeoPackage SQLite Configuration
None
GeoPackage SQLite Extension
None
Abstract Test Suite
Extensions Name
Test Case ID |
/reg_ext/tiles/zoom_levels/data/zoom_other_ext_name |
Test Purpose |
Verify that the "gpkg_zoom_other" extension name is used to register tiles tables with other than factors of two zoom intervals. |
Test Method |
|
Reference |
Annex F.6 Req 87 |
Test Type |
Basic |
Extensions Row
Test Case ID |
/reg_ext/tiles/zoom_levels/data/zoom_other_ext_row |
Test Purpose |
Verify that tiles tables with other than factors of two zoom intervals are registered using the "gpkg_zoom_other" extension name. |
Test Method |
/reg_ext/tiles/zoom_levels/data/zoom_other_ext_name |
Reference |
Annex F.6 Req 88 |
Test Type: |
Capability |
Zoom Interval
Test Case ID |
/reg_ext/tiles/zoom_levels/data/zoom_intervals |
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 only for tile matrix sets that this extension does not apply to. |
Test Method |
|
Reference |
Annex F.6 Req 89 |
Test Type |
Capability |
F.7. Tiles Encoding WebP
Introduction
This extension of clauses Tile Encoding PNG and Tile Encoding JPEG allows encoding of tile images in WebP format.
PNG and JPEG are the default MIME types for encoding images in tile pyramid user data tables.
This extension allows the use of image/x-webp
as an additional encoding type.
Extension Author
GeoPackage SWG, author_name gpkg
.
Extension Name or Template
gpkg_webp
Extension Type
Extension of Existing Requirement in clauses Tile Encoding PNG and Tile Encoding JPEG.
Applicability
This extension applies to any table listed in the gpkg_contents
table with a data_type of tiles
.
Scope
Read-write
Requirements
GeoPackage
GeoPackages with one or more rows in the gpkg_extensions
table with an extension_name
of "gpkg_webp" SHALL comply with this extension.
A GeoPackage that contains tile pyramid user data tables with tile_data
columns that contain images in WebP format SHALL contain a gpkg_extensions
table that contains row records with table_name
values for each such table, column_name
values of "tile_data", extension_name
column values of "gpkg_webp", and scope
column values of "read-write".
(extends Requirement 36 and Requirement 37) A GeoPackage that contains a tile pyramid user data table that contains tile data MAY store tile_data in the WebP format[I22]. Files complying with the WebP format SHALL have the MIME type image/x-webp
.
Requirements 36 and 37 allow a tile pyramid user data table to contain PNG or JPG tiles. This requirement allows for WebP tiles as well. |
GeoPackage SQLite Configuration
None
GeoPackage SQLite Extension
None
Abstract Test Suite
Extensions Name
Test Case ID |
/extensions/tile_encoding_webp/data/webp_ext_name |
Test Purpose: |
Verify that the "gpkg_webp" extensions name is used to register WEBP tile encoding implementations. |
Test Method: |
|
Reference |
Annex F.7 Req 90 |
Test Type |
Basic |
Extensions Row
Test Case ID |
/extensions/tile_encoding_webp/data/webp_ext_row |
Test Purpose: |
Verify that this extension is registered using proper rows in the |
Test Method: |
|
Reference: |
Annex F.7 Req 91 |
Test Type |
Capability |
Extensions Mime Type
Test Case ID |
/extensions/tiles_encoding_webp/data/mime_type_webp |
Test Purpose |
Verify that a tile matrix user data table that conforms to this extension contains a valid image type, including images of MIME type image/x-webp. |
Test Method |
|
Reference |
Annex F.7 Req 92 |
Test Type |
Capability |
F.8. Metadata
Introduction
Two tables in a GeoPackage provide a means of storing metadata in MIME [I21] encodings that are defined in accordance with any authoritative metadata specifications, and relating it to the features, rasters, and tiles data in a GeoPackage. These tables are intended to provide the support necessary to implement the hierarchical metadata models as defined in ISO 19115 [I28] and illustrated in Hierarchical Metadata Example One - ISO19115. and Raster or Tile Metadata Example. As GeoPackage data is captured and updated, the most local and specific detailed metadata changes associated with the new or modified data MAY be captured separately, and referenced to existing global and general metadata.
The gpkg_metadata
table that contains metadata is described in clause Metadata Table, and the gpkg_metadata_reference
table that relates gpkg_metadata
to GeoPackage data is described in clause Metadata Reference Table.
There is no GeoPackage requirement that such metadata be provided or that defined metadata be structured in a hierarchical fashion [K27]. This extension simply provides a mechanism for storing this information. If this extension is used, such metadata [K28] and data that relates it to GeoPackage contents should not be stored in other tables.
Extension Author
GeoPackage SWG, author_name gpkg
Extension Name or Template
gpkg_metadata
Extension Type
New Requirement
Applicability
This extension applies to any content in the GeoPackage.
Scope
Read-write
Requirements
Table Definitions
Metadata Table
A GeoPackage A GeoPackage MAY contain a table named gpkg_metadata
. If present it SHALL be defined per clauses Metadata Table, Table 12, and gpkg_metadata Table Definition SQL.
The first component of GeoPackage metadata is the gpkg_metadata
table that MAY contain metadata in MIME [I21] encodings structured in accordance with any authoritative metadata specification, such as ISO 19115 [I28], ISO 19115-2 [B6], ISO 19139 [B7], Dublin Core [B8], CSDGM [B10], DDMS [B12], NMF/NMIS [B13], etc.
The GeoPackage interpretation of what constitutes "metadata" is a broad one that includes UML models [B14] encoded in XMI [B15], GML Application Schemas [I30], ISO 19110 feature catalogues [B18], OWL [B20] and SKOS [B21] taxonomies, etc.
Column Name | Column Type | Column Description | Null | Default | Key |
---|---|---|---|---|---|
|
INTEGER |
Autoincrement[K6a] primary key |
no |
PK |
|
|
TEXT |
Case sensitive name of the data scope to which this metadata applies; see Table 15 below |
no |
'dataset' |
|
|
TEXT |
URI [I23] reference to the metadata structure definition authority [K29] |
no |
any |
|
|
TEXT |
MIME [I21] encoding of metadata |
no |
'text/xml' [I24] |
|
|
TEXT |
metadata |
no |
'' |
The md_standard_uri data value provides an identifier for the metadata structure (schema) specified by its definition authority. The structure (schema) information could be in whatever encoding is used by the definition authority, e.g. UML [B14], or IDEF1x [B16], or XML/Schema [I25][I26][I27], or RDF/S [B19].
Metadata Reference Table
A GeoPackage that contains a gpkg_metadata
table SHALL contain a gpkg_metadata_reference
table per clauses Metadata Reference Table, Table 13, and gpkg_metadata_reference Table Definition SQL.
The second component of GeoPackage metadata is the gpkg_metadata_reference
table that links metadata in the gpkg_metadata
table to data in the feature, and tiles tables defined in clauses 2.1.6 and 2.2.7.
The gpkg_metadata_reference
table is not required to contain any rows.
Column Name | Col Type | Column Description | Null | Default | Key |
---|---|---|---|---|---|
|
TEXT |
Lowercase metadata reference scope; one of 'geopackage', 'table', 'column', 'row', 'row/col' |
no |
||
|
TEXT |
Name of the table to which this metadata reference applies, or NULL for reference_scope of 'geopackage' |
yes |
||
|
TEXT |
For |
yes |
||
|
INTEGER |
For |
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 |
strftime(\'%Y-%m-%dT%H:%M:%fZ', \'now') |
|
|
INTEGER |
|
no |
FK |
|
|
INTEGER |
|
yes |
FK |
Every row in gpkg_metadata_reference
that has a NULL value as md_parent_id
forms the root of a metadata hierarchy.[K31]
Table Data Values
gpkg_extensions
GeoPackages with rows in the gpkg_extensions
table with an extension_name
of "gpkg_metadata" SHALL comply with this extension.
GeoPackages complying with this extension SHALL have rows in the gpkg_extensions
table as described in Table 14 (below).
Requirement 140 was updated as part of GeoPackage 1.2.1.
In 1.1.0 and 1.2.0, the details of required |
table_name | column_name | extension_name | definition | scope |
---|---|---|---|---|
|
null |
|
see note below |
|
|
null |
|
see note below |
|
For the |
gpkg_metadata
The md_scope
column in the gpkg_metadata
table is the name of the applicable scope for the contents of the metadata column for a given row.
The list of valid scope names and their definitions is provided in Table 15 below.
The initial contents of this table were obtained from the ISO 19115 [I28], Annex B B.5.25 MD_ScopeCode code list, which was extended [K32] for use in the GeoPackage specification by addition of entries with "NA" as the scope code column in Table 12.
Name (md_scope) | Scope Code | Definition |
---|---|---|
undefined |
NA |
Metadata information scope is undefined |
fieldSession |
012 |
Information applies to the field session |
collectionSession |
004 |
Information applies to the collection session |
series |
006 |
Information applies to the (dataset) series [K33] |
dataset |
005 |
Information applies to the (geographic feature) dataset |
featureType |
010 |
Information applies to a feature type (class) |
feature |
009 |
Information applies to a feature (instance) |
attributeType |
002 |
Information applies to the attribute class |
attribute |
001 |
Information applies to the characteristic of a feature (instance) |
tile |
016 |
Information applies to a tile, a spatial subset of geographic data |
model |
015 |
Information applies to a copy or imitation of an existing or hypothetical object |
catalog |
NA |
Metadata applies to a feature catalog [K34] |
schema |
NA |
Metadata applies to an application schema [K35] |
taxonomy |
NA |
Metadata applies to a taxonomy or knowledge system [K36] |
software |
013 |
Information applies to a computer program or routine |
service |
014 |
Information applies to a capability which a service provider entity makes available to a service user entity through a set of interfaces that define a behavior, such as a use case |
collectionHardware |
003 |
Information applies to the collection hardware class |
nonGeographicDataset |
007 |
Information applies to non-geographic data |
dimensionGroup |
008 |
Information applies to a dimension group |
style |
NA |
Information applies to a specific style |
Each md_scope
column value in a gpkg_metadata
table SHALL be one of the name column values from Table 15.
Each |
gpkg_metadata_reference
Every gpkg_metadata_reference
table reference scope column value SHALL be one of 'geopackage', 'table', 'column', 'row', 'row/col' in lowercase.
Every gpkg_metadata_reference
table row with a reference_scope
column value of 'geopackage' SHALL have a table_name
column value that is NULL.
Every other gpkg_metadata_reference
table row SHALL have a table_name
column value that references a value in the gpkg_contents
table_name
column.
Every gpkg_metadata_reference
table row with a reference_scope
column value of 'geopackage','table' or 'row' SHALL have a column_name
column value that is NULL.
Every other gpkg_metadata_reference
table row SHALL have a column_name
column value that contains the name of a column in the SQLite table or view identified by the table_name
column value.
Every gpkg_metadata_reference
table row with a reference_scope
column value of 'geopackage', 'table' or 'column' SHALL have a row_id_value
column value that is NULL.
Every other gpkg_metadata_reference
table row SHALL have a row_id_value
column value that contains the ROWID of a row in the SQLite table or view identified by the table_name
column value.
Every gpkg_metadata_reference
table row md_file_id
column value SHALL be an id column value from the gpkg_metadata
table.
Every gpkg_metadata_reference
table row md_parent_id
column value that is NOT NULL SHALL be an id column value from the gpkg_metadata
table that is not equal to the md_file_id
column value for that row.
Abstract Test Suite
Table Definition
Metadata Table
Test Case ID |
/extensions/metadata/metadata/table_def |
Test Purpose |
Verify that the gpkg_metadata table exists and has the correct definition. |
Test Method |
|
Reference |
Annex F.8 Req 93 |
Test Type |
Basic |
Metadata Reference Table
Test Case ID |
/extensions/metadata/metadata_reference/table_def |
Test Purpose |
Verify that the gpkg_metadata_reference table exists and has the correct definition. |
Test Method |
|
Reference |
Annex F.8 Req 95 |
Test Type |
Basic |
Table Data Values
gpkg_extensions
Test Case ID |
/extensions/metadata/extensions/data_values |
Test Purpose |
Verify that the gpkg_extensions table has the required rows. |
Test Method |
|
Reference |
Annex F.8 Req 140 |
Test Type: |
Capabilities |
gpkg_metadata
Test Case ID |
/extensions/metadata/metadata/data_values_md_scope |
Test Purpose |
Verify that each of the md_scope column values in a gpkg_metadata table is one of the name column values from Table 15. |
Test Method |
|
Reference |
Annex F.8 Req 94 |
Test Type: |
Capabilities |
gpkg_metadata_reference
Test Case ID |
/extensions/metadata/metadata_reference/reference_scope |
Test Purpose |
Verify that gpkg_metadata_reference table reference_scope column values are valid. |
Test Method |
|
Reference |
Annex F.8 Req 96 |
Test Type |
Capability |
Test Case ID |
/extensions/metadata/metadata_reference/table_name |
Test Purpose |
Verify that gpkg_metadata_reference table_name column values are NULL for rows with reference_scope values of 'geopackage', and reference gpkg_contents table_name values for all other reference_scope values. |
Test Method |
|
Reference |
Annex F.8 Req 97 |
Test Type |
Capability |
Test Case ID |
/extensions/metadata/metadata_reference/column_name |
Test Purpose |
Verify that gpkg_metadata_reference column_name column values are NULL for rows with reference scope values of 'geopackage', 'table', or 'row', and contain the name of a column in table_name table for other reference scope values. |
Test Method |
|
Reference |
Annex F.8 Req 98 |
Test Type |
Capability |
Test Case ID |
/extensions/metadata/metadata_reference/row_id_value |
Test Purpose |
Verify that gpkg_metadata_reference row_id_value column values are NULL for rows with reference scope values of 'geopackage', 'table', or 'row', and contain the ROWID of a row in the table_name for other reference scope values. |
Test Method |
|
Reference |
Annex F.8 Req 99 |
Test Type |
Capability |
Test Case ID |
/extensions/metadata/metadata_reference/timestamp |
Test Purpose |
Verify that every gpkg_metadata_reference table row timestamp column value is in ISO 8601 UTC format. |
Test Method |
|
Reference |
Annex F.8 Req 100 |
Test Type |
Capability |
Test Case ID |
/extensions/metadata/metadata_reference/md_file_id |
Test Purpose |
Verify that every gpkg_metadata_reference table row md_file_id column value references a gpkg_metadata id column value. |
Test Method |
|
Reference |
Annex F.8 Req 101 |
Test Type |
Capability |
Test Case ID |
/extensions/metadata/metadata_reference/md_parent_id |
Test Purpose |
Verify that every gpkg_metadata_reference table row md_parent_id column value that is not null is an id column value from the gpkg_metadata_table that is not equal to the md_file_id column value for that row. |
Test Method |
|
Reference |
Annex F.8 Req 102 |
Test Type |
Capability |
Table Definition SQL
gpkg_metadata
GeoPackage versions 1.2.1 and prior had an optional validation triggers |
CREATE TABLE gpkg_metadata (
id INTEGER PRIMARY KEY AUTOINCREMENT,
md_scope TEXT NOT NULL DEFAULT 'dataset',
md_standard_uri TEXT NOT NULL,
mime_type TEXT NOT NULL DEFAULT 'text/xml',
metadata TEXT NOT NULL DEFAULT ''
);
gpkg_metadata_reference
CREATE TABLE gpkg_metadata_reference (
reference_scope TEXT NOT NULL,
table_name TEXT,
column_name TEXT,
row_id_value INTEGER,
timestamp DATETIME NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
md_file_id INTEGER NOT NULL,
md_parent_id INTEGER,
CONSTRAINT crmr_mfi_fk FOREIGN KEY (md_file_id) REFERENCES gpkg_metadata(id),
CONSTRAINT crmr_mpi_fk FOREIGN KEY (md_parent_id) REFERENCES gpkg_metadata(id)
);
INSERT INTO gpkg_metadata_reference VALUES (
'table',
'sample_rasters',
NULL,
NULL,
'2012-08-17T14:49:32.932Z',
98,
99
)
Examples (Informative)
Hierarchical Metadata Example One - ISO19115.
Suppose we have this metadata:
id | md_scope | md_standard_uri | metadata |
---|---|---|---|
0 |
undefined |
TEXT |
|
3 |
series |
TEXT |
|
4 |
dataset |
TEXT |
|
5 |
featureType |
TEXT |
|
6 |
feature |
TEXT |
|
7 |
attributeType |
TEXT |
|
8 |
attribute |
TEXT |
and this reference table definition:
1) Consider a geographic data provider generating vector mapping data for three Administrative areas(A, B and C). … The metadata could be carried exclusively at Dataset Series level.
Then we need a record for each layer table for the three admin areas, like this:
INSERT INTO gpkg_metadata_reference VALUES (
'table', /* reference type */
'roads', /* table name */
'undefined', /* column_name */
-1, /* row_id_value */
(datetime('now')),
3, /* md_file_id */
0 /* md_parent_id */
)
2) After some time alternate vector mapping of Administrative area A becomes available. The metadata would then be extended for Administrative area A, to describe the new quality date values. These values would supersede those given for the Dataset series, but only for Administrative area A. The metadata for B and C would remain unchanged. This new metadata would be recorded at Dataset level.
Then we need a record for each layer table in "A" like this:
INSERT INTO gpkg_metadata_reference VALUES (
'table', /* reference type */
'roads', /* table name */
'undefined', /* column_name */
-1, /* row_id_value */
(datetime('now')),
4, /* md_file_id */
3 /* md_parent_id */
)
3) Eventually further data becomes available for Administrative area A, with a complete re-survey of the road network. Again this implies new metadata for the affected feature types. This metadata would be carried at Feature type level for Administrative area A. All other metadata relating to other feature types remains unaffected. Only the metadata for roads in Administrative area A is modified. This road metadata is recorded at Feature type level.
Then we need a record for each layer table for the roads network, like this:
INSERT INTO gpkg_metadata_reference VALUES (
'table', /* reference type */
'roads', /* table name */
'undefined', /* column_name */
-1, /* row_id_value */
(datetime('now')),
5, /* md_file_id */
4 /* md_parent_id */
)
4) An anomaly in the road survey is identified, in that all Overhead clearances for the Administrative area A have been surveyed to the nearest metre. These are re-surveyed to the nearest decimetre. This re-survey implies new metadata for the affected attribute type 'Overhead Clearance'. All other metadata for Administrative area A remains unaffected. This 'Overhead Clearance' metadata is recorded at Attribute Type level.
Then we need a record for each layer table in the roads network with attribute type 'Overhead Clearance', like this;
INSERT INTO gpkg_metadata_reference VALUES (
'column', /* reference type */
'roads', /* table name */
'overhead_clearance', /* column_name */
-1, /* row_id_value */
(datetime('now')),
7, /* md_file_id */
4 /* md_parent_id */
)
5) A new bridge is constructed in Administrative area A. This new data is reflected in the geographic data for Administrative area A, and new metadata is required to record this new feature. All other metadata for Administrative area A remains unaffected. This new feature metadata is recorded at Feature instance level.
Then we need a record for the bridge layer table row for the new bridge, like this:
INSERT INTO gpkg_metadata_reference VALUES (
'row', /* reference type */
'bridge', /* table name */
'undefined', /* column_name */
987, /* row_id_value */
(datetime('now')),
6, /* md_file_id */
4 /* md_parent_id */
)
6) The overhead clearance attribute of the new bridge was wrongly recorded, and is modified. Again this new attribute requires new metadata to describe the modification. All other metadata for Administrative area A remains unaffected. This new attribute metadata is recorded at Attribute instance level.
Then we need a record for the clearance attribute value, like this:
INSERT INTO gpkg_metadata_reference VALUES (
'row/col', /* reference type */
'bridge', /* table name */
'overhead_clearance', /* column_name */
987, /* row_id_value */
(datetime('now')),
8, /* md_file_id */
4 /* md_parent_id */
)
Hierarchical Metadata Example Two - Field Data Collection
This use case demonstrates a mechanism to indicate which data in a GeoPackage that was originally loaded with data from one or more services has been collected or updated since the initial load, and therefore MAY need to be uploaded to update the original services (e.g., WFS, WCS, WMTS).
Suppose a user with a mobile handheld device goes out in the field and collects observations of a new "Point of Interest" (POI) feature type, and associated metadata about the field session, the new feature type, some POI instances and some of their attributes (e.g., spatial accuracy, attribute accuracy) that results in the following additional metadata:
id | md_scope | md_standard_uri | metadata |
---|---|---|---|
1 |
fieldSession |
TEXT |
|
10 |
featureType |
TEXT |
|
11 |
feature |
TEXT |
|
12 |
attribute |
TEXT |
|
13 |
attribute |
TEXT |
|
14 |
feature |
TEXT |
|
15 |
attribute |
TEXT |
|
16 |
attribute |
TEXT |
|
17 |
feature |
TEXT |
|
18 |
attribute |
TEXT |
|
19 |
attribute |
TEXT |
(This example assumes that the field session data is still considered "raw" and won’t be considered a data set or part of a data series until it has been verified and cleaned, but if that is wrong then additional series and data set metadata could be added.)
Then we need a gpkg_metadata_reference record for the field session for the new POI table, whose md_parent_id is undefined:
INSERT INTO gpkg_metadata_reference VALUES (
'table', /* reference type */
'poi', /* table name */
'undefined', /* column_name */
-1, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
1, /* md_file_id */
0 /* md_parent_id */
)
Then we need a gpkg_metadata_reference record for the feature type for the new POI table, whose md_parent_id is that of the field session:
INSERT INTO gpkg_metadata_reference VALUES (
'table', /* reference type */
'poi', /* table name */
'undefined', /* column_name */
-1, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
10, /* md_file_id */
1 /* md_parent_id */
)
Then we need gpkg_metadata_reference records for the poi feature instance rows, whose md_parent_id is that of the field session:
INSERT INTO gpkg_metadata_reference VALUES (
'row', /* reference type */
'poi', /* table name */
'undefined', /* column_name */
1, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
11, /* md_file_id */
1 /* md_parent_id */
)
INSERT INTO gpkg_metadata_reference VALUES (
'row', /* reference type */
'poi', /* table name */
'undefined', /* column_name */
2, /* row_id_value */
14, /* md_file_id */
1 /* md_parent_id */
)
INSERT INTO gpkg_metadata_reference VALUES (
'row', /* reference type */
'poi', /* table name */
'undefined', /* column_name */
3, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
17, /* md_file_id */
1 /* md_parent_id */
)
And finally we need gpkg_metadata_reference records for the poi attribute instance metadata , whose md_parent_id is that of the field session:
INSERT INTO gpkg_metadata_reference VALUES (
'row/col', /* reference type */
'poi', /* table name */
'point', /* column_name */
1, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
12, /* md_file_id */
1 /* md_parent_id */
)
INSERT INTO gpkg_metadata_reference VALUES (
'row/col', /* reference type */
'poi', /* table name */
'point', /* column_name */
2, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
15, /* md_file_id */
1 /* md_parent_id */
)
INSERT INTO gpkg_metadata_reference VALUES (
'row/col', /* reference type */
'poi', /* table name */
'point', /* column_name */
3, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
18, /* md_file_id */
1 /* md_parent_id */
)
INSERT INTO gpkg_metadata_reference VALUES (
'row/col', /* reference type */
'poi', /* table name */
'category', /* column_name */
1, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
13, /* md_file_id */
1 /* md_parent_id */
)
INSERT INTO gpkg_metadata_reference VALUES (
'row/col', /* reference type */
'poi', /* table name */
'category', /* column_name */
2, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
16, /* md_file_id */
1 /* md_parent_id */
)
INSERT INTO gpkg_metadata_reference VALUES (
'row/col', /* reference type */
'poi', /* table name */
'category', /* column_name */
3, /* row_id_value */
(strftime('%Y-%m-%dT%H:%M:%fZ','now')),
19, /* md_file_id */
1 /* md_parent_id */
)
As long as all metadata collected in the field session either directly (as above) or indirectly (suppose there were a data set level metadata_reference record intermediary) refers to the field session metadata via md_parent_id values, then this chain of metadata references identifies the newly collected information, as Joan requested, in addition to the metadata.
So here is the data after both examples:
id | md_scope | md_standard_uri | metadata |
---|---|---|---|
0 |
undefined |
TEXT |
|
1 |
fieldSession |
TEXT |
|
2 |
collectionSession |
TEXT |
|
3 |
series |
TEXT |
|
4 |
dataset |
TEXT |
|
5 |
featureType |
TEXT |
|
6 |
feature |
TEXT |
|
7 |
attributeType |
TEXT |
|
8 |
attribute |
TEXT |
|
10 |
featureType |
TEXT |
|
11 |
feature |
TEXT |
|
12 |
attribute |
TEXT |
|
13 |
attribute |
TEXT |
|
14 |
feature |
TEXT |
|
15 |
attribute |
TEXT |
|
16 |
attribute |
TEXT |
|
17 |
feature |
TEXT |
|
18 |
attribute |
TEXT |
|
19 |
attribute |
TEXT |
reference_type | table_name | column_name | row_id_value | timestamp | md_file_id | md_parent_id |
---|---|---|---|---|---|---|
table |
roads |
undefined |
0 |
ts |
3 |
0 |
table |
roads |
undefined |
0 |
ts |
4 |
3 |
table |
roads |
undefined |
0 |
ts |
5 |
4 |
column |
roads |
overhead_clearance |
0 |
ts |
7 |
4 |
row |
bridge |
undefined |
987 |
ts |
6 |
4 |
row/col |
bridge |
overhead_clearance |
987 |
ts |
8 |
4 |
table |
poi |
undefined |
0 |
ts |
1 |
0 |
row |
poi |
undefined |
0 |
ts |
10 |
1 |
row |
poi |
undefined |
1 |
ts |
11 |
1 |
row |
poi |
undefined |
2 |
ts |
14 |
1 |
row/col |
poi |
undefined |
3 |
ts |
17 |
1 |
row/col |
poi |
point |
1 |
ts |
12 |
1 |
row/col |
poi |
point |
2 |
ts |
15 |
1 |
row/col |
poi |
point |
3 |
ts |
18 |
1 |
row/col |
poi |
category |
1 |
ts |
13 |
1 |
row/col |
poi |
category |
2 |
ts |
16 |
1 |
row/col |
poi |
category |
3 |
ts |
19 |
1 |
Raster or Tile Metadata Example
A number of raster image processing problems MAY require the support of more metadata that is contained in the image itself.
Applications MAY use the gpkg_metadata
and gpkg_metadata_reference
tables defined in clause [_metadata] to store raster image metadata defined according to standard authoritative or application or vendor specific metadata models.
An example of the data items in such a model is shown in the following table.
-
Rational Polynomial Coefficient
-
Photometric Interpretation
-
No Data Value
-
Compression Quality Factor
-
Georectification
-
NIIRS
-
Min X
-
Min Y
-
Max X
-
Max Y
F.9. Schema
Introduction
The schema extension provides a means to describe the columns of tables in a GeoPackage with more detail than can be captured by the SQL table definition directly. The information provided by this extension can be used by applications to, for instance, present data contained in a GeoPackage in a more user-friendly fashion or implement data validation logic.
Extension Author
GeoPackage SWG, author_name gpkg
Extension Name
gpkg_schema
Extension Type
New requirement dependent on clauses Features, Attributes, and Extension Mechanism.
Applicability
This extension may apply to any Vector Feature User Data Tables, Attributes User Data Tables, or extension tables (see Attributes User Data Tables).
Scope
Read-write
Requirements
Table Definitions
Data Columns
A GeoPackage MAY contain a table named gpkg_data_columns
.
If present it SHALL be defined per Table 16 and gpkg_data_columns Table Definition SQL.
Column Name | Column Type | Column Description | Null | Key |
---|---|---|---|---|
|
TEXT |
Name of a table specified in |
no |
PK, UK |
|
TEXT |
Name of the table column |
no |
PK |
|
TEXT |
A human-readable identifier (e.g. short name) for the column_name content |
yes |
UK |
|
TEXT |
A human-readable formal title for the column_name content |
yes |
|
|
TEXT |
A human-readable description for the column_name content |
yes |
|
|
TEXT |
MIME [I21] type of column_name if BLOB type, or NULL for other types |
yes |
|
|
TEXT |
Column value constraint name (lowercase) specified by reference to |
yes |
GeoPackage applications MAY [K38] use the gpkg_data_columns
table to store minimal application schema identifying, descriptive and MIME [I21] type [K39] information about columns in user vector feature and tile matrix data tables that supplements the data available from the SQLite sqlite_master
table and pragma table_info(table_name)
SQL function.
The gpkg_data_columns
data CAN be used to provide more specific column data types and value ranges and application specific structural and semantic information to enable more informative user menu displays and more effective user decisions on the suitability of GeoPackage contents for specific purposes.
In versions 1.2.1 and earlier, the |
Data Column Constraints
A GeoPackage MAY contain a table named gpkg_data_column_constraints
.
If present it SHALL be defined per Table 17 and gpkg_data_columns Table Definition SQL.
The gpkg_data_column_constraints
table contains data to specify restrictions on basic data type column values.
The constraint_name
column is referenced by the constraint_name
column in the gpkg_data_columns
table defined in Table 16.
Column Name | Column Type | Column Description | Null | Key |
---|---|---|---|---|
|
TEXT |
Name of constraint (lowercase) |
no |
Jointly Unique |
|
TEXT |
Type name of constraint: 'range' | 'enum' | 'glob' |
no |
Jointly Unique |
|
TEXT |
Specified case sensitive value for 'enum' or 'glob' or NULL for 'range' constraint_type |
yes |
Jointly Unique |
|
NUMERIC |
Minimum value for 'range' or NULL for 'enum' or 'glob' constraint_type |
yes |
|
|
BOOLEAN |
0 (false) if min value is exclusive, or 1 (true) if min value is inclusive |
yes |
|
|
NUMERIC |
Maximum value for 'range' or NULL for 'enum' or 'glob' constraint_type |
yes |
|
|
BOOLEAN |
0 (false) if max value is exclusive, or 1 (true) if max value is inclusive |
yes |
|
|
TEXT |
For ranges and globs, describes the constraint; for enums, describes the enum value. |
yes |
The min
and max
columns are defined as NUMERIC to be able to contain range values for any numeric data column defined with a data type from Table 1. These are the only exceptions to the data type rule stated in Req 5.
In GeoPackage 1.0, this table had column names |
Table Data Values
gpkg_extensions
GeoPackages with rows in the gpkg_extensions
table with an extension_name
of "gpkg_schema" SHALL comply with this extension.
GeoPackages complying with this extension SHALL have rows in the gpkg_extensions
table as described in Table 18 (below).
Requirement 141 was updated as part of GeoPackage 1.2.1.
In 1.1.0 and 1.2.0, the details of required |
table_name | column_name | extension_name | definition | scope |
---|---|---|---|---|
|
null |
|
see note below |
|
|
null |
|
see note below |
|
For the |
Data Columns
Values of the gpkg_data_columns
table table_name
column value SHALL reference values in the table_name
column from either gpkg_contents
or gpkg_extensions
.
The column_name
column value in a gpkg_data_columns
table row SHALL contain the name of a column in the SQLite table or view identified by the table_name
column value.
The constraint_name
column value in a gpkg_data_columns
table MAY be NULL.
If it is not NULL, it SHALL contain a constraint_name
column value (which SHALL be lowercase) from the gpkg_data_column_constraints
table.
Data Column Constraints
The lowercase gpkg_data_column_constraints
constraint_type
column value specifies the type of constraint: "range", "enum", or "glob" (GLOB is a text pattern match - see [I33]).
The case sensitive value
column contains an enumerated legal value for constraint_type
"enum", a pattern match string for constraint_type
"glob", or NULL for constraint_type
"range". The set of value
column values in rows of constraint_type
"enum" with the same constraint_name
contains all possible enumerated values for the constraint name. The min
and max
column values specify the minimum and maximum valid values for constraint_type
"range", or are NULL for constraint_type
"enum" or "glob". The min_is_inclusive
and max_is_inclusive
column values contain 1 if the min
and max
values (respectively) are inclusive, 0 if they are exclusive, or are NULL for constraint_type
"enum" or "glob".
These restrictions MAY be enforced by SQL triggers or by code in applications that update GeoPackage data values.
constraint_name | constraint_type | value | min | min_is_inclusive | max | max_is_inclusive |
---|---|---|---|---|---|---|
sampleRange |
range |
NULL |
1 |
true |
10 |
true |
sampleEnum |
enum |
1 |
NULL |
NULL |
NULL |
NULL |
sampleEnum |
enum |
3 |
NULL |
NULL |
NULL |
NULL |
sampleEnum |
enum |
5 |
NULL |
NULL |
NULL |
NULL |
sampleEnum |
enum |
7 |
NULL |
NULL |
NULL |
NULL |
sampleEnum |
enum |
9 |
NULL |
NULL |
NULL |
NULL |
sampleGlob |
glob |
[1-2][0-9][0-9][0-9] |
NULL |
NULL |
NULL |
NULL |
The gpkg_data_column_constraints
table MAY be empty.
If it contains data, the lowercase constraint_type
column values SHALL be one of "range", "enum", or "glob".
The gpkg_data_column_constraint
constraint_name
values for rows with constraint_type
values of "range" and "glob" SHALL be unique.
The gpkg_data_column_constraints
table MAY be empty.
If it contains rows with constraint_type
column values of "range", the value
column values for those rows SHALL be NULL.
If the gpkg_data_column_constraints
table contains rows with constraint_type
column values of "range", the min
column values for those rows SHALL be NOT NULL and less than the max
column value which shall be NOT NULL.
If the gpkg_data_column_constraints
table contains rows with constraint_type
column values of "range", the min_is_inclusive
and max_is_inclusive
column values for those rows SHALL be 0 or 1.
If the gpkg_data_column_constraints
table contains rows with constraint_type
column values of "enum" or "glob", the min
, max
, min_is_inclusive
and max_is_inclusive
column values for those rows SHALL be NULL.
If the gpkg_data_column_constraints
table contains rows with constraint_type
column values of "enum" or "glob", the value
column SHALL NOT be NULL.
Abstract Test Suite
Table Definition
Data Columns
Test Case ID |
/extensions/schema/data_columns/table_def |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Annex F.9 Req 103 |
Test Type |
Basic |
Data Column Constraints
Test Case ID |
/extensions/schema/data_column_constraints/table_def |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Annex F.9 Req 107 |
Test Type |
Basic |
Data Values
gpkg_extensions
Test Case ID |
/extensions/schema/extensions/data_values |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Annex F.9 Req 141 |
Test Type: |
Capabilities |
Test Case ID |
/extensions/schema/data_columns/table_name |
Test Purpose |
Verify that for each |
Test Method |
|
Reference |
Annex F.9 Req 104 |
Test Type |
Capability |
Test Case ID |
/extensions/schema/data_columns/column_name |
Test Purpose |
Verify that for each |
Test Method |
|
Reference |
Annex F.9 Req 105 |
Test Type |
Capability |
Test Case ID |
/extensions/schema/data_columns/constraint_name |
Test Purpose |
Verify that for each |
Test Method |
|
Reference |
Annex F.9 Req 106 |
Test Type |
Capability |
Data Column Constraints
Test Case ID |
/extensions/schema/data_column_constraints/constraint_type |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Annex F.9 Req 108 |
Test Type |
Capability |
Test Case ID |
/extensions/schema/data_column_constraints/constraint_names_unique |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Annex F.9 Req 109 |
Test Type |
Capability |
Test Case ID |
/extensions/schema/data_column_constraints/value_for_range |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Annex F.9 Req 110 |
Test Type |
Capability |
Test Case ID |
/extensions/schema/data_column_constraints/min_max_for_range |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Annex F.9 Req 111 |
Test Type |
Capability |
Test Case ID |
/extensions/schema/data_column_constraints/inclusive_for_range |
Test Purpose |
Verify that the |
Test Method |
|
Reference |
Annex F.9 Req 112 |
Test Type |
Capability |
Test Case ID: |
/extensions/schema/data_column_constraints/min_max_inclusive_for_enum_glob |
Test Purpose: |
Verify that the |
Test Method: |
|
Reference |
Annex F.9 Req 113 |
Test Type |
Capability |
Test Case ID: |
/extensions/schema/data_column_constraints/value_for_enum_glob |
Test Purpose: |
Verify that the |
Test Method: |
|
Reference |
Annex F.9 Req 114 |
Test Type |
Capability |
Table Definition SQL
gpkg_data_columns
CREATE TABLE gpkg_data_columns (
table_name TEXT NOT NULL,
column_name TEXT NOT NULL,
name TEXT,
title TEXT,
description TEXT,
mime_type TEXT,
constraint_name TEXT,
CONSTRAINT pk_gdc PRIMARY KEY (table_name, column_name),
CONSTRAINT gdc_tn UNIQUE (table_name, name)
);
gpkg_data_column_constraints
CREATE TABLE gpkg_data_column_constraints (
constraint_name TEXT NOT NULL,
constraint_type TEXT NOT NULL, // 'range' | 'enum' | 'glob'
value TEXT,
min NUMERIC,
min_is_inclusive BOOLEAN, // 0 = false, 1 = true
max NUMERIC,
max_is_inclusive BOOLEAN, // 0 = false, 1 = true
description TEXT,
CONSTRAINT gdcc_ntv UNIQUE (constraint_name, constraint_type, value)
)
F.10. WKT for Coordinate Reference Systems
Introduction
The OGC GeoPackage standard was adopted prior to the adoption of "12-063r5 OGC Well known text representation of Coordinate Reference Systems" [I34], in 13 August, 2014. As a result, the OGC GeoPackage standard references an older document [I32] which has known ambiguities that are being encountered in the field. This extension establishes a new column to contain values that conform to the new standard. OGC later adopted "18-010r7 OGC Well known text representation of Coordinate Reference Systems" [I36], in 6 June, 2019 as a revision to 12-063r5.
Extension Author
GeoPackage SWG, author_name gpkg
.
Extension Name or Template
gpkg_crs_wkt
Extension Type
Extension of Existing Requirement in clause Table Definition.
Applicability
Applies to the gpkg_spatial_ref_sys
table.
Scope
Read-write
Requirements
Table Definition
gpkg_spatial_ref_sys
For GeoPackages conforming to this extension, the gpkg_spatial_ref_sys
table SHALL have an additional column called definition_12_063
as per Table 19 and gpkg_spatial_ref_sys Table Definition SQL (CRS WKT Extension).
Column Name | Column Type | Column Description | NOT NULL flag | Key |
---|---|---|---|---|
|
TEXT |
Human readable name of this SRS |
true |
|
|
INTEGER |
Unique identifier for each Spatial Reference System within a GeoPackage |
true |
PK |
|
TEXT |
Case-insensitive name of the defining organization e.g. EPSG or epsg |
true |
|
|
INTEGER |
Numeric ID of the Spatial Reference System assigned by the organization |
true |
|
|
TEXT |
Well-known Text [I32] Representation of the Spatial Reference System |
true |
|
|
TEXT |
Human readable description of this SRS |
false |
|
|
TEXT |
Well-known Text [I34] or [I36] Representation of the Spatial Reference System |
true |
Previous versions of this extension specified default values for |
Table Data Values
gpkg_extensions
GeoPackages with a row in the gpkg_extensions
table with an extension_name
of "gpkg_crs_wkt" SHALL comply with this extension.
GeoPackages complying with this extension SHALL have a row in the gpkg_extensions
table as described in Table 20 (below).
Requirement 145 has been updated as part of GeoPackage 1.2.1.
In 1.1.0 and 1.2.0, the |
table_name | column_name | extension_name | definition | scope |
---|---|---|---|---|
|
|
|
see note below |
|
For the |
gpkg_spatial_ref_sys
For backwards compatibility, only use common WKT values between 12-063 and 18-010. Additional WKT values in 18-010r7 can be used when required in the CRS definition. |
At least one definition column SHALL be defined with a valid definition unless the value of the srs_id
column is 0
or -1
. Both columns SHOULD be defined. If it is not possible to produce a valid [I32] definition then the value of the definition
column MAY be undefined
. If it is not possible to produce a valid [I34] or [I36] definition then the value of the definition_12_063
column MAY be undefined
.
If, for a particular row, both the |
Abstract Test Suite
Table Definition
Table Definition
Test Case ID |
/extension_crs_wkt/table_def |
Test Purpose |
Verify that the gpkg_spatial_ref_sys table exists and has the correct definition. Extends |
Test Method |
|
Reference |
Annex F.10 Req 115 |
Test Type |
Basic |
Table Data Values
Test Case ID |
/extensions/crs_wkt/extensions/data_values |
Test Purpose |
Verify that the gpkg_extensions table has the required row. |
Test Method |
|
Reference |
Annex F.10 Req 145 |
Test Type: |
Capabilities |
Test Case ID |
/extension_crs_wkt/data_values_default |
Test Purpose |
Verify that the gpkg_spatial_ref_sys table contains the required default contents. Extends |
Test Method |
|
Reference |
Annex F.10 Req 116 |
Test Type |
Capability |
Test Case ID |
/extension_crs_wkt/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. Extends |
Test Method |
|
Reference |
Annex F.10 Req 117 |
Test Type |
Capability |
Table Definition SQL
gpkg_spatial_ref_sys
CREATE TABLE gpkg_spatial_ref_sys (
srs_name TEXT NOT NULL,
srs_id INTEGER NOT NULL PRIMARY KEY,
organization TEXT NOT NULL,
organization_coordsys_id INTEGER NOT NULL,
definition TEXT NOT NULL,
description TEXT,
definition_12_063 TEXT NOT NULL
);
F.11. Tiled Gridded Coverage Data
This extension has been published separately as OGC 17-066r1.
F.12. Related Tables
This extension has been published separately as OGC 18-000.
Annex G: Geometry Types (Normative)
Code | Name |
---|---|
0 |
GEOMETRY |
1 |
POINT |
2 |
LINESTRING |
3 |
POLYGON |
4 |
MULTIPOINT |
5 |
MULTILINESTRING |
6 |
MULTIPOLYGON |
7 |
GEOMETRYCOLLECTION |
Code | Name |
---|---|
8 |
CIRCULARSTRING |
9 |
COMPOUNDCURVE |
10 |
CURVEPOLYGON |
11 |
MULTICURVE |
12 |
MULTISURFACE |
13 |
CURVE |
14 |
SURFACE |
GEOMETRY subtypes are POINT, CURVE, SURFACE and GEOMETRYCOLLECTION.
CURVE subtypes are LINESTRING, CIRCULARSTRING and COMPOUNDCURVE.
SURFACE subtype is CURVEPOLYGON.
CURVEPOLYGON subtype is POLYGON.
GEOMETRYCOLLECTION subtypes are MULTIPOINT, MULTICURVE and MULTISURFACE.
MULTICURVE subtype is MULTILINESTRING.
MULTISURFACE subtype is MULTIPOLYGON.
Annex H: Tiles Zoom Times Two Example (Informative)
table_name | zoom_level | matrix_width | matrix_height | tile_width | tile_height | pixel_x_size | pixel_y_size |
---|---|---|---|---|---|---|---|
MyTiles |
0 |
8 |
8 |
512 |
512 |
69237.2 |
68412.1 |
MyTiles |
1 |
16 |
16 |
512 |
512 |
34618.6 |
34206.0 |
MyTiles |
2 |
32 |
32 |
512 |
512 |
17309.3 |
17103.0 |
MyTiles |
3 |
64 |
64 |
512 |
512 |
8654.64 |
8654.64 |
MyTiles |
4 |
128 |
128 |
512 |
512 |
4327.32 |
4275.75 |
MyTiles |
5 |
256 |
256 |
512 |
512 |
2163.66 |
2137.87 |
MyTiles |
6 |
512 |
512 |
512 |
512 |
1081.83 |
1068.93 |
MyTiles |
7 |
1024 |
1024 |
512 |
512 |
540.915 |
543.469 |
MyTiles |
8 |
2048 |
2048 |
512 |
512 |
270.457 |
267.234 |
Annex I: Normative References (Normative)
The following normative documents contain provisions which, through reference in this text, constitute provisions of OGC 12-128. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. However, parties to agreements based on this part of OGC 12-128 are encouraged to investigate the possibility of applying the most recent editions of the normative documents indicated below. For undated references, the latest edition of the normative document referred to applies.
-
[I1] ISO/IEC 9075:1992 Information Technology - Database Language SQL (SQL92)
-
[I2] ISO/IEC 9075-1:2011 Information Technology - Database Language SQL - Part 1: Framework
-
[I3] ISO/IEC 9075-2:2011 Information Technology - Database Language SQL - Part 2: Foundation
-
[I4] ISO/IEC 9075-3:2008 Information Technology - Database Language SQL - Part 3: Call- Level Interface (SQL/CLI)
-
[I5] SQLite (all parts) http://www.sqlite.org/ (online) http://www.sqlite.org/sqlite-doc-3071300.zip (offline)
-
[I9] OGC 06-103r4 OpenGIS® Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture Version: 1.2.1 2011-05-28 http://portal.opengeospatial.org/files/?artifact_id=25355
-
[I10] OGC 06-104r4 OpenGIS® Implementation Standard for Geographic information - Simple feature access - Part 2: SQL option Version: 1.2.1 2010-08-04 http://portal.opengeospatial.org/files/?artifact_id=25354 (the older version 1.1 of this standard is known as ISO 19125-1:2004)
-
[I11] OGC 05-134 OpenGIS® Implementation Specification for Geographic information - Simple feature access - Part 2: SQL option Version 1.1.0 2005-11-22 http://portal.opengeospatial.org/files/?artifact_id=13228 (also known as the now withdrawn ISO 19125-2:2004)
-
[I12] ISO/IEC 13249-3:2011 Information technology — SQL Multimedia and Application Packages - Part 3: Spatial (SQL/MM)
-
[I15] MIL_STD_2401 DoD World Geodetic System 84 (WGS84), 11 January 1994
-
[I16] OGC 07-057r7 OpenGIS® Web Map Tile Service Implementation Standard Version 1.0.0 2010-04-06 (WMTS) http://portal.opengeospatial.org/files/?artifact_id=35326
-
[I17] ITU-T Recommendation T.81 (09/92) with Corrigendum (JPEG)
-
[I18] T.871 : Information technology - Digital compression and coding of continuous-tone still images: JPEG File Interchange Format (JFIF), September 11, 2012 http://www.itu.int/rec/T-REC-T.871-201105-I/en
-
[I19] IETF RFC 2046 Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types http://www.ietf.org/rfc/rfc2046.txt
-
[I20] Portable Network Graphics http://libpng.org/pub/png/
-
[I21] MIME Media Types http://www.iana.org/assignments/media-types/index.html
-
[I22] WebP https://developers.google.com/speed/webp/
-
[I23] IETF RFC 3986 Uniform Resource Identifier (URI): Generic Syntax http://www.ietf.org/rfc/rfc3986.txt
-
[I24] W3C Recommendation 26 November 2008 Extensible Markup Language (XML) 1.0 (Fifth Edition) http://www.w3.org/TR/xml/
-
[I25] W3C Recommendation 28 October 2004 XML Schema Part 0: Primer Second Edition http://www.w3.org/TR/xmlschema-0/
-
[I26] W3C Recommendation 28 October 2004 XML Schema Part 1: Structures Second Edition http://www.w3.org/TR/xmlschema-1/
-
[I27] W3C Recommendation 28 October 2004 XML Schema Part 2: Datatypes Second Edition http://www.w3.org/TR/xmlschema-2/
-
[I28] ISO: 19115-1:2014 Geographic information — Metadata — Part 1: Fundamentals (2014) https://www.iso.org/standard/53798.html
-
[I29] ISO 8601 Representation of dates and times http://www.iso.org/iso/catalogue_detail?csnumber=40874
-
[I30] OGC® 10-100r3 Geography Markup Language (GML) simple features profile (with technical note) http://portal.opengeospatial.org/files/?artifact_id=42729
-
[I31] SQLite R*Tree Module http://www.sqlite.org/rtree.html
-
[I32] OpenGIS® 01-009 Implementation Specification: Coordinate Transformation Services Revision 1.0 http://portal.opengeospatial.org/files/?artifact_id=999
-
[I33] SQLite GLOB operator https://www.sqlite.org/lang_expr.html#glob
-
[I34] Geographic information — Well-known text representation of coordinate reference systems http://docs.opengeospatial.org/is/12-063r5/12-063r5.html
-
[I35] TIFF ™ Revision 6.0 Final — June 3, 1992 ftp://download.osgeo.org/libtiff/doc/TIFF6.pdf, ©1986-1988, 1992 by Adobe® Systems Incorporated
-
[I36] Geographic information — Well-known text representation of coordinate reference systems https://docs.opengeospatial.org/is/18-010r7/18-010r7.html
Annex J: Bibliography (Informative)
-
[B1] http://developer.android.com/guide/topics/data/data-storage.html#db
-
[B2] https://developer.apple.com/technologies/ios/data-management.html
-
[B6] ISO 19115-2 Geographic information - - Metadata - Part 2: Metadata for imagery and gridded data
-
[B7] ISO 19139: Geographic information — Metadata — XML schema implementation
-
[B8] Dublin Core Metadata Initiative http://dublincore.org/ IETF RFC 5013
-
[B9] ISO 15836:2009 http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=52142
-
[B10] Content Standard for Digital Geospatial Metadata (CSDGM)
-
[B11] http://www.fgdc.gov/standards/projects/FGDC-standards-projects/metadata/base-metadata/index_html
-
[B12] Department of Defense Discovery Metadata Specification (DDMS) http://metadata.ces.mil/mdr/irs/DDMS/
-
[B14] Unified Modeling Language (UML) http://www.uml.org/
-
[B15] XML for Metadata Interchange (XMI) http://www.omg.org/spec/XMI/
-
[B16] IDEF1x Data Modeling Method http://www.idef.com/IDEF1x.htm
-
[B18] ISO 19110 Geographic information – Methodology for feature cataloguing
-
[B19] RDF Vocabulary Description Language 1.0: RDF Schema http://www.w3.org/TR/rdf-schema/
-
[B20] Web Ontology Language (OWL) http://www.w3.org/TR/2009/REC-owl2-xml-serialization-20091027/
-
[B21] Simple Knowledge Organization System (SKOS) http://www.w3.org/TR/skos-reference/
-
[B22] STANAG 7074 Digital Geographic Information Exchange Standard (DIGEST) - AGeoP-3A, edition 1, 19 October 1994 http://www.dgiwg.org/dgiwg/htm/documents/historical_documents.htm
-
[B23] ISO 19109 Geographic information - Rules for application schema
-
[B26] OGC® 16-094r3 GeoPackage Elevation Extension Interoperability Experiment Engineering Report, Draft Revision 3, 21 June 2016
-
[B27] Media Types https://www.iana.org/assignments/media-types/media-types.xhtml
Annex K: Endnotes
-
[K1] SQLite version 4 (reference B25), which will be an alternative to version 3, not a replacement thereof, was not available when this standard was written. See Future Work clause in Annex B.
-
[K2] SQLite is in the public domain (see http://www.sqlite.org/copyright.html)
-
[K3] With SQLite versions 3.7.17 and later this value MAY be set with the "PRAGMA application_id=1196444487;" SQL statement, where 1196444487 is the 32-bit integer value of 0x47504B47. With earlier versions of SQLite the application id can be set by writing the byte sequence 0x47, 0x50, 0x4B, 0x47 at offset 68 in the SQLite database file (see http://www.sqlite.org/fileformat2.html#database_header for details).
-
[K4] Older GeoPackages use a different versioning mechanism. Instead of using the user_version, they have an application ID of "GP10" (for GeoPackage 1.0 and 1.0.1) or "GP11" (for GeoPackage 1.1).
-
[K4a] For more information on maximum database size, see Section 14 of https://www.sqlite.org/limits.html.
-
[K5] The SQLite PRAGMA integrity_check SQL command does a full database scan that can take a long time to complete on a large GeoPackage file.
-
[K6] New applications should use the latest available SQLite version software [I8]
-
[K6a] The use of the AUTOINCREMENT keyword is optional but recommended. Implementers MAY omit the AUTOINCREMENT keyword for performance reasons, with the understanding that doing so has the potential to allow primary key identifiers to be reused.
-
[K6b] When a table has a primary key that is backed by a ROWID, the "null" flag is ignored.
-
[K7] The following statement selects an ISO 8601 timestamp value using the SQLite strftime function: SELECT (strftime('%Y-%m-%dT%H:%M:%fZ','now')).
-
[K8] GeometryCollection is a generic term for the ST_GeomCollection type defined in [I12], which uses it for the definition of Well Known Text (WKT) and Well Known Binary (WKB) encodings. The SQL type name GEOMETRYCOLLECTION defined in [I10] and used in Clause 1.1.2.1.1 and Annex G below refers to the SQL BLOB encoding of a GeometryCollection.
-
[K9] OGC WKB simple feature geometry types specified in [I9] are a subset of the ISO WKB geometry types specified in [I12]
-
[K10] WKB geometry types are are restricted to 0, 1 and 2-dimensional geometric objects that exist in 2, 3 or 4-dimensional coordinate space; they are not geographic or geodesic geometry types.
-
[K12] A GeoPackage is not required to contain any feature data tables. Feature data tables in a GeoPackage MAY be empty.
-
[K13] GeoPackage applications MAY use SQL triggers or tests in application code to meet this requirement
-
[K14] Images of multiple MIME types MAY be stored in given table. For example, in a tiles table, image/png format tiles COULD be used for transparency where there is no data on the tile edges, and image/jpeg format tiles COULD be used for storage efficiency where there is image data for all pixels. Images of multiple bit depths of the same MIME type MAY also be stored in a given table, for example image/png tiles in both 8 and 24 bit depths.
-
[K15] See Zoom Other Intervals for use of other zoom levels as a registered extensions.
-
[K16] See Tiles Encoding WebP regarding use of the WebP alternative tile MIME type as a registered extension.
-
[K17] Note that SQLite ignores certain column properties (those pertaining to insert, update, or delete operations) when those columns are part of a view. Therefore it is not possible to enforce rules such as NOT NULL or PRIMARY KEY for those columns. When using views, the producer is responsible for ensuring that the underlying tables are populated properly.
-
[K18] The "tiles" stipulation was removed because it prevented the use of the tile matrix mechanism by extensions for other data types.
-
[K19] The "tiles" stipulation was removed because it prevented the use of the tile matrix mechanism by extensions for other data types.
-
[K20] GeoPackage applications MAY query the gpkg_tile_matrix table or the tile pyramid user data table to determine the minimum and maximum zoom levels for a given tile pyramid table.
-
[K21] GeoPackage applications MAY query a tile pyramid user data table to determine which tiles are available at each zoom level.
-
[K22] GeoPackage applications that insert, update, or delete tile pyramid user data table tiles row records are responsible for maintaining the corresponding descriptive contents of the gpkg_tile_matrix_metadata table.
-
[K23] The
gpkg_tile_matrix_set
table contains coordinates that define a bounding box as the exact stated spatial extent for all tiles in a tile (matrix set) table. If the geographic extent of the image data contained in tiles at a particular zoom level is within but not equal to this bounding box, then the non-image area of matrix edge tiles must be padded with no-data values, preferably transparent ones. -
[K24] A GeoPackage is not required to contain any tile pyramid user data tables. Tile pyramid user data tables in a GeoPackage MAY be empty.
-
[K25] The zoom_level / tile_column / tile_row unique key is automatically indexed, and allows tiles to be selected and accessed by "z, x, y", a common convention used by some implementations. This table / view definition MAY also allow tiles to be selected based on a spatially indexed bounding box in a separate metadata table.
-
[K26] If an application process will make many updates, it is often faster to drop the indexes, do the updates, and then recreate the indexes.
-
[K27] Informative examples of hierarchical metadata are provided in Hierarchical Metadata Example One - ISO19115.
-
[K28] An informative example of raster image metadata is provided in Tiles Zoom Times Two Example (Informative)
-
[K29] For example, for ISO 19139 metadata the URI value should be the metadata schema namespace http://www.isotc211.org/2005/gmd
-
[K30] In SQLite, the rowid value is always equal to the value of a single-column primary key on an integer column [B30] and is not changed by a database reorganization performed by the VACUUM SQL command.
-
[K31] Such a metadata hierarchy MAY have only one level of defined metadata
-
[K32] The scope codes in Metadata Scopes include a very wide set of descriptive information types as "metadata" to describe data.
-
[K33] ISO 19139 format metadata (B32) is recommended for general-purpose description of geospatial data at the series and dataset metadata scopes.
-
[K34] The "catalog" md_scope MAY be used for Feature Catalog (B40) information stored as XML metadata that is linked to features stored in a GeoPackage.
-
[K35] The "schema" md_scope MAY be used for Application Schema (B37)(B38)(B39)(B44) information stored as XML metadata that is linked to features stored in a GeoPackage.
-
[K36] The "taxonomy" md_scope MAY be used for taxonomy or knowledge system (B41)(B42) "linked data" information stored as XML metadata that is linked to features stored in a GeoPackage.
-
[K37] The following statement selects an ISO 8601timestamp value using the SQLite strftime function: SELECT (strftime('%Y-%m-%dT%H:%M:%fZ','now')).
-
[K38] A GeoPackage is not required to contain a gpkg_data_columns table. The gpkg_data_columns table in a GeoPackage MAY be empty.
-
[K39] GeoPackages MAY contain MIME types other than the raster image types specified in clauses 2.2.4, 2.2.5, and 3.2.2 as feature attributes, but they are not required to do so.