Open Geospatial Consortium

Submission Date: 2019-08-22

Approval Date:   2019-09-16

Publication Date:   2019-11-25

External identifier of this OGC® document: http://www.opengis.net/doc/DP/proposed-gpkg-enhance

Internal reference number of this OGC® document:    19-047

Category: OGC® Discussion Paper

Editor:   Jeff Yutzler

Proposed OGC GeoPackage Enhancements

Copyright notice

Copyright © 2019 Open Geospatial Consortium

To obtain additional rights of use, visit http://www.opengeospatial.org/legal/

Warning

This document is not an OGC Standard. This document is an OGC Discussion Paper and is therefore not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, an OGC Discussion Paper should not be referenced as required or mandatory technology in procurements.

Document type:    OGC® Discussion Paper

Document subtype:

Document stage:    Approved for public release

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.

i. Abstract

The Open Geospatial Consortium (OGC) GeoPackage Encoding Standard was developed for the purpose of providing an open, standards-based, platform-independent, portable, self-describing, compact format for transferring geospatial information. GeoPackage has proven to be an effective "container" mechanism for bundling and sharing geospatial data for a variety of operational use cases. However, GeoPackage stakeholders have observed persistent interoperability issues, particularly with regards to metadata, extensions, and portrayal.

This paper presents the operational need, proposed approach, and way ahead for addressing these interoperability issues. Section 6 presents three new enhancements (extensions) that are designed to improve the interoperability of GeoPackages in general and metadata in particular. Section 7 presents a vision for implementing an Open Portrayal Framework in GeoPackage. Annex A presents specifications for all of the GeoPackage extensions proposed in this paper. Annex B presents a JSON schema for the proposed encoding for application profiles presented in Section 6. In general, the GeoPackage Standards Working Group (SWG) looks to standardize extensions that address a clear use case, have a sound technical approach, and have a commitment to implementation by multiple organizations. As with the GeoPackage Tiled Gridded Coverage Extension and the GeoPackage Related Tables Extension, these new extensions would be tracked as separate documents from the core GeoPackage Encoding Standard.

The GeoPackage community will benefit from the increased interoperability of operational “mission-ready” GeoPackages that will result from this approach. Additionally, software will be able to quickly determine the validity and utility of a GeoPackage in target operational environments. This will help ensure that GeoPackage production-consumption lifecycles and supporting application tools and services are better aligned with stakeholder missions.

ii. Keywords

The following are keywords to be used by search engines and document catalogues.

ogcdoc, OGC document, geopackage, metadata, profile, application, sqlite

iii. Preface

Note

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.

iv. Submitting organizations

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

Organization name(s):

  • Image Matters LLC

All questions regarding this submission should be directed to the editor or the submitters:

  • Jeff Yutzler, Image Matters LLC

  • Gate Jantaraweragul, Image Matters LLC

  • Carl Reed, Carl Reed and Associates

1. Scope

The goal of this Discussion Paper is to spread awareness of the way ahead for resolving GeoPackage interoperability issues that have been observed by the implementation community.

2. Conformance

This Discussion Paper defines draft specifications for a number of GeoPackage extensions. However, normative requirements for these extensions have not yet been developed. Therefore, conformance with this Discussion Paper is not applicable.

3. References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

IETF: RFC 7946: The GeoJSON Format, https://tools.ietf.org/html/rfc7946 (2016)

OGC: OGC 05-078r4, OpenGIS Styled Layer Descriptor Profile of the Web Map Service Implementation Specification (2007)

OGC: OGC 12-128r15, OGC® GeoPackage Encoding Standard Version 1.2.1, http://www.geopackage.org/spec121 (2018)

OGC: OGC 18-000, OGC GeoPackage Related Tables Extension, http://docs.opengeospatial.org/is/18-000/18-000.html (2019)

4. Terms and Definitions

This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r8], 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 Best Practice.

For the purposes of this report, the definitions specified in Clause 4 of the OWS Common Implementation Standard OGC 06-121r9 shall apply. In addition, the following terms and definitions apply.

  • Conceptual Model (CM)

    ISO defines a "conceptual model" as "a model that defines concepts of a universe of discourse" in https://www.iso.org/standard/69325.html[ISO 19101].
