The GeoAPI Implementation Standard defines application programming interfaces (API) in some programming languages (currently Java and Python) for geospatial applications. The API includes a set of types and methods which can be used for the manipulation of geographic information structured following the specifications adopted by the Technical Committee 211 of the International Organization for Standardization (ISO) and by the Open Geospatial Consortium (OGC). Those interfaces standardize the informatics contract between the client code, which manipulates normalized data structures of geographic information based on the published API, and the library code able both to instantiate and operate on these data structures according to the rules required by the published API and by the ISO and OGC standards.
This standard is a realization of OGC/ISO abstract specifications: it defines a language specific layers of normalization. By comparison, the Geographic Markup Language (GML) is another realization of the same abstract specifications (ignoring version numbers) but targeting a different language (XML). GeoAPI documents the mapping of types and methods from the abstract model into Java and Python programming languages, providing standard interfaces in the "org.opengis" (Java) or "opengis" (Python) namespaces and explaining the use of GeoAPI interfaces.
The following are keywords to be used by search engines and document catalogues.
ogcdoc, OGC document, GeoAPI, programming, Java, Python, interface, geospatial, metadata, referencing, feature
There is various libraries for helping developers to process geospatial data from programming languages like Java and Python. But the proliferation of API variations degrade interoperability. Since each library defines its own Application Programming Interface (API), the choice of a particular library result in a vendor lock-in situation even with open-source softwares. For example, it is difficult for a Web Map Service (WMS) implementation to replace its map projection engine if all available engines use incompatible APIs. Standard API in programmatic language can reduce such vendor lock-in by providing a layer which separates client code, which call the API, from library code, which implements the API. This follows a similar pattern to the well known JDBC (in Java language) or ODBC (in C/C++ language) API which provides standardized interfaces to databases. Clients can use those APIs without concern for the particular implementation which they will use.
GeoAPI interfaces are derived from OGC/ISO conceptual models described by Unified Modeling Language (UML) diagrams. The XML schemas are generally not used (except when there is no UML diagrams describing the model) because they carry XML-specific constraints that do not apply to programming languages. For example, querying the coordinate system associated to a Coordinate Reference System (CRS) is a single method call in GeoAPI. But this single operation would have required more than 50 lines of code if the API was generated from Geographic Markup Language (GML) schema instead of from the UML diagrams of abstract models.
The interfaces described in this standard follow closely, without introducing new concepts, from the previously published standards of the Open Geospatial Consortium (OGC) and the International Organization for Standardization (ISO). Nonetheless, 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. Security considerations
No security considerations have been made for this Standard.
V. Submitting Organizations
The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
All questions regarding this submission should be directed to the editor or the submitters:
GeoAPI contains a series of interfaces and classes in several packages which interpret into some programming languages (currently Java and Python) the data model and UML types of the ISO and OGC standards documents. The interfaces includes documentation which complement the injunctions of the OGC/ISO specifications by explaining particularities of GeoAPI: interpretations made of the specifications where there was room for choice, constraints specific to each programming language, or standard patterns of behavior expected by the community of a programming language. This document explains GeoAPI interfaces and defines its use by library code implementing the API and by client code calling the API. Jointly with the interface definitions, this work aims to provide:
a carefully considered interpretation of the OGC specifications for Java and Python languages,
a base structure to facilitate the creation of software libraries which implement OGC standards,
a well defined, full documented binding reducing the programming effort of using the OGC abstract model,
and to facilitate the portability of application code between different implementations.
The interfaces defined in this standard provide one way to structure the use of the Java and Python languages to implement softwares which follow the design and intents of the OGC/ISO specifications. The creators of the GeoAPI interfaces consider this approach as an effective compromise between the OGC specifications, the requirements of above-cited programming languages, and the tradition of the core libraries of those languages.
Version 3.1 and 4.0 of GeoAPI covers the base of the OGC/ISO Abstract Model for geographic information. GeoAPI provides utilities, base types, metadata structures, geo-referencing, a feature model and filters. The geo-referencing data elements enable the creation of reference systems for spatiotemporal coordinates and mathematical operators to convert coordinates from one coordinate reference system to another. This version of the standard covers the specifications ISO 19103, ISO 19115, ISO 19111 (completed by some elements from the closely related OGC™ specification OGC 01-009), ISO 19109, ISO 19143 and four elements from ISO 19107 necessary to the implementation of ISO 19111. Future versions of this specification are expected to expand this set of interfaces to cover more models of the OGC Abstract Specification series, including notably geometry and coverage data structures.
This standard defines interfaces in Java and Python programming languages. The normative publication of the interfaces occurs in the ASCII or binary format specific to each target language. The interfaces are distributed in ZIP bundles along with the API documentation. An online version of the API documentation, which may contain fixes for errata discovered after publication of this specification, is available at the URLs listed below:
Table 1 — Distribution formats
|Interfaces:||Java Archive (JAR) binary||Python source files (.py)|
|Documentation:||Javadoc as HTML files||Sphinx generated pages as HTML files|
TODO: The snapshot elements in above URLs will be replaced by 3.1 and 4.0 after release.
Contrarily to other OGC/ISO standards, the UML diagrams in this specification are only informative. The reason is because those diagrams show only a small subset of all interfaces and properties provided by GeoAPI, and details such as naming conventions (Clause 7.1.1) differ in the materialization to Java and Python languages. The complete and normative UML diagrams are provided by the abstract specifications listed in Clause 3.
This specification defines several conformance classes for implementations covering different packages of the API or providing different levels of complexity in their implementations. GeoAPI provides a test suite through which to establish conformance of GeoAPI implementations. Requirements for 2 standardization target types are considered:
Libraries which provide software components for building geospatial applications.
Applications which use the above-cited software components.
The second target type (applications) leaves more freedom than the first target type (libraries). In particular, applications are free to delete any types, methods or functionalities that they do not use. Requirements for those two target types are given in Clause 8.
Conformance with this standard shall be checked using all the relevant tests specified in Annex A 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. In order to conform to this OGC® interface standard, a software implementation shall choose to implement:
3. Normative references
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
ISO: ISO 31-0:1992, Quantities and units — Part 0: General principles. International Organization for Standardization, Geneva (1992). https://www.iso.org/standard/3621.html.
ISO: ISO 1000:1992, SI units and recommendations for the use of their multiples and of certain other units. International Organization for Standardization, Geneva (1992). https://www.iso.org/standard/5448.html.
ISO: ISO 8601-1:2019, Date and time — Representations for information interchange — Part 1: Basic rules. International Organization for Standardization, Geneva (2019). https://www.iso.org/standard/70907.html.
ISO: ISO 19101-1:2014, Geographic information — Reference model — Part 1: Fundamentals. International Organization for Standardization, Geneva (2014). https://www.iso.org/standard/59164.html.
ISO: ISO 19101-2:2018, Geographic information — Reference model — Part 2: Imagery. International Organization for Standardization, Geneva (2018). https://www.iso.org/standard/69325.html.
ISO: ISO 19103:2015, Geographic information — Conceptual schema language. International Organization for Standardization, Geneva (2015). https://www.iso.org/standard/56734.html.
ISO: ISO 19107:2003, Geographic information — Spatial schema. International Organization for Standardization, Geneva (2003). https://www.iso.org/standard/26012.html.
ISO: ISO 19109:2015, Geographic information — Rules for application schema. International Organization for Standardization, Geneva (2015). https://www.iso.org/standard/59193.html.
ISO: ISO 19111:2019, Geographic information — Referencing by coordinates. International Organization for Standardization, Geneva (2019). https://www.iso.org/standard/74039.html.
ISO: ISO 19112:2019, Geographic information — Spatial referencing by geographic identifiers. International Organization for Standardization, Geneva (2019). https://www.iso.org/standard/70742.html.
ISO: ISO 19115-1:2014, Geographic information — Metadata — Part 1: Fundamentals. International Organization for Standardization, Geneva (2014). https://www.iso.org/standard/53798.html.
ISO: ISO 19115-1:2014/Amd 1:2018, Geographic information — Metadata — Part 1: Fundamentals. International Organization for Standardization, Geneva (2014). https://www.iso.org/standard/73118.html.
ISO: ISO 19115-1:2014/Amd 2:2020, Geographic information — Metadata — Part 1: Fundamentals. International Organization for Standardization, Geneva (2014). https://www.iso.org/standard/80275.html.
ISO: ISO 19115-2:2019, Geographic information — Metadata — Part 2: Extensions for acquisition and processing. International Organization for Standardization, Geneva (2019). https://www.iso.org/standard/67039.html.
ISO: ISO/TS 19115-3:2016, Geographic information — Metadata — Part 3: XML schema implementation for fundamental concepts. International Organization for Standardization, Geneva (2016). https://www.iso.org/standard/32579.html.
ISO: ISO 19123:2005, Geographic information — Schema for coverage geometry and functions. International Organization for Standardization, Geneva (2005). https://www.iso.org/standard/40121.html.
ISO: ISO 19141:2008, Geographic information — Schema for moving features. International Organization for Standardization, Geneva (2008). https://www.iso.org/standard/41445.html.
ISO: ISO 19143:2010, Geographic information — Filter encoding. International Organization for Standardization, Geneva (2010). https://www.iso.org/standard/42137.html.
ISO: ISO 19157:2013, Geographic information — Data quality. International Organization for Standardization, Geneva (2013). https://www.iso.org/standard/32575.html.
ISO: ISO 19162:2019, Geographic information — Well-known text representation of coordinate reference systems. International Organization for Standardization, Geneva (2019). https://www.iso.org/standard/76496.html.
Martin Daly: OGC 01-009, Coordinate Transformation Services — OLE/COM. Open Geospatial Consortium (2001). https://portal.ogc.org/files/?artifact_id=999.
Akinori Asahara, Ryosuke Shibasaki, Nobuhiro Ishimaru, David Burggraf: OGC 18-075, OGC® Moving Features Encoding Part I: XML Core. Open Geospatial Consortium (2019). https://docs.ogc.org/is/18-075/18-075.html.
Kyoung-Sook KIM, Nobuhiro ISHIMARU: OGC 19-045r3, OGC Moving Features Encoding Extension — JSON. Open Geospatial Consortium (2020). https://docs.ogc.org/is/19-045r3/19-045r3.html.
Arliss Whiteside Jim Greenwood: OGC 06-121r9, OGC Web Service Common Implementation Specification. Open Geospatial Consortium (2010). https://portal.ogc.org/files/?artifact_id=38867.
JSR 385: Units of Measurement API 2.0
James Gosling, Bill Joy, Guy Steele, Gilad Bracha: The Java Language Specification
Python Software Foundation: The Python Language Reference
4. Terms and definitions
This document uses 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 document 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.
4.1. application programming interface (API)
a formally defined set of types and methods which establish a contract between client code which uses the API and implementation code which provides the API
number of elements in a set
Note 1 to entry: Contrast with multiplicity, which is the range of possible cardinalities a set can hold.
4.3. conceptual model
model that defines concepts of a universe of discourse
UML condition or restriction expressed in natural language text or in a machine readable language for the purpose of declaring some of the semantics of an element
one of a sequence of numbers designating the position of a point
Note 1 to entry: In a spatial coordinate reference system, the coordinate numbers are qualified by units.
4.6. coordinate operation
process using a mathematical model, based on a one-to-one relationship, that changes coordinates in a source coordinate reference system to coordinates in a target coordinate reference system, or that changes coordinates at a source coordinate epoch to coordinates at a target coordinate epoch within the same coordinate reference system
4.7. coordinate reference system
coordinate system that is related to an object by a datum
Note 1 to entry: Geodetic and vertical datums are referred to as reference frames.
Note 2 to entry: For geodetic and vertical reference frames, the object will be the Earth. In planetary applications, geodetic and vertical reference frames may be applied to other celestial bodies.
4.8. covariant type
a type that can be replaced by a more specialized type when the property is overridden in a subclass
Note 1 to entry: Some programming languages allow covariant return types in method declarations.
feature that acts as a function to return values from its range for any direct position within its spatial, temporal, or spatiotemporal domain
identifiable collection of data
specification of a value domain with operations allowed on values in this domain
Note 1 to entry: Data types include primitive predefined types and user definable types.
Integer, Real, Boolean, String and Date.
4.12. dynamic attribute
characteristic of a feature in which its value taken from the domain of the feature attribute type varies with time
abstraction of a real world phenomena
Note 1 to entry: A feature can occur as a type or an instance. Feature type or feature instance should be used when only one is meant.
4.14. feature attribute
characteristic of a feature
Note 1 to entry: A feature attribute can occur as a type or an instance. Feature attribute type or feature attribute instance is used when only one is meant.
4.15. feature operation
operation that every instance of a feature type may perform
rule that associates each element from a domain (source, or domain of the function) to a unique element in another domain (target, co-domain, or range)
4.17. geographic feature
representation of real world phenomenon associated with a location relative to the Earth
4.18. geometric object
spatial object representing a geometric set
UML classifier that represents a declaration of a set of coherent public UML features and obligations
Note 1 to entry: An interface specifies a contract; any classifier that realizes the interface must fulfil that contract. The obligations that can be associated with an interface are in the form of various kinds of constraints (such as pre- and post-conditions) or protocol specifications, which can impose ordering restrictions on interactions through the interface.
trademark of Oracle used to refer to an object oriented, single inheritance programming language whose syntax derives from the C programming language and which is defined by the Java Language Specification
4.21. literal value
constant, explicitly specified value
Note 1 to entry: This contrasts with a value that is determined by resolving a chain of substitution (e.g. a variable).
data about data
4.23. moving feature
feature whose location changes over time
Note 1 to entry: Its base representation uses a local origin and local coordinate vectors of a geometric object at a given reference time.
Note 2 to entry: The local origin and ordinate vectors establish an engineering coordinate reference system (ISO 19111), also called a local frame or a local Euclidean coordinate system.
UML specification of the range of allowable cardinalities that a set may assume
Note 1 to entry: Contrast with cardinality, which is the number of elements in a set.
UML general purpose mechanism for organizing elements into groups
facet or attribute of an object referenced by a name
an interpreted high-level programming language for general-purpose programming
specialized abstraction relationship between two sets of model elements, one representing a specification (the supplier) and the other representing an implementation of the latter (the client)
Note 1 to entry: Realization indicates inheritance of behaviour without inheritance of structure.
Note 2 to entry: GeoAPI and GML are two realizations of OGC/ISO abstract specifications.
path of a moving point described by a one parameter set of points
This section provides details for conventions used in the document. All examples in this document are informative only.
6.1. UML notation
Unified Modeling Language (UML) static structure diagrams appearing in this document are used as described in Subclause 5.2 of OGC Web Services Common OGC 06-121r9.
6.2. Type terminology
The meaning of type, class, interface, property and attribute can vary depending on the programming language. This document follows the UML 2 definition of interface as a declaration of a set of coherent public operations, properties and obligations specifying a contract. UML interfaces are represented in programming languages by Java interfaces and Python abstract classes. The word class is generally not used in this document except in discussions specific to a programming language, in which case the word takes the meaning defined by the target language; in Java this is often (but not only) an implementation of an interface.
The word type is used as a generic term for interface, class (whatever it is in target programming languages), code list, enumeration or the description of a feature. Note that code lists, enumerations and feature types are not interfaces.
The word property (not attribute) is used for values or associations defined by an interface. This document reserves the word attribute for feature attributes or XML attributes.
The meaning of implementation depends on the context. From the perspective of OGC/ISO abstract specifications, Java interfaces or Python abstract classes are implementations of the abstract models, in the same way than XML Schema Definitions (XSD) are other implementations of the same abstract models. But from the perspective of programming languages, interfaces are not implementations; instead the word “implementation” is used for concrete classes. In this document, the types provided by GeoAPI are said to be an implementation of abstract models, while the concrete classes provided by vendors are said to be an implementations of GeoAPI.
6.3. Abbreviated terms
The following symbols and abbreviated terms are used in this specification:
Application Program Interface
Coordinate Reference System
Geographic Markup Language
International Organization for Standardization
Java Database Connectivity
Java Naming and Directory Interface
Open Database Connectivity
Open Geospatial Consortium
Unified Modeling Language
Uniform Resource Identifiers
Coordinated Universal Time
Well Known Text
Web Map Service
Extensible Markup Language
XML Schema Definition
The normative provisions in this specification are denoted by the URI:
All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.
6.4.1. Package namespaces
This specification uses "opengis" in the text for denoting a package or module in OGC namespace, but the fully qualified name depends on the programming language. For example, the metadata package is spelled "org.opengis.metadata" in Java but only "opengis.metadata" (without "org" prefix) in Python. Except in language-specific notes, this specification uses the shorter form in the text and lets readers adapt to their programming language of interest.
7. Geospatial API overview
The GeoAPI interfaces formalizes the handling of types defined in OGC/ISO abstract specifications. Whereas the specifications define types, operations and relationships using the general UML notation, the GeoAPI types implement those standards as programming language interfaces or simple classes. The structure of the GeoAPI library mirrors the packaging and separation of the different ISO and OGC specifications by grouping different types and functionality in separated Java and Python language packages.
Figure 1 — OGC/ISO specifications and GeoAPI packages mapping
The opengis.annotation package provides the annotation system used to document the origin and obligation level of all methods and types in GeoAPI. These annotations are available through introspection at runtime for any code which wishes to exploit this information. The opengis.util package provides some basic types shared by two or more standards. Most of them are derived from ISO 19103:2015. The packages in the opengis.metadata namespace cover the types defined in the ISO 19115-1:2014 and ISO 19115-2:2019Metadata specifications, which are data structures describing other data. They are completed by ISO 19157:2013Data quality for the quality sub-package. The packages in the opengis.parameter and opengis.referencing namespaces implement the types from the ISO 19111:2019Referencing by Coordinates specification complemented by the mathematical operator types from the OGC 01-009Coordinate Transformation Services implementation specification. The packages in the opengis.geometry namespace cover the types defined in the ISO 19107:2003Spatial Schema specification, although version 4.0 of the library only defines the elements from that specification needed by the geo-referencing types. The opengis.feature package covers the meta-classes defined in the ISO 19109:2015Rules for application schema specification, completed by the dynamic attributes defined in OGC 18-075Moving Features specification. The feature package is not needed for dynamic languages like Python. The opengis.filter package covers the types defined in ISO 19143:2010Filter encoding specification.
7.1. General mapping rules
This section gives high-level guidance in the mapping from UML to Java and Python API applying to all GeoAPI types. Other sections after this one will focus on specific type subsets (metadata, referencing, etc). Those guidance are not strict rules; departures exist on a case-by-case basis when the semantic justify them.
7.1.1. Naming conventions
The interface and property names defined in OGC/ISO standards may be modified for compliance with the conventions in use in target programming languages. The main changes are described below:
The two-letter prefixes are dropped. For example, "MD_Metadata" and "CI_Citation" interfaces are named "Metadata" and "Citation" in Java and Python. The camel cases convention (for example "CoordinateSystemAxis") is kept unchanged for interfaces.
220.127.116.11. Code lists and enumerations
The two-letter prefixes are dropped in the same way than for interfaces. Then if the type name ends with the "Code" suffix, that suffix is dropped too in strongly-typed languages like Java. For example, the ISO 19115 "MD_TopicCategoryCode" code list is named "TopicCategory" in Java classes. But the "Code" suffix drop is not applied to more dynamic languages like Python, because the naming convention can be a compensation for the absence of compile-time type checks.
The name adaptations depend on the target programming language and on the multiplicity. In Java, accessor methods start with the "get" prefix and are followed by their property name in camel cases. But in Python, no prefix is added and the camel cases convention is replaced by the snake cases convention (see the "coordinateSystem" example below). If a property allows more than one value, then the plural form of its noun may be used. The plural form hints the developers that they may need to use indexes or iterators for accessing elements.
Table 2 — Example of name adaptations in programming elements
|Metatype||Name in OGC/ISO||Name in Java||Name in Python|
7.1.2. Multiplicity conventions
The UML diagrams may specify arbitrary multiplicities (minimum and maximum number of occurrences) for each property. But GeoAPI recognizes only the following four multiplicities, materialized in the API as annotations (Clause 7.1.3) and in the method signatures. If a different multiplicity is needed, then [0 … ∞] should be used with a restriction documented in the text attached to the property.
[0 … 0] — the property cannot be set (this happen sometimes in subtypes).
[0 … 1] — the property is optional or conditional.
[1 … 1] — the property is mandatory.
[0 … ∞] — the property can appear an arbitrary number of times, including zero or one.
Some programming languages have an Optional construct for differentiating the [0 … 1] and [1 … 1] cases. This construct is used where appropriate, but shall be considered only as a hint. It may appear in a mandatory property if that property was optional in the parent interface. Conversely, absence of Optional construct is not a guarantee that the value will never be null. Some properties fall in gray area, where they are usually not null but may be null in some rare situations. For example, the ellipsoid property of a Geodetic Reference Frame is mandatory when used in the context of geographic or projected coordinate reference systems, which are by far the most common cases. Even when used in other contexts, the ellipsoid is optional but still recommended. Consequently, GeoAPI does not use the Optional construct for the ellipsoid property in order to keep the most common usages simpler, but robust applications should be prepared to handle a null value. Developers should refer to the API documentation for the policy on null values.
When the multiplicity is [0 … ∞], the property type is a collection such as a list. In such case an absent property is represented by an empty collection, not a null value. When the multiplicity is [1 … ∞] the collection shall never be empty, but there is no language construct in Java and Python for enforcing that requirement.
7.1.3. Annotated API
The opengis.annotation package allows GeoAPI to document the UML elements from the various specification documents used for defining the Java and Python constructs. Those annotations encode the source document, stereotype, original name, and obligation level of the various types, properties and operations published by GeoAPI. The source document may be completed by a version number when the GeoAPI construct is based on a different edition of a normative document than the dated references listed in Clause 3. GeoAPI defines two annotations in the Java language (no annotation in Python): @UML which is applied on types and properties (fields or methods), and @Classifier which can be applied only on types. Those annotations are shown in the figure below:
Figure 2 — Annotations reflecting UML elements used by GeoAPI
An example in Annex D.1.1 shows how these annotations are applied in the Java language and how they are available at runtime by introspection.
18.104.22.168. Departures from ISO model
The GeoAPI Obligation is the ISO MD_ObligationCode enumeration moved into the annotation package for use with other UML-related types.
A forbidden enumeration value has been added for handling the cases where a property defined in a parent interface is inapplicable to a sub-interface ([0…0] multiplicity in abstract models).
The GeoAPI Stereotype enumeration is a copy of the ISO MD_DatatypeCode code list retaining only the values relevant to annotation of GeoAPI programming elements. This duplication exists because the ISO 19115 standard defines a code list, while Java annotations require enumerations.
7.1.4. Derived methods
GeoAPI may define additional methods not explicitly specified in OGC/ISO abstract models, when the values returned by those methods can be derived from the values provided by standard OGC/ISO properties. Those extensions are enabled by the way properties are handled. In OGC/ISO abstract models each property could have its value stored verbatim, for example as a column in a database table, an XML element in a file or a field in a class. For enabling efficient use of OGS/ISO models in relational databases or XML files, those models are generally non-redundant: each value is stored in exactly one property. By contrast in GeoAPI all properties are getter methods: no matter how implementations store property values, users can fetch them only through method calls. Since methods are free to compute values from other properties, GeoAPI uses this capability for making some information more easily accessible in situations where property values can be reached only indirectly in OGC/ISO models. Those additional methods introduce apparent duplications, but they should be thought as links to the real properties rather than copies of the property values. Those methods are added sparsely, in places where introducing them brings some harmonization by reducing the needs to perform special cases. Examples include fetching the head of an arbitrary GenericName, fetching the Geodetic Reference Frame indirectly associated to a ProjectedCRS, fetching axes of an arbitrary Coordinate Reference System (including compound ones), and more. Those additional methods can be recognized by the absence of @UML annotation.
7.2. Core data types mapping
The ISO 19103 specification (Geographic Information – Conceptual schema language) defines types which are used as building blocks by the other standards in the 19100 series. ISO 19103:2015 defines Primitive types (§7.2 of that standard), Collection types (§7.3), Enumerated types (§7.4), Name types (§7.5), Record types (§7.7) and Unit of Measure types (§C.4). GeoAPI maps these types either to existing types from the Java and Python standard libraries or, when needed, to types defined in the opengis.util package. That utility package is used by GeoAPI for types defined in the ISO 19103 specification for which no equivalence is already present in the Java and Python standard libraries.
For various practical reasons the mapping from ISO types to programming language types is not a one-to-one relationship. The mapping actually used is explained below. Furthermore, not all of the types in ISO 19103 have a mapping defined because the need for these types has not yet appeared, since they have not yet appeared in any other specification for which GeoAPI defines interfaces. Such types are listed as “unimplemented” in the tables below.
7.2.1. Primitive types
From ISO 19103:2015 §7.2.1 and 7.2.5 to 7.2.11
Each primitive type of the OGC/ISO specifications maps to zero, one or two object structures in GeoAPI. Where the mapping can be made directly to a programming language primitive type, such as int and float, the language primitive is preferred. In languages where “primitives” and “wrappers” are distinct, wrappers may be used instead of primitives on a case-by-case basis. The following table shows the mapping used by GeoAPI to represent the primitive types in the ISO 19100 series.
Table 3 — Primitive types mapping
|ISO 19103 interface||Java type||Python type|
|Number||java.lang.Number||int or float|
(1) Wrapper types such as java.lang.Integer or java.util.OptionalInt may be used where appropriate.
(2) Sometimes substituted by long or java.lang.Long where the value may exceed 2³².
(3) Decimal differs from Real, as Decimal is exact in base 10 while Real may not.
(4) Substituted by org.opengis.util.InternationalString where the string representation depends on the locale.
7.2.2. Date and time
From ISO 19103:2015 §7.2.2 to 7.2.4
The ISO 19103 Date interface gives values for year, month and day while the Time interface gives values for hour, minute and second. DateTime is the combination of a date with a time, with or without timezone. GeoAPI maps the ISO date and time interfaces to the types provided in the standard library of target languages. In some cases like Java, this mapping forces GeoAPI to choose whether the time component shall include timezone information or not since the choices are represented by different types (e.g. LocalDateTime, OffsetDateTime and ZonedDateTime). The timezone information is often desired for geospatial data (for example in the acquisition time of a remote sensing image), but may be undesired for some other cases like office opening hours. In the latter case, the decision to include timezone or not depends if the opening hours apply to one specific office or to all offices spanning the multiple timezones of a country. GeoAPI generally includes timezone information, but this policy may be adjusted on a case-by-case basis.
Table 4 — Date and time types mapping
|ISO 19103 interface||Java class||Python type|
(1) Some properties defined in GeoAPI 3.x use the legacy java.util.Date class for historical reasons.
DateTime is distinct from Instant. The former is expressed in the proleptic Gregorian calendar as described in ISO 8601-1:2019, while the latter is an instantaneous point on the selected time scale, astronomical or atomic. An Instant does not have year, month or day components. It is instead a duration elapsed since an epoch, and its conversion to a DateTime may be complicated. In GeoAPI, temporal objects in metadata are typically DateTime while coordinates in a temporal coordinate reference system are typically Instant.
From ISO 19103:2015 §7.3
GeoAPI implements ISO 19103 collection interfaces using the standard Collections Frameworks provided by Java and Python. A Set is a finite collection of objects where each object appears only once. A Bag is similar to a Set except that it may contain duplicated instances. The order of elements in a Set or a Bag is not specified. A Sequence is similar to a Bag except that elements are ordered.
Table 5 — Collections mapping
|ISO 19103 interface||Java type||Python type|
Unless otherwise required by the semantic of a property, GeoAPI preferably uses the Collection type in Java method signatures. This allows implementers to choose their preferred subtypes, usually Set or Sequence. The Set type is not the default type because enforcing element uniqueness may constraint implementations to use hash tables or similar algorithms, which is not always practical.
7.2.4. Controlled vocabulary
From ISO 19103:2015 §6.5
A controlled vocabulary is an established list of standardized terminology (names, words or phrases) with associated definitions for use to identify, describe, index or retrieve information. A controlled vocabulary implementation commonly found in many programming languages is enumeration.
GeoAPI distinguishes two different types of controlled vocabularies: enumerations are closed controlled vocabularies: it is not possible to add new members (except by releasing new GeoAPI versions). By contrast, code lists are open vocabularies: they provide a basic set of members defined at compile-time, but users are free to add new members at runtime. Many programming languages provide an enum construct for the closed case. For the opened case, GeoAPI defines the CodeList abstract class in Java.
Table 6 — Enumerated types mapping
|ISO 19103 type||Java type||Python type|
(1) GeoAPI does not yet provide an extensible implementation of code list in the Python language, but this limitation may be addressed in a future version.
Code lists can be extended by calls to valueOf(String) methods in the Java language. Extensions should follow ISO 19103 recommendation: Extensions of a code list use the existing code list values and merely add additional unique values. These additional values should not replace an existing code by changing the name or definition, or have the same definition as an existing value.
The figure below shows one closed (on the left side) and one opened (on the right side) enumeration derived from ISO 19115. The ControlledVocabulary parent interface is a GeoAPI addition. Its indirect inheritance by PixelOrientation is because the Enum class is defined by programming language standard library and cannot be modified directly. An example in Annex D.1.2 shows how code lists are used in the Java language.
Figure 3 — Closed and opened enumeration examples
22.214.171.124. Departures from ISO model
Code lists and enumerations in GeoAPI differ from the OGC/ISO standards as described in the following sub-sections.
GeoAPI introduces a ControlledVocabulary interface as the parent type of enumerations and code lists. It provides methods for accessing properties common to both enumerated types: the name used in the target programming language (e.g. "UPPER_LEFT"), the identifier used in OGC/ISO specification (e.g. "upperLeft"), and its position (ordinal) in the enumeration. Note that the ordinal values may change in any future specification if new enumeration values are added, but this is not necessarily a problem because not all algorithms need stable values (e.g. hash tables).
In some specifications (for example ISO 19115), code list and enumeration names end with the "Code" suffix. Some other specifications (for example ISO 19111) do not use any particular suffix. The mapping to programmatic API may uniformize those type names to a single convention, depending on the target language. For the Java API, "Code" suffixes are omitted in class names. But for the Python API, class names are left unchanged. See naming conventions in Clause 7.1.1 for examples in both languages.
7.2.5. Name types
From ISO 19103:2015 §7.5
A GenericName is a sequence of identifiers rooted within the context of a namespace. NameSpace defines a domain in which names can be mapped to objects. For example, names could be primary keys in a database table, in which case the namespace is materialized by the table. Each storage (XML, shapefiles, netCDF, …) may have their own constraints for names in their namespaces.
Figure 4 — Generic names derived from ISO 19103
GenericName is the base interface for all names in a NameSpace. A generic name can be either a LocalName, or a ScopedName which is an aggregate of a LocalName (the head) for locating another NameSpace and a GenericName (the tail) valid in that name space. For example if "urn:ogc:def:crs:EPSG:10:4326" is a ScopedName, then "urn" is the head and "ogc:def:crs:EPSG:10:4326" is the tail. GeoAPI extends the model by allowing navigation in the opposite direction, with "urn:ogc:def:crs:EPSG:10" as the path and "4326" as the tip.
Figure 5 — Components of a generic name
TypeName and MemberName are subtypes of LocalName for referencing a type (for example a class) and a member (for example a property in a class) respectively. All those types are mapped to Java and Python classes as below:
Table 7 — Name types mapping
|ISO 19103 interface||Java interface||Python class|
126.96.36.199. Mapping to programming languages
Above names are valid values for TypeName, where urn:ogc:def:dataType:OGC:1.1 is the scope of the LocalName. In addition, GeoAPI defines also the following type names using only OGC as the scope. The general rule is to use the name used in UML diagrams of OGC/ISO standards.
Table 8 — Standard type names and mapping to programming languages
|Scoped type name||Java class||Python class|
188.8.131.52. Departures from ISO model
Generic names in GeoAPI differ from the OGC/ISO standards as described in the following sub-sections.
GeoAPI extends the ISO 19103 model by adding a (path, tip) pair in complement to the (head, tail) pair. While the head and tip properties carry non-trivial information only inside ScopedName, GeoAPI nevertheless makes them available from the parent GenericName interface (not shown in Figure 4) with the restriction that they shall return this (Java) or self (Python) when the name is an instance of LocalName. This generalization makes common operations simpler without the need to check for the exact name interface.
The ISO 19103 GenericName.aName property appears as toString in Figure 4, but this property should be mapped to the standard mechanism for representing an arbitrary object as a character string in the target programming language. In Java this is the toString() method; in Python this is __str__ or __repr__. This specification uses the Java method name as it is more readable, but other languages should adapt. The aName and scopedName properties in sub-interfaces are replaced by inheritance of toString in above UML.
ISO 19103 defines mapping methods from a name to the object identified by that name: getObject() in GenericName and numerous methods in NameSpace. Those methods are not included in GeoAPI interfaces. Instead, we left these mappings to other frameworks, for example Java Naming and Directory Interface (JNDI). An example in Annex D.1.3 shows how some omitted methods can be implemented by JNDI in the Java language.
The NameFactory is an extension to allow the construction of instances of these name types (in GeoAPI, factories are realizations of constructors). The GenericName.toFullyQualifiedName() method is an addition for developer convenience. All GeoAPI additions on name types carry no new information compared to ISO model.
7.2.6. Record types
From ISO 19103:2015 §7.7
Records define new data type as an heterogeneous aggregation of component data types (the fields). A RecordType defines dynamically constructed data type. It is identified by a TypeName and contains an arbitrary number of fields as (name, type) pairs. A Record is an instance of RecordType containing the actual field values.
Figure 6 — Records derived and extended from ISO 19103
Record and RecordType are lookup mechanisms that associate field names to values and value types respectively. Field names are locally mapped, and field types are most often primitives. Because the RecordType describes the structure of a set of records, it is essentially a metaclass for that set of records viewed as a class. In dynamic languages such as Python, the Record and RecordType interfaces are not really needed because those languages can handle dynamically constructed data types natively, but they can nevertheless be useful as marker interfaces.
Table 9 — Record types mapping
|ISO 19103 interface||Java class or interface||Python class|
184.108.40.206. Departures from ISO model
Records in GeoAPI differ from the OGC/ISO standards as described in the following sub-sections.
The Type interface and typeName property were defined in the older ISO 19103:2005 standard and are kept by GeoAPI despite their removal from ISO 19103:2015. The isInstance(…) method is a GeoAPI extension.
The ISO 19103 Field and FieldType interfaces are omitted because the same functionality is achieved with Dictionary<MemberName, Type> and Dictionary<MemberName, Any> respectively. Dictionaries are realized by language-specific types such as java.util.Map (see collection types in Clause 7.2.3) which offer more flexibility. In particular dictionaries provide functionality equivalent to the ISO 19103:2005 locate(name : MemberName) method. That method was defined in older ISO standard but removed in ISO 19103:2015 revision. The use of dictionaries allows GeoAPI to keep the locate functionality despite the method removal.
7.2.7. Web types
From ISO 19103:2015 §C.3
ISO 19103 defines the following data types for use in World Wide Web environments. Those types are often found in XML documents. GeoAPI maps the ISO types to standard types of the target languages without introducing new interfaces.
Table 10 — Web types mapping
|ISO 19103 interface||Java class or interface||Python class|
220.127.116.11. Departures from ISO model
All ISO 19103 web types extend CharacterString. But it is not the case of equivalent objects provided by the standard Java library. Consequently, a character string cannot easily be substituted by an anchor, file name or URI in GeoAPI for Java.
From ISO 19103:2015 §C.2
The InternationalString interface is defined by GeoAPI to handle textual sequences which may potentially need to be translated for users of different locales. Conceptually this act as a CharacterString but may, depending on the implementation, provide access to locale specific representations of that string. GeoAPI InternationalString is closely related, but not identical, to ISO 19103 LanguageString. The main difference is that the latter is a character string in one specific language, while InternationalString can be a collection of character strings in different locales. This is useful, for example, when an implementation is operating on a server that serves multiple languages simultaneously, to allow sending string representations in the locale of the client rather than the locale of the server running the GeoAPI implementation.
Figure 7 — Cultural and linguistic adaptability
The toString() method (__str__ in Python) returns the text in a language at implementer’s choice. The toString(Locale) method tries to return the text in the specified language if available, and otherwise fallbacks on a language at implementer’s choice. This specification makes no recommendation about the default or fallback languages because some programming languages provide their own mechanism (e.g. using Language Range as defined by IETF RFC 4647). Consequently, GeoAPI delegates most internationalization types to the target language standard library, as shown in the following table. An example in [International__xad_String] shows the use of InternationalString in the Java language.
Table 11 — Linguistic types mapping
|ISO 19103 interface||Java class or interface||Python class|
(1) Sometimes substituted by CharSequence or InternationalString.
(2) Defined as a unit of measurement in ISO 19103 §C.4.24.
(3) From ISO 19103 §7.2.10 (primitive types).
18.104.22.168. Departures from ISO model
Internationalization in GeoAPI differs from the OGC/ISO standards as described in the following sub-sections.
All GeoAPI linguistic types have names and properties different than the ISO 19103 types. This is either because the ISO types are mapped to types provided by the target language standard library or because the GeoAPI type is inspired by a similar effort in the target language ecosystem.
InternationalString as defined by GeoAPI provides the same functionality than ISO 19115 PT_FreeText. It can be applied to all ISO 19115 elements who’s data type is CharacterString and domain is “free text”. Consequently, GeoAPI uses the single InternationalString interface for the two ISO types LanguageCode (from ISO 19103) and PT_FreeText (from ISO 19115).
7.2.9. Units of measurement
From ISO 19103:2015 §C.4
ISO 19103 represents measurements and their units by two base interfaces: Measure for the result from performing the act of ascertaining the value of a characteristic of some entity, and UnitOfMeasure as a quantity adopted as a standard of measurement for other quantities of the same kind. Those two base interfaces have a parallel set of subtypes. For example, Length as a Measure specialization for distances, accompanied by UomLength as an UnitOfMeasure specialization for length units. Likewise Area is accompanied with UomArea, Time is accompanied with UomTime, etc.
GeoAPI does not define any interface for the ISO 19103 Measure and UnitOfMeasure types because Java and Python already have their own library for units of measurement. For example, Java has standardized a set of quantity interfaces in the Java Specification Request JSR 385. When such language-specific standard exists and provides equivalent functionality to ISO 19103, that external standard is used. See Java profile (Annex B.1) or Java example code (Annex D.1.5) for more information.
7.3. Metadata packages
The GeoAPI metadata packages use the opengis.metadata namespace and implement the types defined in the ISO 19115-1:2014 – Metadata part 1: Fundamentals specification along with the modifications of ISO 19115-1:2014/Amd 1:2018 and ISO 19115-1:2014/Amd 2:2020. They are completed or merged with the types defined in ISO 19115-2:2019 – Metadata part 2: Extensions for acquisition and processing and ISO 19157:2013 — Data quality specifications.
The metadata packages of GeoAPI provide container types for descriptive elements which may be related to data sets or components. All of these data structures are essentially containers for strings, dates or numbers, and the interfaces consist almost exclusively of methods which provide read access to those types or a container. The API defines no methods which manipulate or modify the data structures. Implementers are free to provide a fully mutable implementation of GeoAPI interfaces, but users may need to cast to the implementation classes in order to modify a metadata.
There is almost 500 properties in more than 150 metadata interfaces. This specification does not describe them; see ISO 19115 together with GeoAPI Javadoc or Python-doc (Clause 2) for a description of each property. Implementers can support a subset of their choice. The following UML example shows a few frequently used interfaces with some of their properties. An example in Annex D.1.6 shows how to extract the individual name from a Citation in the Java language.
Figure 8 — Example of a few metadata interfaces with a subset of their properties
7.3.1. Package mapping
From ISO 19115-1:2014 §6.5.[2…14] and §6.6; ISO 19157:2013
The mapping of ISO packages to GeoAPI packages follows a parallel naming scheme, shown in the table below. Some minor packages (for example Portrayal catalogue which contains only one interface) have been aggregated into another package. All packages are defined by ISO 19115 except Data quality which is defined by ISO 19157 but considered by GeoAPI as metadata for historical reasons, and Reference system which has been retrofitted in the ISO 19111 interfaces from the referencing package.
Table 12 — Metadata package mapping
|ISO package||Java package||Python module|
|Citation and party||org.opengis.metadata.citation||opengis.metadata.citation|
7.3.2. Reference systems
Derived from ISO 19115-1:2014 §6.5.8
The way GeoAPI handles reference systems in metadata differs significantly from ISO 19115. Coordinate Reference Systems (CRS) are defined in details by the ISO 19111 standard. But the ISO 19115 metadata standards do not reference those CRS interfaces directly (except in one case), at the cost of some overlaps. By contrast GeoAPI does not enforce such separation between standards when a bidirectional dependency can bring harmonization. A bidirectional dependency does not imply that implementers have to support both ISO standards.
Reference Systems interfaces are defined in GeoAPI referencing packages. A Reference System may be a Coordinate Reference System (ISO 19111:2019) or may use geographic identifiers (ISO 19112:2019). GeoAPI supports both cases by defining ReferenceSystem as the common parent of Coordinate Reference System and Reference System using Geographic Identifier. This is done by inserting the ISO 19115 ReferenceSystem interface between IdentifiedObject and CoordinateReferenceSystem in ISO 19111 type hierarchy as shown below (note: this diagram does not show all types, properties and associations for brevity reasons):
Figure 9 — Location of ReferenceSystem in the hierarchy of ISO 19111 types
More information about the CoordinateReferenceSystem interface is given in the Referencing packages section (Clause 7.5). The following table lists all association to a reference system from the metadata packages:
Table 13 — Associations from a metadata object to a reference system
|Metadata interface||Property name||Property type|
7.3.3. Nil values
ISO/TS 19115-3:2016 – XML schema implementation for fundamental concepts allows property values to be nil even when the property is declared mandatory by ISO 19115-1 standard. In such case, ISO 19115-3 requires to specify why the property is nil. Nil reasons can be:
Template: the metadata is only a template with values to be provided later.
Withheld: the value is not divulged.
Unknown: a correct value probably exists but is not known and not computable.
Missing: the correct value is not readily available and may not exist.
Inapplicable: there is no value.
GeoAPI does not provide a mechanism for specifying the reason why a property is nil. Instead, the GeoAPI rules of method return values have been relaxed for the metadata packages. Elsewhere in GeoAPI, methods which have a mandatory obligation in the specification must return an instance of the return type and cannot return the Java null or Python None reference. However, in the metadata package this rule is relaxed because data sets are encountered so frequently which have nil values for any of above-cited reasons. In the GeoAPI metadata packages, methods for mandatory properties should return a valid instance, but users should be prepared to receive null (Java), None (Python) or an empty collection. This modification has been adopted to allow implementations sufficient latitude about how to handle metadata records with nil values. Nonetheless, sophisticated implementations can determine if a metadata record conforms with the ISO 19115-1 specification by inspecting the annotations at runtime (Annex D.1.1).
7.3.4. Departures from ISO 19115
Metadata in GeoAPI differ from the OGC/ISO standards as described in the following sub-sections.
22.214.171.124. Harmonization with ISO 19115-2
A departure in the GeoAPI metadata packages from the published ISO 19115 standard is in the way GeoAPI metadata package added the types and properties defined in the specification ISO 19115-2:2019 – Extensions for acquisition and processing. The latter was forced to create a number of interfaces to hold elements which naturally could occur directly in the interfaces defined by ISO 19115-1. We integrated such interfaces directly into the existing interfaces rather than adding complexity to the API which exists by historical accident. For example, ISO 19115-2 defines a MI_Band interface which extends the MD_Band interface defined by ISO 19115-1, with the addition of a transferFunctionType property (among others) for completing the scaleFactor and offset properties defined by ISO 19115-1. GeoAPI merges those two interfaces together, with annotations (Clause 7.1.3) on each property for declaring the originating standard. The metadata interfaces merged in such way are:
Table 14 — Metadata ISO 19115-2 interfaces merged with ISO 19115-1 parent interfaces
|ISO 19115-1 parent interface||ISO 19115-2 subclass merged with parent|
126.96.36.199. Harmonization with ISO 19111
Coordinate Reference Systems (CRS) are defined in details by the ISO 19111:2019 standard. But the ISO 19115 metadata standards do not reference those CRS interfaces directly (except VerticalCRS). Instead, the metadata standards reference CRS by their identifier (for example an EPSG code), optionally accompanied by a code telling whether the CRS type is geographic, projected, temporal, a compound of the above, a geographic identifier, etc. The ISO 19115 standard combines those two information in a ReferenceSystem interface.
In order to have a more uniform way to handle reference systems, GeoAPI replaces (identifier, type code) tuples by associations to the actual Reference System objects. The ISO 19115 ReferenceSystem type is redefined as a subtype of ISO 19111 IdentifiedObject (Figure 9). The referenceSystemIdentifier property defined by ISO 19115 is replaced by inheritance of identifier property from IdentifiedObject. The referenceSystemType property value (geographic, projected, compound, geographic identifier, etc.) can be determined using language-specific instructions such as instanceof in Java.
In the same spirit than above replacement, verticalCRSId is omitted because redundant with verticalCRS.
7.4. Geometry packages
The GeoAPI geometry packages use the opengis.geometry namespace and are placeholder for types defined in the ISO 19107:2003 — Spatial schema specification. TODO: upgrade to ISO 19107:2019. The geometry specification provides a vector based spatial representation of elements. The geometry types defined in GeoAPI include only the two simplest types from ISO specification along with their abstract parent interfaces. Those types are defined because they are needed by the referencing package. Other types are expected to be added in future GeoAPI versions.
Table 15 — Mapping of types from the geometry package
|ISO 19107 interface||Java type||Python type|
The DirectPosition type represents a single location in the coordinate space defined by a CoordinateReferenceSystem. The Envelope type represents the lower and upper extreme values along each axis. This type is frequently conflated with a bounding rectilinear box but the two types differ conceptually. The Envelope type in ISO 19107 provides methods to obtain the “corners” of the envelope as DirectPosition instances. However, users should note that these positions might not have any meaning in physical space. For example, the corners could be outside the Coordinate Reference System (CRS) domain of validity even if the feature itself is fully inside that domain. The corner DirectPosition instances are acting, for convenience, as data containers for tuples of coordinates but not as representations of an actual position.
7.4.1. Geometry base class
Each geometric object is considered an infinite set of points (except the Point object which contains only itself). As a set, their most fundamental operations are of the same nature as the standard operations of Java collections. We could therefore see a geometry as a kind of java.util.Set in which the elements are points, except that the number of elements contained in the set is infinite (with the exception of geometries representing a simple point). To better represent this concept, the ISO standard and GeoAPI define a TransfiniteSet interface which we could see as a Set of potentially infinite size. Although a parent relationship exists conceptually between these interfaces, GeoAPI does not define TransfiniteSet as a sub-interface of java.util.Set, as the definition of certain methods such as size() and iterator() would be problematic. However, we find very similar methods such as contains(…) and intersects(…).
ISO 19107 defines two types of structures to represent a point: GM_Point and DirectPosition. The first type is a true geometry and may therefore be relatively cumbersome, depending on the implementation. The second type is not formally considered to be a geometry; it extends neither GM_Object nor TransfiniteSet. It barely defines any operations besides the storing of a sequence of numbers representing a coordinate. It may therefore be a more lightweight object. In order to allow API to work equally with these two types of positions, ISO 19107 defines Position as a union of DirectPosition and GM_Point. GeoAPI represents the union as parent interface for compatibility with languages that do not support union.
7.4.2. Departures from ISO 19107
Geometries in GeoAPI differ from the OGC/ISO standards as described in the following sub-sections.
The parent class of all geometries is called GM_Object in the ISO 19107 standard. GeoAPI interfaces use the Geometry name instead, as the omission of the GM_ prefix would leave a name too similar to Java’s Object class.
GeoAPI has moved the DirectPosition and Envelope types from the coordinate sub-package where they are defined in the ISO 19107 specification up to the opengis.geometry package due to their importance and frequency of use.
188.8.131.52. Union replacement
ISO 19107 defines Position as the union of DirectPosition and Point. But unions are not allowed in Java. Instead, GeoAPI defines Position as the base interface of both types so a similar functionality can be achieved with an “is instance of” check.
GeoAPI adds the following shortcut methods in the Envelope interface. They are frequently requested information that implementers can often provide in a more efficient way than forcing users to compute them from lower and upper corners: dimension, minimum, maximum, median and span.
7.5. Referencing packages
The GeoAPI referencing packages use the opengis.referencing and opengis.parameter namespaces and implement the types defined in the ISO 19111:2019 — Referencing by coordinates specification. TODO: upgrade to ISO 19111:2019. The referencing package also includes the types describing object factories and mathematical transformation operators defined in the legacy standard OGC 01-009 — Coordinate Transformation Services from 2003. Those types can be used to define various datums, define various coordinate systems, and combine those to define the coordinate referencing systems (CRS) generally encountered in geospatial science. The UML below (incomplete for brevity) shows a few commonly used GeoAPI types. Differences compared to ISO 19111 (notably inheritance from ReferenceSystem type, location of coordinateSystem association and inclusion of MathTransform interface) are discussed in following sections and in the departures section (Clause 7.5.6).
Figure 10 — Subset of interfaces derived from ISO 19111 and other standards
More information about the ReferenceSystem parent interface is given in the Metadata packages section (Clause 7.3.2). The mapping from ISO 19111 packages to GeoAPI packages is shown below:
Table 16 — Referencing package mapping
|ISO package||Java package||Python module|
|Coordinate Reference System||org.opengis.referencing.crs||opengis.referencing.crs|
7.5.1. Coordinate systems
From ISO 19111:2019 §10 and §C.3
A Coordinate System (CS) contains the set of axes that spans a given coordinate space. Each axis defines an approximate direction (north, south, east, west, up, down, port, starboard, past, future, etc.), units of measurement, minimal and maximal values, and what happen after reaching those extremum. For example, in longitude case, after +180° the coordinate values continue at −180°.
In addition to axis definitions, another important coordinate system characteristic is their type (CartesianCS, SphericalCS, etc.). The CS type implies the set of mathematical rules for calculating geometric quantities such as angles, distances and surfaces. Usually the various CS subtypes do not define any new programmatic methods compared to the parent type, but are nevertheless important for type safety. For example, many calculations or associations are legal only when all axes are perpendicular to each other. In such case the coordinate system type is restricted to CartesianCS in method signatures.
184.108.40.206. Associations with CRS
The coordinate system associated to a SingleCRS shall be an instance of one CoordinateSystem subtype. It should be a subtype defined by ISO 19111 when possible, or a user-defined subtype when no standard type describes the space geometry. The standard coordinate system types are Cartesian, affine, spherical, cylindrical, polar, ellipsoidal, vertical, temporal, ordinal and parametric.
The coordinate system associated to a CompoundCRS is of unspecified type. None of the standard types describe the full space geometry, and implementers do not need to define a public type. The CoordinateSystem in this context is only a list of axes defined as the concatenation of the list of axes of all components, without saying anything about space geometry. Requesting elements in that list can be thought as redirection to the coordinate system of a CRS component.
NOTE: An implementation may know that the third coordinate system axis of a CompoundCRS is the first axis of the second CRS component, and redirects axis information requests to that component. In this scenario the CoordinateSystem implementations does the work that users would need to do themselves if they wanted information about axes, but in a more convenient and potentially more efficient way.
Since above paragraphs define coordinate system for both SingleCRS and CompoundCRS interfaces, GeoAPI provides the coordinateSystem association in the CoordinateReferenceSystem (CRS) parent interface. It makes easy for users to get information about the coordinate system axes of any CRS, with automatic redirection to CompoundCRS components when needed.
From OGC 01-009 §12.3.[6…7] and §12.4.6
The referencing packages include factory types defined originally in the OGC 01-009 specification. These factories define a normalized approach to object instantiation and, if used exclusively, simplify the work of switching between implementations. Subtypes of ObjectFactory instantiate objects by assembling components passed as arguments and subtypes of AuthorityFactory instantiate objects based on identifiers in some third party database, notably those in the EPSG geodetic dataset.
Figure 11 — Factory interfaces partially derived from OGC 01-009
TODO: Some methods of CRSAuthorityFactory and CoordinateOperationAuthorityFactory to be replaced by ISO 19111:2019 RegisterOperations.
Code that needs to instantiate one of the objects defined in GeoAPI referencing packages should first obtain the factory in some platform dependent manner and then use the factory methods to instantiate the desired object instances. These instances can then be used through the interfaces defined in the GeoAPI library.
In Java, factory implementations are discovered by java.util.ServiceLoader. In Python, GeoAPI does not have a recommended mechanism yet.
220.127.116.11. Axis order
The order of coordinate system axes in every objects obtained from an AuthorityFactory shall be as defined by the authority. The order depends on the Coordinate Reference System (CRS) type and the country defining the CRS. In the case of geographic CRS, this is often – but not always – the (latitude, longitude) axis order. In particular the following method call:
shall return a coordinate reference system with (latitude, longitude) axis order, not (longitude, latitude).
7.5.3. Coordinate operations
From ISO 19111:2019 §12 and §C.5
A Coordinate Operation can transform or convert coordinate tuples from one Coordinate Reference System (CRS) to another CRS. There is four kinds of coordinate operations in GeoAPI:
A coordinate conversion is the implementation of some mathematical formulas without empirically derived parameters. Conversions can be as accurate as floating point computations allow. Map projections are kinds of coordinate conversions.
A coordinate transformation involves empirically derived parameters. Because those parameters have observational error and because transformation methods are only approximations of a complex reality, the coordinate transformation results also have errors. Furthermore, several transformations may exist for the same pair of coordinate reference systems, differing in their method, parameter values, domain of validity and accuracy characteristics.
TODO: Point motion operation.
A concatenated operation defines a sequential execution of any of above operations.
GeoAPI provides three ways to create a coordinate operation, described in the following sub-sections.
18.104.22.168. From a pair of CRS
Given a source coordinate reference system (CRS) in which existing coordinate values are expressed, and a target coordinate reference system in which coordinate values are desired, CoordinateOperationFactory can provide a coordinate operation performing the conversion or transformation work. An example is given in Annex D.1.8 for the Java language.
Note that when several possibilities exist for the same pair of CRS, the selected transformation is implementation-dependent. Implementations should select the “best” transformation based on criterion such as accuracy and domain of validity, but GeoAPI does not specify any rule. Users are encouraged to verify which transformation has been selected by invoking the CoordinateOperation.toWKT() method.
TODO: RegisterOperations returns a set of all operations.
22.214.171.124. From operation parameter values
The ParameterValue interface provides methods to set the value of the operation parameter. In the general use pattern for these types, a ParameterValueGroup containing all the named parameters for an operation method is first obtained from the OperationMethod or the MathTransformFactory, and then each ParameterValue instance is obtained in turn and its value set. This use pattern ensures that all the needed parameters for an operation method can be obtained as a single block. An example is given in Annex D.1.7 for the Java language.
7.5.4. Math transforms
From OGC 01-009 §12.4.5
The CoordinateOperation object introduced in previous section provides high-level information (source and target CRS, domain of validity, positional accuracy, operation parameter values, etc). The actual mathematical work is performed by a separated object obtained by a call to getMathTransform(). At the difference of CoordinateOperation instances, MathTransform instances do not carry any metadata. They are kind of black box which know nothing about the source and target CRS, the domain or the accuracy (actually the same MathTransform can be used for different pairs of CRS if the mathematical work is the same), Furthermore, MathTransform may be implemented in a very different way than what CoordinateOperation said. In particular many conceptually different coordinate operations such as unit conversions, axis swapping, etc. can be implemented by MathTransform as affine transforms and concatenated for efficiency. The result may be a MathTransform doing in a single step a calculation described by CoordinateOperation as a chain of distinct operations. Having MathTransform separated from CoordinateOperation gives more flexibility to implementers for optimizations.
Figure 12 — Association between Coordinate Operation and Math Transform
MathTransform has a method taking a DirectPosition (the coordinates in source CRS) in input and returning a DirectPosition (the coordinates in target CRS) in output. But MathTransform provides also various methods operating on an arbitrary number of coordinate tuples packed in arrays of float or double types. If there is many points to transform, the methods operating on arrays will generally be much more efficient than the method operating on DirectPosition. The example in Annex D.1.8 shows how to transform in Java the coordinates of 6 cities.
126.96.36.199. Partial derivatives
From OGC 01-009 §188.8.131.52
MathTransform can also provide the derivative of the transform function at a point. For example, if P is a map projection converting degrees of latitude and longitude (φ, λ) into projected coordinates (x, y) in metres, then the derivative said what would be the displacement V⃗ in metres if the latitude is increased by 1° north, and what would be the displacement U⃗ in metres if the longitude is increased by 1° east. Those vectors are potentially different for every locations on the map. The figure below illustrates the vectors evaluated at two locations, P₁ and P₂:
Figure 13 — Derivatives of a map projection
The derivative is the matrix of the non-translating portion of the approximate affine map at the point. The derivative at a location P can be represented by a Jacobian matrix as below. The first matrix column gives the V⃗ vector and the second column gives the U⃗ vector of Figure 13, in that order because this example uses latitude, longitude axis order as inputs.
Jacobian matrices can easily be concatenated in a chain of operations. The Jacobian matrix of the whole chain is the product of the Jacobian matrices of each step. Another useful property is that for obtaining the Jacobian of the reverse operation P⁻¹, the equations do not need to be derived. The Jacobian of the forward projection can be computed, then the matrix inverted:
7.5.5. Well-Known Text (WKT)
Most objects in the opengis.referencing packages can be imported and exported in Well-Known Text (WKT) format. This format allows the exchange of CRS definitions with implementations of other OGC standards such as web services. GeoAPI provides two toWKT() methods for producing a WKT representation of an object:
One method is defined in the IdentifiedObject parent interface and is inherited notably by CoordinateReferenceSystem. But that method can also be used with CoordinateOperation and various components such as Datum. Well Known Text (WKT) character strings produced by that method shall be compliant with the format defined in the ISO 19162:2019 standard.
A second toWKT() method is defined in the MathTransform interface, which is not an object defined by ISO standards. Character strings produced by that method shall be compliant with the format defined in OGC 01-009 §7.1. Other sections such as OGC 01-009 §7.2 should be ignored since they are replaced by ISO 19162.
Difference between the two WKT representations is illustrated below. For a very simple operation doing only a swapping of latitude and longitude axes, the ISO 19162 representation of the CoordinateOperation object can be as below:
COORDINATEOPERATION["Axis order change (2D)",
SOURCECRS[GEODCRS["RGF93", ...definition omitted for brevity..., ID["EPSG", 4171]]],
TARGETCRS[GEODCRS["RGF93 (lon-lat)", ...definition omitted for brevity..., ID["EPSG", 7084]]],
METHOD["Axis Order Reversal (2D)", ID["EPSG", 9843]],
AREA["World."], BBOX[-90.00, -180.00, 90.00, 180.00]]
Figure 14 — ISO 19162 representation of a coordinate operation
The OGC 01-009 §7.1 representation of the MathTransform associated to above coordinate operation can be as below. All metadata information (source and target CRS, domain of validity, etc.) are lost, and the human-readable ”Axis Order Reversal” operation is replaced by a more mathematical “Affine parametric transformation” operation.
Figure 15 — OGC 01-009 representation of a math transform
Those two representations are complementary. CoordinateOperation.toWKT() provides high-level information about the operation together with metadata for understanding the context. MathTransform.toWKT() said more information about how the operation is implemented, which is useful for analyzing the validity of transformation results.
The converse operation – creating an object from a WKT definition – is done by createFromWKT(…) methods defined in CRSFactory and MathTransformFactory interface.
7.5.6. Departures from ISO 19111
The main departures of GeoAPI from the ISO 19111 standards are inspired by the legacy OGC 01-009 standard published in 2001. That legacy standard included COM, CORBA and Java profiles. In support for those profiles, some aspects of the legacy model were better suited to programming languages compared to the more web-focused standards published the following years. GeoAPI retains some OGC 01-009 aspects when appropriate and adapt them to the ISO 19111 interfaces. References to OGC 01-009 clauses are given in sub-sections below.
184.108.40.206. Separation between coordinate operation metadata and execution
From OGC 01-009 §12.4.[1,5] and figure 11
A major extension of GeoAPI compared the ISO 19111 standard comes from the inclusion, directly in the CoordinateOperation interface, of a method providing access to the MathTransform interface from the older OGC 01-009 specification. That interface performs the actual computation of coordinates in target CRS from the coordinates in source CRS. This separation – between a type providing operation metadata and a type doing the actual work – existed in OGC 01-009 and has been kept by GeoAPI for giving to developers more flexibility regarding optimizations. The operations that are really executed by MathTransform may be very different than the operations described by CoordinateOperation, provided that they are mathematically equivalent. An example is given in Clause 7.5.5.
Since the 2019 revision of ISO 19111 specification, the CoordinateOperation interface has a transform(…) method too. But that new method can be implemented as a convenience method redirecting the work to MathTransform.
220.127.116.11. Coordinate system association
From OGC 01-009 §18.104.22.168 and figure 7
In the ISO 19111 specification, only SingleCRS has an association to coordinateSystem. GeoAPI moves this association to the CoordinateReferenceSystem parent interface for user convenience, because coordinate system (CS) dimension and axes are frequently requested information and will always be available, directly or indirectly, even for CompoundCRS. However, only coordinate systems associated to SingleCRS can be instances of ISO 19111 concrete subtypes (CartesianCS, SphericalCS, VerticalCS, etc.). It is not possible to assign a standard concrete type to the coordinate system of a CompoundCRS. For the latter case, users see only the abstract CoordinateSystem type which serves merely as an axis container. The concrete CS subtype can be hidden in implementation details.
NOTE: This generalization would not be appropriate for a database schema or for formats such as Well Known Text because axes listed with a CompoundCRS would be redundant with axes listed with each CRS component. But this consideration does not apply to programming languages: the axes do not need to be repeated because each method such as CoordinateSystem.getAxis(int) contains code, not necessarily data structure. Implementations can redirect requests for CoordinateSystem axes to corresponding CompoundCRS elements.
22.214.171.124. Type and property names
From OGC 01-009 §126.96.36.199
The ISO 19111 CRS type name has been expanded to the CoordinateReferenceSystem name in GeoAPI for compatibility with previous GeoAPI versions. It is also common practice in Java language to avoid abbreviations.
In the GeneralDerivedCRS interface, the conversion association to Conversion has been renamed conversionFromBase for making clear that the source CRS is the baseCRS. This naming is similar to the one used in OGC 01-009 with direction reversed.
188.8.131.52. Ellipsoid second defining parameter
From OGC 01-009 §12.3.10
ISO 19111 defines the union named SecondDefiningParameter as being either semiMinorAxis or inverseFlattening. The union construct (defined in some languages like C/C++) does not exist in Java. GeoAPI changed the interface to require both ellipsoidal parameters (in addition to the semiMajorAxis parameter which is mandatory in any case), as was done in OGC 01-009. However, implementors could readily permit users to only provide one of the two parameters by creating a class which calculates the second parameter from the first. For precision, GeoAPI imports the isIvfDefinitive boolean property from OGC 01-009 to enable the user to establish which of the two parameters was used to define the instance.
184.108.40.206. Scope and domain of validity
In the ISO 19111 model, only the Datum, CoordinateReferenceSystem and CoordinateOperation types can specify a scope and a domain of validity. This is done through the domain property defined in a common parent of those three types, named ObjectUsage. GeoAPI makes the domain property more generally available by moving it into the IdentifiedObject parent type. This generalization allows other types of object, such as CoordinateSystem, to also specify a domain. For example, an application for data in space may want to define a MinkowskiCS type with the following scope: “For objects moving at relativistic speed”.
As a side-effect of this generalization, the ObjectUsage interface can be omitted since domain was its sole property. The ObjectUsage type name is at odd with the semantics of subclassing as an “is type of” hierarchy. Qualifying a CRS as “a type of object usage” is restrictive. Instead, CRS contains a description of object usage. This semantic oddity is avoided by omitting the ObjectUsage type.
220.127.116.11. Omitted unions
ISO 19111 defines GeodeticCS, EngineeringCS and DerivedProjectedCS unions for type safety. For example, the GeodeticCS union ensures that a GeodeticCRS can only be associated to a CartesianCS, an EllipsoidalCS or a SphericalCS. Those unions have been omitted from GeoAPI because unions are not supported in Java language, and the Python language does not enforce type safety.
The concept of operation parameters is defined in many OGC/ISO standards:
ISO 19111:2019 provides CC_OperationParameter,
ISO 19115-1:2014 provides SV_Parameter,
ISO 19157:2013 provides DQM_Parameter,
ISO 19143:2010 provides Argument, and
OGC 01-004 (a legacy standard, but still useful to GeoAPI) provided GC_ParameterInfo.
GeoAPI provides a unified parameter framework in the org.opengis.parameter Java package. The ISO 19111 model is adopted as the basis because it provides a clear separation between the definition of a parameter (name, aliases, identifier, expected value type and units) and the actual parameter value. The parameter properties that are defined by other standards but not present in CC_OperationParameter are retrofitted in the GeoAPI parameter framework.
Table 17 — Main parameter properties and their mapping to ISO standards
|GeoAPI||ISO 19111||ISO 19115||ISO 19157||ISO 19143||Remarks|
|identifier||identifier||Optional, contrarily to name which is mandatory.|
|name.description||definition||Should be a short sentence.|
|description||description||description||BrowseGraphic property not explicitly supported.|
|minimumOccurs||minimumOccurs||optionality||optionality = (minimumOccurs > 0)|
|maximumOccurs||maximumOccurs||repeatability||repeatability = (maximumOccurs > 1)|
ISO 19157 Description type contains a mandatory text and an optional illustration. Only the text description is explicitly stored in the GeoAPI unified parameter type. However, if needed implementations can associate the description property to an object that implement both the InternationalString and Description interfaces.
18.104.22.168. Departures from ISO model
OperationParameter has been renamed as ParameterDescriptor to emphasize that it only describes the parameters without providing values. The Descriptor suffix is found in other Java libraries such as JavaBeans and Java Advanced Imaging.
7.6. Feature packages
The GeoAPI feature package uses the opengis.feature namespace and implements the types defined in the ISO 19109:2015 – Rules for application schema specification. The main UML materialized by GeoAPI is ISO 19109 figure 5 (TODO: verify). That figure is also reproduced in ISO 19103:2015 figure E.6.
TODO: provide UML and explain the mapping.
7.6.1. Moving feature
From OGC 18-075 figure 3
Features often have an attribute of type Geometry (ISO 19107:2003). A sub-type of Geometry is Trajectory (ISO 19141:2008). A feature where the geometry is a trajectory is a moving feature. In addition of time-dependent positions defined by the trajectory, a moving feature may also have time-dependent attribute values. Those attributes are represented by the DynamicAttribute sub-type.
7.7. Filter packages
The GeoAPI filter packages use the opengis.filter namespace and implement the types defined in the ISO 19143:2010 — Filter encoding specification. GeoAPI ignores the XML encoding aspects and retains only the types defined in UML diagrams.
The two most fundamental types are Expression and Filter, shown in next sections. All expressions are identified by a ScopedName and all filters are identified by a CodeList. This is an extension to ISO 19143 specification where only some specific sub-types have those identifications. This generalization allows, in some cases, to execute generic code without the need to check the filter or expression sub-types.
From ISO 19143:2010 §7.[3…6]
An expression is a function that receives a resource (typically a Feature) in input and produces a value (typically a character string, a number or a geometry) in output. The output is restricted to Boolean if the expression is used as an operand of a LogicalOperator (Clause 7.7.2).
Expressions extend the mechanism provided by the target platform for defining functions. For example, in the Java language, Expression extends the java.util.function.Function interface (Annex B.2).
An expression can be a literal, a reference to the values of a particular property in resources, or a named procedure (for example arithmetic operations between the results of two sub-expressions). An expression can have zero or more parameters and generates a single result. The parameters themselves are in-turn expressions and shall appear in the order in which they are defined in the FilterCapabilities (Clause 7.7.3).
Figure 16 — Partial UML of expressions
ValueReference is an expression whose value is computed by retrieving the value indicated by a name or a XPath in a resource (typically a property in Feature instances), and Literal is an expression whose value is a constant.
Parameters are specified at Expression creation time. For example, an expression computing x+1 where x is the value of a Feature property can be created with two parameters: a ValueReference retrieving the x value for each feature and a Literal whose value is the integer 1. When apply(f) is invoked on that “Add” expression where f is a Feature instance, the “Add” expression invokes in turn apply(f) on the two above-cited parameters. The values computed by those parameters are added, then returned by the “Add” expression.
From ISO 19143:2010 §7.[7…11]
A filter is a predicate that identifies a subset of resources from a collection of resources. Each resource instance is evaluated against a filter, which always evaluates to true or false. If the filter evaluates to true, the resource instance is included in the result set. If the filter evaluates to false, the resource instance is ignored. Roughly speaking, a filter encodes the information present in the WHERE clause of a SQL statement.
There are various sub-interfaces of this interface that represent many types of filters, such as simple property comparisons or spatial queries. The following diagram shows the 4 basic types of filters together with the code lists identifying which operation is applied. More specialized sub-types such as BinaryComparisonOperator and DistanceOperator are not shown in this diagram.
Figure 17 — Partial UML of filters
In above diagram, the operatorType property defined in the Filter parent interface is overridden by more specialized types (shown as associations) in each sub-interface. This is type covariance. Likewise expression is defined in parent interface with unconstrained multiplicity, but that multiplicity is restrained in sub-interfaces.
Filter operands are expressions. For example, a filter named "PropertyIsEqualTo" uses two expressions. The first expression may be a ValueReference fetching the value of a property and the second expression may be a Literal with the desired value.
From ISO 19143:2010 §7.13
FilterCapabilities is the entry point for listing which expressions and filter operators are available. It capabilities are separated in the following categories:
IdCapabilities lists names that represent the resource identifier elements that the service supports.
ScalarCapabilities advertises which logical, comparison and arithmetic operators the service supports.
SpatialCapabilities advertises which spatial operators and geometric operands the service supports.
TemporalCapabilities advertises which temporal operators and temporal operands the service supports.
AvailableFunction describes functions that may be used in filter expressions.
ExtendedCapabilities advertises any additional operators added to the filter syntax.
7.7.4. Departures from ISO 19143
The ISO 19143 model is slightly modified in GeoAPI for retrofitting with existing interfaces in Java and Python. Some modifications are also applied for generalization when non-encoded property values can be computed. The aim is to facilitate computational operations without preventing the encoding of ISO 19143 compliant XML documents, as omitted types (for example) can be inferred.
22.214.171.124. Omissions relative to expressions
Function interface is omitted (actually retrofitted into the base Expression interface) for avoiding confusion with function interfaces provided natively by target platforms (such as the java.util.function package). Instead, the Function properties are moved into the Expression parent interface because from a programming language point of view, all expressions – including Literal – can be viewed as a kind of function. The following partial UML diagrams illustrate the difference.