OGC GeoPackage WKT for Coordinate Reference Systems Extension

Open Geospatial Consortium

Submission Date: 2022-04-14

Approval Date: 2022-08-20

Publication Date: 2022-10-14

External identifier of this OGC® document: http://www.opengis.net/doc/IS/geopackage-crs-wkt/1.1

Internal reference number of this OGC® document: 21-057

Version: 1.1.0

Category: OGC® Implementation Standard

Editor: Jeff Yutzler

OGC GeoPackage WKT for Coordinate Reference Systems Extension

Copyright notice

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

Warning

This document is an OGC Member approved international standard. This document is available on a royalty free, non-discriminatory basis. Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

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.

i. Abstract

This document is a revision to the GeoPackage WKT for Coordinate Reference Systems Extension that previously was published as Annex F.10 of the GeoPackage Encoding Standard 1.3.0 (OGC 12-128r17). This document replaces Annex F.10. The extension defines how to encode coordinate reference systems (CRS) in GeoPackages using the ISO/OGC Well-known text representation of coordinate reference systems [2019] (CRS WKT2) Standard. Specifically, this revision adds coordinate epochs to the encoding of coordinate reference systems in a GeoPackage.

ii. Keywords

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

ogcdoc, OGC document, geopackage, crs, srs, wkt, crs_wkt, crs_wkt2

iii. Preface

Version 1 of the OGC GeoPackage Encoding Standard was adopted prior to the adoption of "12-063r5 OGC Well known text representation of Coordinate Reference Systems" [2014] (so-called WKT2). As a result, the OGC GeoPackage Encoding Standard references an older CRS WKT document (OpenGIS® 01-009 Implementation Specification: Coordinate Transformation Services Revision 1.0, so-called WKT1), which has known ambiguities that are being encountered by the implementation community. The CRS extension establishes a new column in the gpkg_spatial_ref_sys table to contain values that conform to the WKT2 Standard. In 2019, OGC adopted "18-010r7 OGC Well known text representation of Coordinate Reference Systems" as a revision to 12-063r5. The core (unextended) GeoPackage Encoding Standard supports the older CRS WKT [12-063r5] standard (WKT1). This extension enables both the WKT1 and WKT2 encodings to be used. However, use of the newer WKT2 encoding is strongly encouraged. GeoPackage clients are expected to use the newer encoding if both encodings are present.

In a dynamic CRS, coordinates of a point on the surface of the Earth may change with time. To be unambiguous, the coordinates must always be qualified with the epoch at which they are valid (the coordinate epoch is not necessarily the epoch at which the observation was collected). In 2021, the GeoPackage SWG added coordinate epochs to gpkg_spatial_ref_sys. As this was the only substantive change to the GeoPackage Encoding Standard being considered at the time, the decision was made to split this extension into a separate document so that it could be considered separately.

iv. Security Considerations

No security considerations are provided for this Standard.

v. Submitting organizations

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

Image Matters
Spatialys

vi. Submitters

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

Name

Affiliation

Jeff Yutzler

Image Matters LLC

Even Rouault

Spatialys

1. Scope

This GeoPackage extension applies to the gpkg_spatial_ref_sys table and modifies the existing requirement specified in Requirement 10.

2. Conformance

This OGC GeoPackage WKT for Coordinate Reference Systems Extension defines requirements for encoding coordinate reference systems and coordinate epochs in a GeoPackage.

Conformance with this standard shall be checked using all the relevant tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site^[1].

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.

OGC: OGC 12-128r17 OGC GeoPackage Encoding Standard 1.3.0, http://www.geopackage.org/spec130/ (2020)

OGC: OGC 19-005r4 OGC Abstract Specification Topic 2: Referencing by coordinates, https://docs.opengeospatial.org/as/18-005r4/18-005r4.html (2019)

OGC: OGC 18-010r7 Geographic information — Well-known text representation of coordinate reference systems 2.0.6, https://docs.opengeospatial.org/is/18-010r7/18-010r7.html (2019)

4. Terms and Definitions

This document used the terms defined in OGC Policy Directive 49, 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 and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

For the purposes of this document, the following additional terms and definitions apply.

coordinate epoch: A property of coordinates referenced to a dynamic coordinate reference system indicating the date at which the coordinates are valid. (SOURCE: OGC 18-005r4)
Coordinate Reference System (CRS): A coordinate reference system is a set of mathematical rules for specifying how coordinates are to be assigned to a point that is related to an object by a datum. (SOURCE: ISO 19111:2019)

