Core concepts — containers, contents table, and spatial reference systems
Introduction
GeoPackage is an open, standards-based, platform-independent, portable, self-describing format for transferring geospatial information. Built on SQLite, it provides a lightweight yet powerful way to package spatial data, making it ideal for mobile applications, data sharing, and offline work. Understanding the foundational concepts of GeoPackage is essential for anyone working with modern geospatial data.
The Container Concept
What is a GeoPackage?
At its most fundamental level, a GeoPackage is a single file with a .gpkg extension that serves as a container for geospatial data. This container is actually an SQLite database file, which means it's a single, self-contained file that can store multiple types of spatial and non-spatial data.
Why Containers Matter
Before GeoPackage, working with geospatial data often meant managing multiple files. A shapefile, for example, requires at minimum three files (.shp, .shx, .dbf), and often more. GeoPackage solves this problem by using a single-file container that can hold:
- Multiple vector layers (feature tables)
- Raster tile sets
- Metadata and documentation
- Styling information (through extensions)
- Multiple coordinate reference systems
This "one file, everything included" approach simplifies data distribution, backup, and management. You can email a single .gpkg file containing an entire project's worth of spatial data.
The Container Concept
A GeoPackage is fundamentally a SQLite database file with a specific structure and set of requirements. This means it's a single file (with a .gpkg extension) that acts as a container for multiple datasets, their metadata, and supporting information.
Think of it like a specialized ZIP file for spatial data. Just as a ZIP file can contain multiple documents while presenting itself as a single file, a GeoPackage can contain multiple layers of vector and raster data, all their metadata, and coordinate system definitions in one portable file.
This container approach offers several advantages. You can share an entire project as a single file, there's no risk of missing auxiliary files, and all related datasets maintain their spatial relationships because they're stored together with consistent metadata.
The Contents Table: Your Data Inventory
At the heart of every GeoPackage is the gpkg_contents table, which acts as the master catalog for all data tables in the package. This table is mandatory and serves as the entry point for discovering what data exists in the GeoPackage.
Think of gpkg_contents as a library catalog. Just as a library catalog tells you what books are available, where they're located, and what they're about, the contents table tells applications what datasets exist, what type of data they contain, and where they're located spatially.
The contents table registers every user data table in the GeoPackage, whether it contains vector features, raster tiles, or non-spatial attributes. Each entry includes the table name, data type, human-readable description, spatial extent, and the coordinate system used. This allows applications to quickly discover and understand all available datasets without having to examine every table in the database.
For example, a GeoPackage containing data for a city might have entries in gpkg_contents for feature tables like roads, buildings, and parks, as well as tile tables for background imagery. Each entry tells applications what kind of data to expect and where it's located geographically.
Understanding Spatial Reference Systems
Spatial reference systems (SRS) define how coordinates relate to locations on Earth. A coordinate pair like (50.8, 4.4) is meaningless without knowing whether those numbers represent degrees of latitude/longitude, meters in a projected system, or some other unit and reference frame.
The gpkg_spatial_ref_sys table stores the spatial reference system definitions used by datasets in the GeoPackage. Every spatial dataset must reference an entry in this table through its srs_id value.
Required Spatial Reference Systems
The GeoPackage specification requires three specific spatial reference systems to be present in every valid GeoPackage:
EPSG:4326 (WGS 84 Geographic): The World Geodetic System 1984, using latitude and longitude in decimal degrees. This is the most common coordinate system for global geographic data and is used by GPS systems.
EPSG:-1 (Undefined Cartesian): Used for data where no spatial reference system is defined or needed. This is appropriate for engineering drawings, floor plans, or any coordinates that aren't tied to Earth geography.
EPSG:0 (Undefined Geographic): Used for geographic data where the specific datum is unknown or unspecified.
Spatial Reference System Identifiers
The srs_id column links to the gpkg_spatial_ref_sys table, which contains the full definition of each coordinate system. Common values include:
- 4326: WGS 84 geographic coordinates (latitude/longitude)
- 3857: Web Mercator projection (used by web mapping services)
- -1: Undefined Cartesian coordinate system
- 0: Undefined geographic coordinate system
Applications use the SRS information to properly interpret coordinates and perform spatial operations like coordinate transformations and distance calculations.
The Container Concept
At its core, GeoPackage is built on the principle of being a self-contained data container. This means everything needed to work with the spatial data—the features themselves, their metadata, spatial reference definitions, and indexes—all reside within a single file.
Benefits of the Container Approach
The container design provides several advantages. First, it simplifies data distribution and sharing. Instead of managing multiple files (shapefile's .shp, .shx, .dbf, .prj files, for example), you work with a single .gpkg file. Second, it ensures consistency because all related information travels together. Third, it leverages SQLite's reliability and ACID properties (Atomicity, Consistency, Isolation, Durability), providing robust data integrity.
The self-contained nature of GeoPackages makes them ideal for mobile applications, offline workflows, and situations where you need to package geospatial data for distribution or archival.
The Contents Table: Central Registry
Every GeoPackage contains a special table called gpkg_contents that acts as a central registry or catalog of all user data tables in the file. This table serves as the entry point for discovering what data exists within the package.
The contents table allows applications to quickly answer questions like: What datasets are available? What type of data do they contain? Where are they located spatially? When were they last updated?
Each row in gpkg_contents represents one dataset—whether it's a collection of features (vector data), a tile pyramid (raster data), or attribute-only data. This registration system ensures that applications can reliably discover and access all available data without having to search through every table in the database.
The contents table serves several critical functions. It provides a centralized inventory of all datasets, stores spatial extent information for quick spatial queries, maintains timestamps for data currency tracking, and links each dataset to its spatial reference system. This metadata-driven approach allows GeoPackage to be self-describing, meaning applications can open a GeoPackage file and immediately understand what data it contains without prior knowledge.
Spatial Reference Systems in GeoPackage
The gpkg_spatial_ref_sys table is fundamental to how GeoPackage handles coordinate systems. Every geometry in a GeoPackage must reference a spatial reference system (SRS) defined in this table.
The table contains entries that define coordinate systems using several key fields. The srs_id serves as a unique identifier, while organization and organization_coordsys_id identify the authority that defines the coordinate system (typically "EPSG" and an EPSG code). The srs_name provides a human-readable name, and the definition column contains the full coordinate system definition in Well-Known Text (WKT) format.
Every GeoPackage must include at least three predefined spatial reference systems: undefined Cartesian (-1), undefined geographic (0), and WGS 84 geographic (4326). These serve as defaults and ensure basic interoperability. When you add feature data with a specific coordinate system, you reference the appropriate srs_id from this table.
The beauty of this system is that it allows each dataset in a GeoPackage to use different coordinate systems while maintaining clear documentation of what system each uses. Applications reading the GeoPackage can then properly interpret and transform the coordinates as needed.
Working Together
These three core concepts — the container, the contents table, and spatial reference systems — form an integrated foundation. The SQLite container provides the storage mechanism, the contents table catalogs what's stored, and the spatial reference systems define how to interpret the coordinates. Together, they create a self-describing format where all the information needed to understand and use the data travels with the data itself.
This self-contained nature is one of GeoPackage's greatest strengths. A single file can be shared, backed up, or transmitted, and the recipient has everything needed to work with the data properly. There's no need to track down separate projection files, metadata documents, or auxiliary indexes.