In the field of computer science, CM is a particular case of a general conceptual model which is also called a domain model.
In this ER, CM is an abstract model to represent the abstract concepts, relevant term, basic entities, their behavior (or attributes) and their relationships used by domain experts.
A CM is explicitly chosen to be independent of a specific design, encoding or implementation concerns.

  • 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 the OGC GeoPackage encoding standard.

  • Feature

    Representation of some real-world object or phenomenon, e.g. a building, a river, or a person. A feature may or may not have geometric aspects.

  • GeoJSON

    GeoJSON is an open standard format designed for representing simple geographical features, along with their non-spatial attributes. It is based on JSON, the JavaScript Object Notation. The geometries of features include points, line strings, polygons, and multi-part collections of these types (source: https://tools.ietf.org/html/rfc7946).

  • GeoPackage file

    A platform-independent SQLite database file that contains geospatial data and metadata tables with specified definitions, integrity assertions, format limitations and content constraints, all of which comply with the requirements stated in the OGC GeoPackage encoding standard.

  • Interoperability

    The capability to communicate, execute programs, or transfer data among various functional units in a manner that requires the user to have little or no knowledge of the unique characteristics of those units (source: https://www.iso.org/standard/59221.html[ISO 19119]).

  • Layer

    The basic unit of geographic information that may be requested as a map from a server.

  • Map

    A pictorial representation of geographic data.

  • Model

    Abstraction of some aspects of a universe of discourse https://www.iso.org/standard/59193.html[ISO 19109].

  • Portrayal

    Portrayal presentation of information to humans https://www.iso.org/standard/46226.html[ISO 19117].

  • Stylable Layer Set

    A StylableLayerSet is a set of layers (those identified as associated with that StylableLayerSet) to which a particular set of style sheet documents (those associated with that StylableLayerSet) can be applied to.
The multiple layers within a multi-layer tile set would typically be associated with a unique StylableLayerSet. A StylableLayerSet could also be shared by multiple tile sets meant to be used together (especially when each tile set contains a single layer), or by a group of tile sets or layers following the same schema(s).

  • Style

    Styles provide the mapping from feature types and feature properties and constraints to parameterized symbols used in drawing maps. (source: OGC Glossary of Terms)
A style organizes the rules of symbolizing instructions to be applied by a rendering engine on one or more geographic features and/or coverages. (from working group consensus Jan 18, 2019)

  • Style Set

    A style set is a label for a group of style sheets which would typically be unique for a multi-layer tile set.
A style set could also be shared by multiple tile sets meant to be used together, each containing a single layer, or a group of tile sets with the same schema.

  • Style Sheet

    A style sheet is a container for styling rules for a single layer or for multiple layers.

  • Styles API

    A Web API for accessing, uploading, deleting and editing styles.

  • Tile

    A geometric shape with known properties that is the result of the tiling (tessellation) of a plane. A tile consists of a single connected "piece" without "holes" or "lines" (topological disc).

  • Tile Set

    A set of tiles with common properties that meets the definition of a tessellation. In short, a collection of subsets of the plane, i.e. tiles, which cover the space without gaps or overlaps.
Note

A comment on the correct terminology for 'Vector Tiles' is appropriate before continuing. The decision made by the participants is as follows: When explicitly referring to the conceptual model and addressing tiled point, poly-line and polygon data in a formal context the correct terminology is Tiled Feature Data. When discussing the initial pilot, the extension work and the associated extensions using the terms 'Vector Tile(s)' is accepted.

4.1. Abbreviated terms

  • BLOB Binary Large OBject

  • CDS Concept Development Study

  • COTS Customer Off The Shelf

  • CRS Coordinate Reference System

  • CSS Cascading Style Sheets

  • DDIL Denied, Degraded, Intermittent, or Limited

  • GeoJSON Geospatial JavaScript Object Notation

  • GPKG GeoPackage

  • KML Keyhole Markup Language

  • JSON JavaScript Object Notation

  • MVT Mapbox Vector Tiles

  • OGC Open Geospatial Consortium

  • OPF Open Portrayal Framework

  • OWS OGC Web Services

  • RTE Related Tables Extension

  • SLD Styled Layer Descriptor

  • SRS Spatial Reference System

  • SWG Standards Working Group

  • VT Vector Tiles, Vector Tiling, Vectiles

  • VTP Vector Tiles Pilot

  • VTPExt Vector Tiles Pilot Extension

  • WFS Web Feature Service

  • WMS Web Map Service

  • WMTS Web Map Tile Service

  • XML eXtensible Markup Language

5. Conventions

The GeoPackage database diagrams in section 6 are a modified form of Unified Modeling Language (UML) class diagrams. Tables are indicated with a T icon. Tables are grouped logically into packages for presentation purposes, but this logical structure is not actually reflected in the database itself. Solid arrows indicate a foreign key relationship via the labeled property. Dashed arrows indicate a table name reference via the named column. Where relevant, an * indicates a multiplicity of 1..n. PlantUML was used to render the diagrams from plain text.

GeoPackage extensions in Annex A are developed in accordance with the GeoPackage Extension Template.

The schema in Annex B.1 is developed in accordance with JSON Schema draft 07.

6. GeoPackage Proposals (Informative)

6.1. Metadata Profiles

GeoPackage has supported metadata since version 1.0. In version 1.0, metadata was supported through the metadata option. In version 1.1, this section of the standard was relegated to an extension so that it would be more consistent with other parts of the GeoPackage standard. This approach has proven to not be enough of a change. The Metadata Extension is rarely being used operationally and effective GeoPackage client support for metadata is even less common.

The contributors to this paper believe that while the Metadata Extension is potentially a very powerful tool, the mechanism is insufficiently defined to be workable operationally. There is currently no agreement on the meaning and significance of metadata in GeoPackage or how that metadata should be used to serve any particular purpose. In addition, someone opening a GeoPackage would have no way of recognizing that the file has any particular type of metadata in it. They would have to inspect every single row in the gpkg_metadata table. This lack of guidance places an unreasonable demand on developers.

This paper presents an approach for addressing these gaps by introducing GeoPackage "metadata profiles". A metadata profile is an agreement on what a metadata document will look like and how it will be used in a GeoPackage. The proposal is to leverage the extension mechanism to hold the information that expresses this agreement. The proposed approach has two parts:

  • Creating a new extension that defines a new extension "scope" (i.e., the gpkg_extensions.scope column) of "metadata"

  • Creating an extension for each metadata profile that describes the meaning and significance of a particular type of metadata

6.1.1. Metadata Extension Review

Before delving deeper into the metadata proposals, reviewing the Metadata Extension as it exists today may be beneficial. The following content is drawn from the GeoPackage Getting Started Guide.

The extension provides a means to store metadata in a GeoPackage and relate it to content already in the GeoPackage. There is no GeoPackage requirement that any such metadata be provided. This extension simply provides a mechanism for storing such information. The metadata extension is agnostic with regards to the metadata model and/or standard used. Metadata may be encoded in accordance with any authoritative metadata specification and in any content encoding.

gpkg_extensions

To use this extension, add the following rows to [this table](http://www.geopackage.org/spec121/#gpkg_extensions_cols).

table_name column_name extension_name definition scope

gpkg_metadata

NULL

gpkg_metadata

http://www.geopackage.org/spec121/#extension_metadata

read-write

gpkg_metadata_reference

NULL

gpkg_metadata

http://www.geopackage.org/spec121/#extension_metadata

read-write
gpkg_metadata

Add a row to [this table](http://www.geopackage.org/spec121/#gpkg_metadata_cols) for each metadata document.

Column Value

id

primary key

md_scope

[Metadata Scope](http://www.geopackage.org/spec120/#metadata_scopes) - default "dataset"

md_standard_uri

Uniform Resource Identifier (URI) reference to the metadata structure definition authority (e.g., http://metadata.ces.mil/dse/ns/GSIP/nmis/2.2.0/doc for the NSG Metadata Implementation Specification (NMIS))

mime_type

MIME encoding of metadata (e.g., text/xml)

metadata

The actual metadata document
gpkg_metadata_reference

Add a row to [this table](http://www.geopackage.org/spec121/#gpkg_metadata_reference_cols) for each GeoPackage, table, column, row, or row/column that has a metadata document. Multiple rows can refer to a single gpkg_metadata entry. It is also possible for an element (geopackage, table, column, row, or row/column) to have multiple metadata documents.

Column Value

reference_scope

one of "geopackage", "table", "column", "row", or "row/col"

table_name

user-defined table name (or NULL for whole GeoPackage)

column_name

for reference_scope of "column" or "row/col", column name in user-defined table (NULL otherwise)

row_id_value

for reference_scope of "row" or "row/col", the row ID (NULL otherwise)

timestamp

timestamp value in ISO 8601 format

md_file_id

Foreign key to gpkg_metadata

md_parent_id

Foreign key to the parent metadata document (if applicable, NULL otherwise)

6.1.2. Metadata Profiles Implementation

A metadata profile is an optional agreement on how metadata is to be used in a GeoPackage to meet a particular purpose. Through the GeoPackage extension mechanism, a community of interest MAY define one or more metadata profiles that specify the encoding, scope, and purpose of a particular type of metadata. Without this mechanism, a GeoPackage client would be forced to inspect all metadata content to respect an out-of-band (non-machine-encoded) agreement to determine how metadata is being used in that GeoPackage.

The contributors to this paper propose implementing metadata profiles through the following:

  • A new extension that adds add a new "scope" value to gpkg_extensions of "metadata" (as opposed to "read-write" or "write-only") to differentiate it from other extension types.

  • A new extension with this scope to capture the rules and use for each specific metadata profile.

These changes would be backward compatible because applications not familiar with metadata profiles would simply ignore them.

The proposed approach is demonstrated through the examples presented in the following subsections.

Styles Metadata

Testbed-15 participants identified a need for metadata for styles. In conjunction with a Styles Extension (see GeoPackage Open Portrayal Framework (Informative)), a metadata profile would describe the style metadata. Figure 1 illustrates the relationship between the relevant GeoPackage tables when this metadata profile is in use.

styles metadata
Figure 1. GeoPackage Styles Metadata Model
Dataset Provenance

By default, there is no indication of where the data for particular GeoPackage content originated. If in-field updates are to be possible, a GeoPackage client would need some way of knowing the origin of the data. By adding metadata documents for each layer to a GeoPackage, a GeoPackage client would have the information necessary to perform delta updates. There are two candidate encodings for this information, each captured in a separate draft metadata profile:

Figure 2 illustrates the relationship between the relevant GeoPackage tables when this metadata profile is in use.

contents metadata
Figure 2. GeoPackage Dataset Provenance Model
Delta Updates

Some GeoPackage stakeholders have identified a need to track updates to a GeoPackage, for example, in a disconnected mode. This would potentially allow those updates to be tracked, reviewed, and applied to another repository. GeoPackage is a single-user database with no built-in security so any management of updates beyond version and checksum will rely on the trustworthiness of software and users. With that understanding, the GeoPackage Metadata Extension supports the elements needed to track updates made locally.

The contributors to this paper propose a delta updates metadata profile. This profile includes the following:

  • A single row can be added to gpkg_metadata for each collection (editing) session. The contributors to this paper propose to use an OWS Context document containing citation information as the metadata document.

  • Then a row can be added to gpkg_metadata_references for each edit. That row can reference a row or row/column combination.

This metadata profile can be used in conjunction with the dataset provenance metadata profile discussed in the previous section to enable in-field delta updates. Even if this mechanism is not in place, delta updates can still be performed after-the-fact through these tables.

Figure 3 illustrates the relationship between the relevant GeoPackage tables when this metadata profile is in use.

delta updates
Figure 3. GeoPackage Delta Updates Model
Note

This metadata profile is similar to what was originally presented in the GeoPackage Encoding Standard as hierarchical metadata example number 2.

6.1.3. Way Ahead

The contributors to this paper intend to present this concept to OGC’s Metadata Domain Working Group (DWG). If the DWG is amenable to the approach, it may lead to an interoperability experiment. Individual metadata profiles would need to be developed independently and standardized if they are to be required operationally.

Note

The GeoPackage SWG considered this approach in July 2019, but did not agree to accept it at that time. One possible reason for the motion’s failure to pass is that things were moving too quickly and that this was too important to be rushed with minimal discussion and experimentation.

6.2. Application Profiles

The GeoPackage community wants GeoPackage to be interoperable, but it is not easy to achieve interoperability in an ecosystem that is extensible by design. The GeoPackage community has observed persistent interoperability issues in GeoPackage use, particularly when participants make use of GeoPackage’s open-ended extension mechanism. Multiple interoperability experiments have demonstrated that the desired level of interoperability has not been achieved yet. In particular, organizations that want to use GeoPackages from disparate sources are not having great success. Feedback from the GeoPackage community includes the following:

  • GeoPackage has many degrees of freedom, including but not limited to extensions e.g., Spatial Reference Systems (SRSs), geometry types, tile matrix sets, tile formats, etc.;

  • Conformance to the standard is no guarantee of interoperability, and;

  • There is currently no clear way to determine whether a client will be able to fully use the information available in a particular GeoPackage.

While the gpkg_extensions table declares what extensions are in use, this is not proving to provide sufficient information. There are some options that are not explicitly defined through this mechanism and cannot be determined without a row-by-row scan of GeoPackage data tables. This is a convoluted process that would add unreasonable time to GeoPackage loads.

The contributors to this paper propose improving interoperability by introducing application profiles to GeoPackage. An application profile would categorize and itemize a set of optional elements for a particular GeoPackage. Application profiles have a role for communities of interest, GeoPackage producers, and GeoPackage clients. Application profiles could be implemented operationally through three incremental capabilities described in the following subsections.

6.2.1. Ad-hoc Agreements

In some circumstances, it may be sufficient to have an ad-hoc agreement (verbal or written) on what GeoPackage options are to be used in a particular scenario. Communities of Interest could attempt to convey the specific options that are permitted and required for GeoPackages and GeoPackage clients. GeoPackage producers could attempt to convey what types of business objects have been added to a GeoPackage (feature, layer, map, 3D scene, observation, etc.) and what options were used to manage that information. Meanwhile, GeoPackage consumers would attempt to convey the specific GeoPackage elements that their software supports. While this "checklist" approach is difficult to enforce, it is a reasonable stop-gap that would potentially work in closed ecosystems.

6.2.2. Machine-readable Manifests

The standard will benefit from a uniform manner capturing the information described in the "Ad-hoc Agreements" above. Use of machine-readable documents would provide a robust way to convey that information in a way that can be verified and enforced completely through software. The proposal is for a new metadata profile (metadata scope: "manifest", reference scope: "geopackage") and a new metadata document that captures this information. Annex B contains the working version of the JSON Schema for GeoPackage Application Profiles along with an example document. Ideally the JSON Schema should be standardized, but that is outside of the scope of this discussion paper.

Note

The metadata scope of "manifest" is new and not currently on the list of approved metadata scopes.

This capability would benefit communities of interest, GeoPackage producers, and GeoPackage consumers.

  • Communities of interest would be able to publish application profiles that encapsulate the allowed optional and required set of options for a GeoPackage within that community. Communities of interest could also encourage the development and use of software that can produce an application profile, add a manifest to a GeoPackage, and/or validate that the contents of a particular GeoPackage conform to its manifest.

  • GeoPackage producers will be able to clearly and consistently convey the specific content that have been added to a GeoPackage and then validate that the content is encoded in accordance with the standard.

  • GeoPackage clients will be able to readily validate and/or exploit "mission-ready" GeoPackage contents and notify users when a GeoPackage contains elements that the software is not designed to handle.

When this capability is in place, there should be no confusion about whether GeoPackages can be used operationally in a given domain or application environment.

6.2.3. Bill of Materials

Application profiles may also be used as a "bill of materials" that specifies a set of options that may be incorporated into a GeoPackage. Allowing GeoPackage consumers to provide a bill of materials with a GeoPackage production request would allow a GeoPackage producer to produce a GeoPackage that only uses white-listed set of options. The ensuing GeoPackage would still contain a manifest and, by agreement, this manifest would only contain elements that were present in the bill of materials.

6.2.4. Way Ahead

The next step would be an interoperability experiment to determine if application profiles can be produced, shared between participants, and encoded into GeoPackages as manifests. An interoperability experiment would also provide an opportunity for participants to review the JSON encoding and recommend changes before it becomes standardized. As with other metadata profiles, the metadata profile for manifests would need to be standardized. The GeoPackage community would also benefit from open tools to produce application profiles, encode them into GeoPackages as manifests, validate that GeoPackages conform to their own manifests, and produce GeoPackages that conform to a bill of materials.

6.3. Semantic Annotations

Interoperability is greatly hindered when formal semantics are lacking from data descriptions. There is an unbounded set of ancillary information that may be operationally relevant to GeoPackage users. Members of the GeoPackage community have periodically proposed adding additional columns to existing GeoPackage tables to address one-off operational needs. Adding additional columns to existing tables introduces interoperability risks and does not necessarily meet operational needs due to their unclear semantics.

In response, the a new extension to allow Semantic Annotations to be placed on any GeoPackage business objects is proposed. The schema for a Semantic Annotation is straight-forward, including resolvable URIs and types along with a human-readable name and description. Semantic Annotations are linked to business objects via the Related Tables Extension.

There is a wide range of ways these annotations can be used, including but not limited to real-time context-sensitive behaviors during mission operations. Some examples of these scenarios are presented in the following subsections. For non-semantically-aware systems, a semantic annotation is effectively a "category" or tag.

6.3.1. Example 1: Linking Layers to Styles

As the OGC develops its vision for an open portrayal framework, the coupling of styles and layers is unclear. Since the styles that will work for a particular layer are independent of the data (and may be produced by one or more completely different organizations), a loose coupling between layers and styles is preferred. By annotating layers (regardless of content type) with known valid styles, a GeoPackage client may provide a user a reasonable set of style options to choose from. Whether the styles are stored directly in the GeoPackage or are accessible through a separate style service, the client will be able to retrieve the styles and apply them to the data in the layer.

Figure 4 illustrates the relationship between these tables when these semantic annotations are in use.

styles
Figure 4. Model for Layer-to-Style Semantic Annotations

6.3.2. Example 2: Stylable Layer Sets

The "stylable layer set" concept was introduced to group multiple styles that apply to the same data set or schema. For example, a stylable layer set could apply to a theater of operations and could group a set of styles (e.g., "topographic", "satellite overlay", and "night") The original proposal called for a column to be added to a pair of tables, but the semantic annotation approach would be more flexible and could be applied to any content type. In this case, both the layers and the styles could be annotated with one or more stylable layer sets.

Figure 5 illustrates the relationship between these tables when these semantic annotations are in use.

stylable layer set
Figure 5. Model for Semantic Annotations for Stylable Layer Sets

6.3.3. Example 3: Layer-to-Layer Linking

When a GeoPackage contains a relatively large volume of vector data (either in conventional or tiled layers), it is a recommended practice to pre-render raster tiles that cover a large geographic area. This reduces the need to render extreme numbers of features at run-time. In scenarios where a full OWS Context is considered to be over-kill for the scenario, a simple semantic annotation can be used to link vector and raster layers that represent the same underlying data.

6.3.4. Way Ahead

As with other GeoPackage capabilities, this would be implemented in GeoPackage as an extension that would require its own maintenance cycle, including an interoperability experiment to vet the approach and standardization as an independent document.

7. GeoPackage Open Portrayal Framework (Informative)

The goal of the OGC Open Portrayal Framework (OPF) is to allow production of high-quality digital maps over the web from existing vector data. This section describes the challenges and proposed mitigations specifically for GeoPackage producers and clients. Figure 6 illustrates a generalized view of a spatial data infrastructure. As shown on the left side of the diagram, features and styles are often developed independently of each other. A data producer may not have any knowledge of the portrayal requirements which are often the purview of a completely different organization. A successful OPF must also account for the possibility that there is a many-to-many relationship between potential data sources and potential visualizations.

overview
Figure 6. Open Portrayal Framework Overview

The rest of this section explores the following three challenges to implementing an OPF:

  1. Conveying the styling rules;

  2. Coupling layers with styles;

  3. Making the styling rules accessible operationally.

7.1. Conveying Styling Rules

Styling rules must be encapsulated in a common encoding that can be used by GeoPackage clients to render (draw) the features onto the screen in a prescribed way. Participants in the OGC Testbed-15 OPF Thread asserted that it is not realistic for the community to select a single encoding for styling rules. There are too many diverse requirements, existing encodings are too entrenched, and introducing a completely new encoding would be too risky and expensive. That said, the GeoPackage community would benefit from a default encoding. An ideal encoding would be standardized, easy to implement and use, and capable of handling the gamut of basic portrayal needs. Unfortunately, no single encoding has all three of these traits. As part of the OPF thread in Testbed-15, participants are using two encodings.

  • OGC’s Styled Layer Descriptor (SLD) is an OGC standard and handles most basic portrayal requirements, but its XML-based structure is considered by many to be difficult to use. In addition, XML is a poor choice for mobile computing environments where GeoPackage is commonly used.

  • Mapbox Styles is not standardized but it does handle most basic portrayal requirements and its JSON-based structure is considered relatively easy to use.

As a result, the submitters recommend a flexible approach to portrayal encodings.

  • Organizations that demand standards-based approaches should use SLD.

  • Organizations with more flexible requirements may be better off using Mapbox Styles.

  • GeoPackage should support other encodings, either explicitly or through the use of extensions as is proposed with tiled feature data (aka vector tiles)[1]. This will allow organizations to innovate as technology evolves.

While allowing multiple style encodings does not maximize interoperability, it is the best solution available at this time that considers the needs of both the procurement community and the developers operating in a more agile environment. Each portrayal engine will have its own internal model for handling styles. The emergence of a symbology conceptual model (currently under development as OGC 18-067) will assist developers in mapping from one or more style encodings to their internal model.

7.2. Coupling Layers and Styles

Since styles and data layers are often developed independently, an effective spatial data infrastructure needs a way to couple layers with styling rules that are appropriate for those layers. This is particularly important in GeoPackage where software capabilities tend to be more limited to support streamlined workflows that are easy to train for. The first requirement for effective style management is to provide a resolvable URI for each style. After that, there is some flexibility.

  • Independent map views, each with their own sets of layers and corresponding styles, can be encoded in the GeoPackage as OWS Context files using the proposed OWS Context Extension. For example, a topographic map may have no background (or possibly a single-colored base map as a background) and one or more feature layers, each with a specific style (referenced by its URI). A corresponding satellite overlay map may have raster tiles as a background with the same set of feature layers, but with a different set of styles. The GeoPackage client then provides a list of available contexts to the operator. This approach is the simplest for the operator, but it does not provide the operator any way to customize the display.

  • Semantic Annotations can be used to couple layers with styles. In this case, it is the GeoPackage client’s responsibility to provide the appropriate list of styles to the operator. The operator can then select the desired style on a layer-by-layer basis.

  • Semantic Annotations can also be used to couple layers with stylable layer sets. In this case, the GeoPackage client’s and operator’s responsibilities are similar, but the organization of the styles is slightly different.

7.3. Making Styles Accessible Operationally

While the previous section describes how to couple layers and styles together, it does not address the challenge of getting the styles to the GeoPackage client so that they can be used to visualize the data. Since there are a number of operational settings that a GeoPackage client may operate in, the infrastructure needs a number of ways to retrieve style information. Some of these ways include the following:

  1. In a connected environment, a GeoPackage client may retrieve a style directly via its URI. In a mature architecture, the service hosting the style would be able to provide it in more than one encoding so that it can meet the needs of disparate clients.

  2. In a disconnected environment, a GeoPackage client may retrieve a style directly from a GeoPackage via the proposed Styles Extension. When used in conjunction with manifests, a client would be able to discover that the Styles Extension is in use and what specific options (particularly encodings) are supported. The responsibility of the GeoPackage producer would then be to ensure that the styles are added in all of the necessary encodings and that the manifest fully reflects the GeoPackage’s contents.

  3. In a mixed environment, a GeoPackage client may retrieve a style through a style service (i.e., registry) that can resolve a style via its URI. In this scenario, the service decouples the style from where it is stored[2]. This provides flexibility beyond what would be appropriate for a GeoPackage Client to manage by itself.

Annex A: Proposed GeoPackage Extensions (Informative)

A.1. GeoPackage Metadata Profiles Extension

Warning

This subsection is under discussion and may change radically.

Extension Title

Metadata Profiles Extension

Introduction

A metadata profile establishes rules for using the Metadata Extension to meet a specific purpose. Use of this extension signifies that metadata profiles are in use in the current GeoPackage.

Extension Author

Image Matters LLC, in collaboration with the participants of OGC Testbed-15.

Extension Name or Template

im_metadata_profiles (will become gpkg_metadata_profiles if adopted by OGC)

Extension Type

New requirement dependent on GeoPackage Metadata Extension and extending Requirement 64.

Applicability

This extension allows for the definition of metadata profiles to describe a particular class of metadata use.

Scope

read-write

Specification

gpkg_extensions

To use this extension, add the following rows to this table in addition to the rows required for the Metadata Extension and any metadata profiles.

Table 1. gpkg_extensions table row
table_name column_name extension_name definition scope

gpkg_metadata

null

im_metadata_profiles

a reference to this file

read-write
Note

The values in the definition column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by OGC, it will gain the "gpkg_" prefix and get a different definition permalink.

Creating New Metadata Profiles

To create a new metadata profile, write a new extension specifying the following:

  1. A row in gpkg_extensions with the values as per gpkg_extensions table row for a metadata profile

  2. The values for the md_scope, md_standard_uri, and mime_type columns of gpkg_metadata that jointly identify this particular profile

  3. The allowed values for the reference_scope column of gpkg_metadata_references

Table 2. gpkg_extensions table row for a metadata profile
table_name column_name extension_name definition scope

gpkg_metadata

metadata

an extension name

a reference to this file

metadata
Note

Before this extension, gpkg_extensions.scope values were limited to "read-write" and "write-only".

A.2. GeoPackage Dataset Provenance GeoJSON Metadata Profile

Warning

This subsection is under discussion and may change radically.

Extension Title

Dataset Provenance Metadata Profile

Introduction

A metadata profile establishes rules for using the Metadata Extension to meet a specific purpose. This profile indicates how to present the metadata describing the provenance of a specific dataset. The metadata document itself is a GeoJSON-encoded OWS Context as per the OWS Context GeoJSON Encoding Standard. The FeatureCollection in this document will have citation information in the properties object and a single Feature object that indicates where the dataset was derived from.

Extension Author

Image Matters LLC, in collaboration with the participants of OGC Testbed-15.

Extension Name or Template

im_metadata_dataset_provenance (will become gpkg_metadata_dataset_provenance if adopted by OGC)

Extension Type

New requirement dependent on GeoPackage Metadata Extension and Metadata Profiles.

Applicability

This extension allows for the storage of metadata pertaining to the provenance of a specific dataset.

Scope

read-write

Specification

gpkg_extensions

To use this extension, add the following row to this table.

Table 3. gpkg_extensions Table Rows
table_name column_name extension_name definition scope

gpkg_metadata

metadata

im_metadata_dataset_provenance

a reference to this file

metadata
Note

The values in the definition column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by OGC, it will gain the "gpkg_" prefix and get a different definition permalink.
gpkg_metadata

For every dataset, add a row to the gpkg_metadata table with the following values:

  • id is a primary key

  • md_scope "dataset"

  • md_standard_uri "https://portal.opengeospatial.org/files/?artifact_id=68826"

  • mime_type "application/json"

  • metadata the actual metadata document

gpkg_metadata_references

For every dataset, add a row to the gpkg_metadata_references table with the following values:

  • reference_scope "row"

  • table_name the gpkg_contents.table_name for that dataset

  • column_name null

  • row_id_value null

  • timestamp strftime(\'%Y-%m-%dT%H:%M:%fZ', \'now')

  • md_file_id the gpkg_metadata.id for that metadata document

  • md_parent_id null

A.3. GeoPackage Updates Metadata Profile

Warning

This subsection is under discussion and may change radically.

Extension Title

Updates Metadata Profile

Introduction

A metadata profile establishes rules for using the Metadata Extension to meet a specific purpose. This profile indicates how to present the metadata describing the citation information for specific updates to a GeoPackage. The metadata document itself is a GeoJSON-encoded OWS Context as per the OWS Context GeoJSON Encoding Standard. The FeatureCollection object will not have any Features but will have citation information in its properties object.

Extension Author

Image Matters LLC, in collaboration with the participants of OGC Testbed-15.

Extension Name or Template

im_metadata_updates (will become gpkg_metadata_updates if adopted by OGC)

Extension Type

New requirement dependent on GeoPackage Metadata Extension and Metadata Profiles.

Applicability

This extension allows for the storage of metadata pertaining to the citation information for modifications to a GeoPackage table, its rows, or its column values.

Scope

read-write

Specification

gpkg_extensions

To use this extension, add the following row to this table.

Table 4. gpkg_extensions Table Rows
table_name column_name extension_name definition scope

gpkg_metadata

metadata

im_metadata_updates

a reference to this file

metadata
Note

The values in the definition column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by OGC, it will gain the "gpkg_" prefix and get a different definition permalink.
gpkg_metadata

For every dataset, add a row to the gpkg_metadata table with the following values:

  • id is a primary key

  • md_scope "collectionSession"

  • md_standard_uri "https://portal.opengeospatial.org/files/?artifact_id=68826"

  • mime_type "application/json"

  • metadata the actual metadata document

gpkg_metadata_references

For every dataset, add a row to the gpkg_metadata_references table with the following values:

  • reference_scope "table", "row", or "row/col"

  • table_name the gpkg_contents.table_name for that dataset

  • column_name the column name or null

  • row_id_value the row ID or null

  • timestamp strftime(\'%Y-%m-%dT%H:%M:%fZ', \'now')

  • md_file_id the gpkg_metadata.id for that metadata document

  • md_parent_id null

A.4. GeoPackage Styles Metadata Profile

Warning

This subsection is under discussion and may change radically.

Extension Title

Styles Metadata Profile

Introduction

A metadata profile establishes rules for using the Metadata Extension to meet a specific purpose. This profile indicates how to present the metadata describing a specific stylesheet as per the Styles and Symbology Extension. The specification for the metadata document itself is currently under development, but the working draft is currently available at https://app.swaggerhub.com/apis/cportele/opf-style-api/1.0.0/Use%20styles/getStyleMetadata.

Extension Author

Image Matters LLC, in collaboration with the participants of OGC Testbed-15.

Extension Name or Template

im_metadata_styles (will become gpkg_metadata_styles if adopted by OGC)

Extension Type

New requirement dependent on GeoPackage Metadata Extension and Metadata Profiles.

Applicability

This extension allows for the the storage of metadata pertaining to a specific stylesheet.

Scope

read-write

Specification

gpkg_extensions

To use this extension, add the following row to this table.

Table 5. gpkg_extensions Table Rows
table_name column_name extension_name definition scope

gpkg_metadata

metadata

im_metadata_styles

a reference to this file

metadata
Note

The values in the definition column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by OGC, it will gain the "gpkg_" prefix and get a different definition permalink.
gpkg_metadata

For every stylesheet, add a row to the gpkg_metadata table with the following values:

  • id is a primary key

  • md_scope "style"

  • md_standard_uri "https://app.swaggerhub.com/apis/cportele/opf-style-api/1.0.0#/Use%20styles/getStyleMetadata"

  • mime_type "application/json"

  • metadata the actual metadata document

gpkg_metadata_references

For every stylesheet, add a row to the gpkg_metadata_references table with the following values:

  • reference_scope "row"

  • table_name "gpkgext_stylesheets"

  • column_name null

  • row_id_value the gpkgext_stylesheets.id value for that stylesheet

  • timestamp strftime(\'%Y-%m-%dT%H:%M:%fZ', \'now')

  • md_file_id the gpkg_metadata.id for that metadata document

  • md_parent_id null

A.5. GeoPackage Dataset Provenance STAC Profile

Warning

This subsection is under discussion and may change radically.

Extension Title

Dataset Provenance STAC Metadata Profile

Introduction

A metadata profile establishes rules for using the Metadata Extension to meet a specific purpose. This profile indicates how to present the metadata describing the provenance of a specific dataset. The metadata document itself is a STAC Item as per the STAC specification.

Extension Author

Image Matters LLC, in collaboration with the participants of OGC Testbed-15.

Extension Name or Template

im_metadata_dataset_stac (will become gpkg_metadata_dataset_stac if adopted by OGC)

Extension Type

New requirement dependent on GeoPackage Metadata Extension and Metadata Profiles.

Applicability

This extension allows for the storage of metadata pertaining to the provenance of a specific dataset.

Scope

read-write

Specification

gpkg_extensions

To use this extension, add the following row to this table.

Table 6. gpkg_extensions Table Rows
table_name column_name extension_name definition scope

gpkg_metadata

metadata

im_metadata_dataset_stac

a reference to this file

metadata
Note

The values in the definition column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by OGC, it will gain the "gpkg_" prefix and get a different definition permalink.
gpkg_metadata

For every dataset, add a row to the gpkg_metadata table with the following values:

  • id is a primary key

  • md_scope "dataset"

  • md_standard_uri "https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md"

  • mime_type "application/json"

  • metadata the actual metadata document

gpkg_metadata_references

For every dataset, add a row to the gpkg_metadata_references table with the following values:

  • reference_scope "row"

  • table_name the gpkg_contents.table_name for that dataset

  • column_name null

  • row_id_value null

  • timestamp strftime(\'%Y-%m-%dT%H:%M:%fZ', \'now')

  • md_file_id the gpkg_metadata.id for that metadata document

  • md_parent_id null

A.6. GeoPackage Manifest Metadata Profile

Warning

This subsection is under discussion and may change radically.

Extension Title

Manifest Metadata Profile

Introduction

A metadata profile establishes rules for using the Metadata Extension to meet a specific purpose. This profile indicates how to present the metadata describing a manifest, or in other words the elements that are in use in the GeoPackage. The metadata document itself is a JSON document with a new schema developed specifically for this purpose.

Extension Author

Image Matters LLC, in collaboration with the participants of OGC Testbed-15.

Extension Name or Template

im_metadata_manifest (will become gpkg_metadata_manifest if adopted by OGC)

Extension Type

New requirement dependent on GeoPackage Metadata Extension and Metadata Profiles.

Applicability

This extension allows for the storage of a manifest as a metadata object.

Scope

read-write

Specification

gpkg_extensions

To use this extension, add the following row to this table.

Table 7. gpkg_extensions Table Rows
table_name column_name extension_name definition scope

gpkg_metadata

metadata

im_metadata_manifest

a reference to this file

metadata
Note

The values in the definition column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by OGC, it will gain the "gpkg_" prefix and get a different definition permalink.
gpkg_metadata

For every dataset, add a row to the gpkg_metadata table with the following values:

  • id is a primary key

  • md_scope "manifest"

  • md_standard_uri "https://gitlab.com/imagemattersllc/ogc-tb-15-opf/blob/master/schema/manifest-schema.json"

  • mime_type "application/json"

  • metadata the actual metadata document

gpkg_metadata_references

For every dataset, add a row to the gpkg_metadata_references table with the following values:

  • reference_scope "geopackage"

  • table_name null

  • column_name null

  • row_id_value null

  • timestamp strftime(\'%Y-%m-%dT%H:%M:%fZ', \'now')

  • md_file_id the gpkg_metadata.id for that metadata document

  • md_parent_id null

A.7. GeoPackage Semantic Annotation Extension

Warning

This subsection is under discussion and may change radically.

Extension Title

Semantic Annotations Extension

Introduction

A semantic annotation is a semantically grounded term that can be applied to another concept. Use of this extension enables semantic annotations to be applied to any business object in the current GeoPackage.

Extension Author

Image Matters LLC, in collaboration with the participants of OGC Testbed-15.

Extension Name or Template

im_semantic_annotations (will become gpkg_semantic_annotations if adopted by OGC)

Extension Type

New requirement dependent on GeoPackage Related Tables Extension (RTE) and optionally GeoPackage Schema Extension.

Applicability

This extension can be applied to any GeoPackage business object (layers, features, tiles, styles, etc.).

Scope

read-write

Specification

gpkg_contents

To use this extension, add the following row to this table.

Table 8. gpkg_contents table row
table_name data_type identifier description last_change others

gpkgext_semantic_annotations

"attributes"

"semantic annotations"

any

any

null
gpkg_extensions

To use this extension, add the following rows to this table in addition to the rows required for the Related Tables Extension and Schema Extension (if used).

Table 9. gpkg_extensions table row
table_name column_name extension_name definition scope

gpkgext_semantic_annotations

null

im_semantic_annotations

a reference to this file

read-write
Note

The values in the definition column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by OGC, it will gain the "gpkg_" prefix and get a different definition permalink.
gpkgext_semantic_annotations

When this extension is in use, add a table with this name and the following columns:

  • id is a primary key

  • type is a semantically grounded type (category) for the annotation

  • title is a human-readable title for the annotation

  • description is an optional human-readable text description for the annotation

  • uri is the resolvable URI for the semantic concept

Using Semantic Annotations

To use semantic annotations, do the following:

  1. Add rows to gpkgext_semantic_annotations for every annotation you want to use.

    1. Optionally, use the Schema Extension to establish an enumeration for the types and further describe those types. See http://www.geopackage.org/guidance/extensions/schema.html for more details.

  2. Make a "related tables" relationship (as per http://www.geopackage.org/guidance/extensions/related_tables.html) between any business object table (base table) and gpkgext_semantic_annotations (related table).

    • The base_primary_column must be an integer. For tables like gpkg_contents with a non-integer primary key, you can use rowid instead.

    • The relation_name is "simple_attributes".

    • The mapping_table_name may be any valid, available table name. Create the table and add a row gpkg_extensions with that table name as required by the RTE.

  3. Add a row to the mapping table for each instance of the annotation. As with other RTE relationships, there may be a many-to-many relationship between the business objects and the semantic annotations.

A.8. GeoPackage OWS Context Extension

Warning

This subsection is under discussion and may change radically.

Extension Title

OWS Context

Introduction

This extension provides a mechanism for storing OWS Context content in a GeoPackage using the standard ATOM or GeoJSON encoding.

Extension Author

Image Matters LLC, in collaboration with the participants of OGC Testbed-15, the OGC Vector Tiles Pilot, and the OWS Context SWG.

Extension Name or Template

im_ows_context (will become gpkg_ows_context if adopted by OGC)

Extension Type

New requirement dependent on GeoPackage Core (Clause 1).

Applicability

This extension adds an additional level of organization to existing GeoPackage data.

Scope

read-write

Specification

gpkg_extensions

To use this extension, add the following row to this table.

Table 10. gpkg_extensions Table Rows
table_name column_name extension_name definition scope

gpkgext_contexts

null

im_ows_context

a reference to this file

read-write
Note

The values in the definition column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by OGC, it will gain the "gpkg_" prefix and get a different definition permalink.
gpkgext_contexts

This table describes OWS Context instances. The columns of this table are:

  • id is a primary key

  • name is a text label for the context

  • format is the format of the context (e.g., atom or geojson)

  • context is the actual context text

  • title is an optional text title designed to be human-readable

  • description is an optional text description designed to be human-readable

  • parent_id is a key to another context document that serves as the parent (to allow nesting)

A.9. GeoPackage Styles Extension

Warning

This subsection is under discussion and may change radically.

Extension Title

Styles

Introduction

This extension provides a mechanism for styles in a GeoPackage.

Extension Author

Image Matters LLC, in collaboration with the participants of OGC Testbed-15, the OGC Vector Tiles Pilot, and the OWS Context SWG.

Extension Name or Template

im_styles (will become gpkg_styles if adopted by OGC)

Extension Type

New requirement dependent on GeoPackage Core (Clause 1).

Applicability

This extension allows for stylesheets to be stored in a GeoPackage. How those stylesheets are used is outside of the scope of this specification, but they could be incorporated into OWS Context (see GeoPackage OWS Context Extension.

Scope

read-write

Specification

gpkg_extensions

To use this extension, add the following rows to this table.

Table 11. gpkg_extensions Table Rows
table_name column_name extension_name definition scope

gpkgext_stylesheets

null

im_styles

a reference to this file

read-write

gpkgext_symbols

null

im_styles

a reference to this file

read-write
Note

The values in the definition column SHOULD refer in some human-readable way to this extension specification. If the extension is adopted by OGC, it will gain the "gpkg_" prefix and get a different definition permalink.
gpkgext_stylesheets

This table contains stylesheets, organized by style set and option. The columns of this table are:

  • id is a primary key

  • layer_set is text defining a layer set that is suitable for styling in a common way

  • style is text describing a specific implementation for a layer set

  • format is the format of the stylesheet (e.g., mbstyle or sld)

  • stylesheet is the actual stylesheet text

  • title is an optional text title

  • description is an optional text description

  • uri is an optional resolvable URI

gpkgext_symbols

This table contains symbols, organized by style set and option. The columns of this table are:

  • id is a primary key

  • symbol_id is a string identifier such as a URI that can uniquely identify the symbol

  • content_type is the media type (formerly MIME type, e.g., image/svg+xml or image/png) of the symbol

  • symbol is the actual symbol BLOB

  • title is an optional text title

  • description is an optional text description

  • uri is an optional resolvable URI

Note

As with other GeoPackage tables, this specification takes no position on how either of these tables are to be used by a client.

Annex B: Proposed GeoPackage Application Profile (Informative)

B.1. Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://imagemattersllc.com/geopackage.manifest.0.2.json",
  "title": "GeoPackage Manifest",
  "description": "The contents of a GeoPackage",
  "type": "object",
  "properties": {
    "file_size": {
      "description": "The file size (MB)",
      "type": "number"
    },
    "version": {
      "description": "The GeoPackage Version (e.g., 1.2.1)",
      "type": "string"
    },
    "last_change": {
      "description": "RFC 3339 timestamp for this file",
      "type": "string",
      "format": "date-time"
    },
    "data_types": {
      "description": "gpkg_contents.data_types",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "gpkg_spatial_ref_sys": {
      "description": "Details on the SRSs in use",
      "type": "object",
      "properties": {
        "srss": {
          "description": "The SRSs in use",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "srs_name": {
                "description": "gpkg_spatial_ref_sys.srs_name",
                "type": "string"
              },
              "srs_id": {
                "description": "gpkg_spatial_ref_sys.srs_id",
                "type": "string"
              },
              "organization": {
                "description": "gpkg_spatial_ref_sys.organization",
                "type": "string"
              }
            },
            "required": [
              "srs_name",
              "srs_id",
              "organization"
            ]
          }
        },
        "gpkg_crs_wkt": {
          "description": "True: the WKT for Coordinate Reference Systems Extension is in use",
          "type": "boolean"
        }
      }
    },
    "options": {
      "description": "The options that are in use",
      "type": "object",
      "properties": {
        "features": {
          "description": "If exists, the features option is in use",
          "type": "object",
          "properties": {
            "geometry_type_names": {
              "description": "gpkg_geometry_columns.geometry_type_name values",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "non-linear geometry types": {
              "description": "True: at least one \"geometry_type_name\" is a non-linear geometry type requiring an extension",
              "type": "boolean"
            },
            "gpkg_rtree_index": {
              "description": "True: the RTree spatial index is in use",
              "type": "boolean"
            },
            "gpkg_schema": {
              "description": "True: the Schema extension is in use",
              "type": "boolean"
            },
            "zs": {
              "description": "gpkg_geometry_columns.z",
              "type": "array",
              "items": {
                "type": "number",
                "minimum": 0,
                "maximum": 2
              },
              "minItems": 1
            },
            "ms": {
              "description": "gpkg_geometry_columns.m",
              "type": "array",
              "items": {
                "type": "number",
                "minimum": 0,
                "maximum": 2
              },
              "minItems": 1
            }
          },
          "required": [
            "geometry_type_names"
          ]
        },
        "tiles": {
          "description": "If exists, the tiles option is in use",
          "type": "object",
          "properties": {
            "encodings": {
              "description": "Allowed encodings for a \"tile_data\" value",
              "type": "array",
              "items": {
                "type": "string"
              },
              "minItems": 1
            },
            "gpkg_tile_matrix_set": {
              "description": "options for this table",
              "type": "array",
              "items": {
                "description": "The tile matrix sets that are in use",
                "type": "object",
                "properties": {
                  "srs_id": {
                    "description": "gpkg_tile_matrix_set.srs_id",
                    "type": "number"
                  },
                  "min_x": {
                    "description": "gpkg_tile_matrix_set.min_x",
                    "type": "number"
                  },
                  "min_y": {
                    "description": "gpkg_tile_matrix_set.min_y",
                    "type": "number"
                  },
                  "max_x": {
                    "description": "gpkg_tile_matrix_set.max_x",
                    "type": "number"
                  },
                  "max_y": {
                    "description": "gpkg_tile_matrix_set.max_y",
                    "type": "number"
                  }
                },
                "required": [
                  "srs_id",
                  "min_x",
                  "max_x",
                  "min_y",
                  "max_y"
                ]
              },
              "minItems": 1
            },
            "gpkg_zoom_other": {
              "description": "True: \"Zoom Other Intervals\" extension is in use",
              "type": "boolean"
            },
            "2d-gridded-coverage": {
              "description": "If key exists, the \"gpkg_2d_gridded_coverage\" extension is in use",
              "type": "object",
              "properties": {
                "datatype": {
                  "description": "gpkg_2d_gridded_coverage_ancillary.datatype",
                  "type": "object",
                  "properties": {
                    "integer": {
                      "description": "If key exists, this datatype is in use",
                      "type": "boolean"
                    },
                    "float": {
                      "description": "If key exists, this datatype is in use",
                      "type": "object",
                      "properties": {
                        "compressed": {
                          "description": "True: the TIFF may be LZW compressed",
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            },
            "vector-tiles": {
              "description": "If key exists, the \"im_vector_tiles\" extension ise in use",
              "type": "object",
              "properties": {
                "encodings": {
                  "description": "The vector tiles encodings in use",
                  "type": "object",
                  "properties": {
                    "mapbox": {
                      "description": "If key exists, the \"im_vector_tiles_mapbox\" extension is use",
                      "type": "object",
                      "properties": {
                        "compressed": {
                          "description": "True: Mapbox Vector Tiles may be compressed",
                          "type": "boolean"
                        }
                      }
                    },
                    "geojson": {
                      "description": "If key exists, the \"im_vector_tiles_geojson\" extension is in use",
                      "type": "boolean"
                    }
                  }
                },
                "attributes": {
                  "description": "How attributes may be encoded",
                  "type": "object",
                  "properties": {
                    "embedded": {
                      "description": "True: attributes may be embedded in vector tiles",
                      "type": "boolean"
                    },
                    "table": {
                      "description": "True: attributes may be stored in an attributes table defined by gpkgext_vt_layers.attributes_table_name",
                      "type": "boolean"
                    },
                    "related_table": {
                      "description": "True: the of the vector_tiles_attributes RTE may be used to correlate features with tiles containing those features",
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "required": [
            "encodings",
            "gpkg_tile_matrix_set"
          ]
        },
        "attributes": {
          "description": "True: the attributes option is in use",
          "type": "boolean"
        }
      }
    },
    "extensions": {
      "description": "An umbrella for cross-cutting extensions",
      "type": "object",
      "properties": {
        "gpkg_extensions": {
          "description": "True: GeoPackage is an \"extended GeoPackage\"",
          "type": "object",
          "properties": {
            "extensions": {
              "description": "The gpkg_extensions.extension_name of all extensions actively in use",
              "type": "array",
              "items": {
                "description": "each extension",
                "type": "object",
                "properties": {
                  "definition": {
                    "description": "gpkg_extensions.definition",
                    "type": "string"
                  },
                  "category": {
                    "description": "standard: extension has been adopted by OGC; community: extension has not been adopted by OGC but is available for public review; proprietary: extension has not been adopted by OGC and is not available for public review",
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "gpkg_metadata": {
          "description": "If key exists, this extension is in use",
          "type": "object",
          "properties": {
            "im_metadata_profiles": {
              "description": "If key exists, the metadata profiles extension is in use",
              "type": "array",
              "items": {
                "description": "metadata profile extension name",
                "type": "string"
              }
            },
            "hierarchical": {
              "description": "True: metadata documents may be organized hierarchically",
              "type": "boolean"
            }
          }
        },
        "gpkg_related_tables": {
          "description": "If key exists, this extension is in use",
          "type": "object",
          "properties": {
            "relation_names": {
              "description": "gpkgext_relations.relation_name values in use",
              "type": "array",
              "items": {
                "type": "string"
              },
              "minItems": 1
            }
          }
        },
        "im_style": {
          "description": "If key exists, this extension is in use",
          "type": "object",
          "properties": {
            "gpkgext_stylesheets": {
              "description": "options for this table",
              "type": "object",
              "properties": {
                "format": {
                  "description": "gpkgext_stylesheets.format options",
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            },
            "gpkgext_symbols": {
              "description": "options for this table",
              "type": "object",
              "properties": {
                "content_type": {
                  "description": "gpkgext_symbols.content_type options",
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "required": [
    "last_change",
    "version",
    "gpkg_spatial_ref_sys"
  ]
}

B.2. Example

{
  "version": "1.2.1",
  "data_types": [
    "tiles",
    "features",
    "vector-tiles"
  ],
  "last_change": "2019-06-12T19:27:59.056Z",
  "gpkg_spatial_ref_sys": {
    "srss": [
      {
        "srs_name": "EPSG::3857",
        "srs_id": "3857",
        "organization": "epsg"
      }
    ]
  },
  "options": {
    "features": {
      "geometry_type_names": [
        "POINT"
      ]
    },
    "tiles": {
      "encodings": [
        "image/png",
        "image/jpg",
        "application/vnd.mapbox-vector-tile"
      ],
      "gpkg_tile_matrix_set": [
        {
          "srs_id": 3857,
          "min_x": -20026376.39,
          "min_y": -20048966.1,
          "max_x": 20026376.39,
          "max_y": 20048966.1
        }
      ],
      "vector-tiles": {
        "encodings": {
          "mapbox": {
            "compressed": true
          },
          "attributes": {
            "embedded": true
          }
        }
      }
    },
    "attributes": true
  },
  "extensions": {
    "gpkg_extensions": {
      "gpkg_rtree_index": {
        "definition": "http://www.geopackage.org/spec121/#extension_rtree",
        "category": "standard"
      },
      "gpkg_metadata": {
        "definition": "http://www.geopackage.org/spec121/#extension_metadata",
        "category": "standard"
      },
      "im_vector_tiles": {
        "definition": "https://gitlab.com/imagemattersllc/ogc-tb-15-opf/blob/master/spec/1-vte.adoc",
        "category": "community"
      },
      "im_vector_tiles_mapbox": {
        "definition": "https://gitlab.com/imagemattersllc/ogc-tb-15-opf/blob/master/spec/2-mvte.adoc",
        "category": "community"
      },
      "im_style": {
        "definition": "https://gitlab.com/imagemattersllc/ogc-tb-15-opf/blob/master/spec/5-sse.adoc",
        "category": "community"
      },
      "im_metadata_profiles": {
        "definition": "https://gitlab.com/imagemattersllc/ogc-tb-15-opf/blob/master/spec/7-metadata-profiles.adoc",
        "category": "community"
      },
      "im_metadata_styles": {
        "definition": "https://gitlab.com/imagemattersllc/ogc-tb-15-opf/blob/master/spec/11-metadata-styles.adoc",
        "category": "community"
      },
      "im_metadata_dataset_stac": {
        "definition": "https://gitlab.com/imagemattersllc/ogc-tb-15-opf/blob/master/spec/12-metadata-dataset-stac.adoc",
        "category": "community"
      },
      "im_metadata_manifest": {
        "definition": "https://gitlab.com/imagemattersllc/ogc-tb-15-opf/blob/master/spec/10-metadata-manifest.adoc",
        "category": "community"
      }
    },
    "gpkg_metadata": {
      "im_metadata_profiles": [
        "im_metadata_styles",
        "im_metadata_dataset_stac",
        "im_metadata_manifest"
      ]
    },
    "im_style": {
      "gpkgext_stylesheets": {
        "format": [
          "sld",
          "mapbox"
        ]
      },
      "gpkgext_symbols": {
        "content_type": [
          "image/svg+xml",
          "image/png"
        ]
      }
    }
  }
}

Annex C: Revision History

Date Release Editor Primary clauses modified Description

2019-08-05

0.1

Jeff Yutzler

all

initial version

2019-08-22

0.9

Jeff Yutzler

all

final draft

2019-09-12

0.91

Carl Reed

all

review

Annex D: Bibliography

  1. Saeedi, S.: OGC Testbed-14: Symbology Engineering Report. OGC 18-029, Open Geospatial Consortium, https://docs.opengeospatial.org/per/18-029.html (2019).

  2. Yutzler, J.: Vector Tiles Pilot Extension Engineering Report. OGC 18-101, Open Geospatial Consortium, https://portal.opengeospatial.org/files/?artifact_id=79181&version=1 (2019).

  3. Yutzler, J.: OGC Portrayal Concept Development Study. OGC 17-094r1, Open Geospatial Consortium, http://docs.opengeospatial.org/per/17-094r1.html (2018).

  4. Bocher, E., Ertz, O.: OGC Symbology Conceptual Model: Core part. OGC 18-067, Open Geospatial Consortium, https://portal.opengeospatial.org/files/80686 (2018).

1. The current proposal for tiled feature data is to have one extension to declare that vector tiles are allowed, then a separate extension to allow a tiles column to have a specific encoding such as Mapbox Vector Tiles or GeoJSON.
2. In this scenario, the styles may be stored directly in the GeoPackage as per the previous item.