Note

The GeoPackage Encoding Standard (GES) uses the term "spatial reference system (SRS)," though technically an SRS is a spatial reference either by coordinates (CRS) or by geographic identifier (e.g., post code / zip code or street address). In the GES, a spatial reference system is realized through a row in the gpkg_spatial_ref_sys table.

well-known text (WKT): A compact machine- and human-readable representation of geometric objects that may also be used for succinctly describing the critical elements of CRS definitions. (SOURCE: OGC 18-010r7)

Note	CRS WKT2 specifically refers to a document conforming to the latest revision of OGC 18-010.

5. Conventions

This section provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML schema, or special notes regarding how to read the document.

5.1. Identifiers

The normative provisions in this Standard are denoted by the URI

http://www.opengis.net/spec/{standard}/{m.n}

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

6. WKT for Coordinate Reference Systems Extension (Informative)

Following is the information required by the GeoPackage Extension Template.

6.1. Extension Author

GeoPackage SWG, author_name gpkg.

6.2. Extension Name or Template

gpkg_crs_wkt

6.3. Extension Type

Extension of Existing Requirement 10.

6.4. Applicability

Applies to the gpkg_spatial_ref_sys table.

6.5. Scope

Read-write

7. Requirements (Normative)

7.1. Table Definition

7.1.1. gpkg_spatial_ref_sys

Requirement 115

For GeoPackages conforming to this extension, the gpkg_spatial_ref_sys table SHALL have additional columns called definition_12_063 and epoch as per Table 1 and gpkg_spatial_ref_sys Table Definition SQL (CRS WKT Extension).

Table 1. Spatial Ref Sys Table Definition
Column Name	Column Type	Column Description	NOT NULL flag	Key
`srs_name`	TEXT	Human readable name of this SRS	true
`srs_id`	INTEGER	Unique identifier for each Spatial Reference System within a GeoPackage	true	PK
`organization`	TEXT	Case-insensitive name of the defining organization e.g. EPSG or epsg	true
`organization_coordsys_id`	INTEGER	Numeric ID of the Spatial Reference System assigned by the organization	true
`definition`	TEXT	Well-known Text [I32] Representation of the Spatial Reference System	true
`description`	TEXT	Human readable description of this SRS	false
`definition_12_063`	TEXT	Well-known Text [I34] or [I36] Representation of the Spatial Reference System	true
`epoch`	DOUBLE	Coordinate epoch as per https://docs.opengeospatial.org/as/18-005r4/18-005r4.html#68	false

Note	Previous versions of this extension specified default values for `definition` and `definition_12_063`. Those defaults have been removed for interoperability reasons but implementers should be aware that some GeoPackages may have these defaults in place.

7.2. Table Data Values

7.2.1. gpkg_extensions

Requirement 145

GeoPackages with a row in the gpkg_extensions table with an extension_name of "gpkg_crs_wkt" SHALL comply with the extension defined in this Standard. GeoPackages complying with this extension SHALL have a row in the gpkg_extensions table as described in Table 2 (below).

Warning

Requirement 145 has been updated as part of GeoPackage 1.2.1. In 1.1.0 and 1.2.0, the table_name and column_name column values of the required gpkg_extensions row were inadvertently left unspecified. While the executable test suite running on an older GeoPackage version will not generate a failure due to missing gpkg_extensions column values, implementers are encouraged to update these values to comply with the updated requirement on older versions as well.

Table 2. Extension Table Records
table_name	column_name	extension_name	definition	scope
`gpkg_spatial_ref_sys`	`definition_12_063`	`gpkg_crs_wkt`	see note below	`read-write`
`gpkg_spatial_ref_sys`	`definition_12_063`	`gpkg_crs_wkt_1_1`	see note below	`read-write`
`gpkg_spatial_ref_sys`	`epoch`	`gpkg_crs_wkt_1_1`	see note below	`read-write`

Note

For the definition column, use a hyperlink that describes the current implementation of this extension. While a URL such as http://www.geopackage.org/spec/#extension_crs_wkt is acceptable, permalinks to specific versions are provided upon publication using the URL pattern http://www.geopackage.org/specMmP/#extension_crs_wkt where M is the major version, m is the minor version, and P is the patch. For example http://www.geopackage.org/spec121/#extension_crs_wkt is the permalink for this extension for GeoPackage 1.2.1.

7.2.2. gpkg_spatial_ref_sys

Requirement 116

Values of the definition_12_063 column SHALL be constructed per the WKT syntax as defined in [I34] and [I36].

Note	For backwards compatibility, only use WKT values that are common to both 12-063 and 18-010. Additional WKT values specified in 18-010r7 can be used when required in the CRS definition.

Requirement 117

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.

Note

If, for a particular row, both the definition and definition_12_063 columns are populated, the value in the definition_12_063 column takes priority.
The coordinate epoch SHOULD be provided if available. As such, a GeoPackage could have multiple SRSs with the same organization and organization_coordsys_id but with different epochs. While the epoch should theoretically go in the dataset metadata (per ISO 19111 / OGC Topic 2 as approved by the OGC in March 2021), there is not currently a standard metadata profile that would be suitable.

Annex A: Conformance Class Abstract Test Suite (Normative)

A.1. 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 /base/core/gpkg_spatial_ref_sys/data/table_def.

Test Method

PRAGMA table_info('gpkg_spatial_ref_sys')
Fail if returns an empty result set
Fail if result set does not include a column named 'definition_12_063' or if the column is not of type 'TEXT', notnull 1, and dflt_value 'undefined'.
Fail if result set does not include a column named 'epoch' or if the column is not of type 'DOUBLE' and notnull 0.
Pass if no failures.

Reference

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 rows.

Test Method

SELECT table_name, column_name, scope FROM gpkg_extensions WHERE extension_name = 'gpkg_crs_wkt';
Not testable if returns an empty result set
Fail if there is not exactly one row
Fail if scope is not "read-write"
Fail if column_name is not "definition_12_063"
Fail if table_name is not "gpkg_spatial_ref_sys"
Pass if no fails

Reference

Req 145

Test Type:

Capabilities

Test Case ID

/extensions/crs_wkt/extensions/data_values_1_1

Test Purpose

Verify that the gpkg_extensions table has the required rows for the revised extension.

Test Method

SELECT table_name, column_name, scope FROM gpkg_extensions WHERE extension_name = 'gpkg_crs_wkt_1_1';
Not testable if returns an empty result set
Fail if there is not exactly two rows
Fail if scope for both rows is not "read-write"
Fail if column_name is not "definition_12_063" or "epoch"
Fail if table_name for both rows is not "gpkg_spatial_ref_sys"
Pass if no fails

Reference

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 /base/core/gpkg_spatial_ref_sys/data_values_default.

Test Method

SELECT organization, organization_coordsys_id, definition, definition_12_063 FROM gpkg_spatial_ref_sys WHERE srs_id = -1
1. Confirm that this returns "NONE" -1 "undefined" "undefined"
SELECT srs_id, organization, organization_coordsys_id, definition, definition_12_063 FROM gpkg_spatial_ref_sys WHERE srs_id = 0
1. Confirm that this returns "NONE" 0 "undefined" "undefined"
SELECT definition FROM gpkg_spatial_ref_sys WHERE organization IN ("epsg","EPSG") AND organization_coordsys_id 4326
1. Confirm that this is a valid CRS
SELECT definition_12_063 FROM gpkg_spatial_ref_sys WHERE organization IN ("epsg","EPSG") AND organization_coordsys_id 4326
1. Confirm that this is a valid 12-063/18-010 CRS
Pass if tests 1-4 are met
Fail otherwise

Reference

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 /base/core/gpkg_spatial_ref_sys/data_values_required.

Test Method

SELECT definition, definition_12_063 FROM gpkg_spatial_ref_sys WHERE srs_id NOT IN (0, -1)
For each result
1. Fail if both definition values are 'undefined'
Pass if no failures

Reference

Req 117

Test Type

Capability

Annex B: Table Definition SQL (Normative)

B.1. gpkg_spatial_ref_sys

gpkg_spatial_ref_sys Table Definition SQL (CRS WKT Extension)

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,
  epoch DOUBLE
);

Annex C: Revision History

Date	Release	Editor	Primary clauses modified	Description
2021-08-20	0.1	J. Yutzler	all	initial version
2022-04-15	0.90	R. Lott	preface, 4, 7	input from open comment period
2022-05-10	0.91	C. Reed	multiple	input from open comment period
2022-05-23	0.92	A. Youmans	4	clarification
2022-06-06	0.93	J. Yutzler	all	final cleanup