OGC GeoAPI 3.1/4.0

This specification uses opengis in the text for denoting a package or module in OGC namespace, but the exact spelling 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.

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

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.

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 the references clause. 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:

Those annotations are related to the ISO 19115-1 Metadata standard in the following way: above Obligation enumeration is the MD_ObligationCode enumeration defined by ISO 19115, moved into the opengis.annotation package for making it closer to other UML-related types. A forbidden value has been added for handling the cases where a property defined in a parent interface is inapplicable to a sub-interface (those cases are declared in ISO standards with the maximum number of occurrence set to zero). Above Stereotype enumeration is a copy of the MD_DatatypeCode code list defined by ISO 19115, retaining only the values relevant to GeoAPI. This duplication exists because the ISO 19115 standard defines a code list, while Java annotations require enumerations.

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 a GeoAPI restriction in 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.

From ISO 19103:2015 §7.2.1

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 double, the language primitive is preferred. However, when the value must be able to be set to null, the object wrapper of that primitive may be used in languages where "primitives" and "wrappers" are distinct. The following table shows the mapping used by GeoAPI to represent the primitive types in the ISO 19100 series.

(1) The primitive type, such as int and double, is used instead of the wrapper where the value can not be null.
(2) Sometime substituted by java.lang.Long or 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.

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

(1) Some properties defined in GeoAPI 3.x use the legacy java.util.Date class for historical reasons.

Note: DateTime is distinct from Instant. The former is expressed in the proleptic Gregorian calendar as described in ISO 8601, while the later 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.

Unless otherwise required by the semantic of a property, GeoAPI preferably uses the Collection type in Java method signatures. This allows implementors 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.

From ISO 19103:2015 §6.5

GeoAPI distinguishes between two enumerated types depending on whether the complete set of literal types is known when the code is originally created, or if the list may be extended at run time. Many language provides an enum construct for the former case and GeoAPI defines the CodeList abstract class in Java for the later case.

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. For the Python API, class names are left unchanged.

From ISO 19103:2015 §7.5

A name is a sequence of identifiers rooted within the context of a namespace. NameSpace defines a domain in which "names" given by character strings can be mapped to objects. For example a class forms a namespace for the properties that the class contains.

GenericName is the base interface for all names in a NameSpace. A generic name can be either a LocalName, or a ScopedName which is a composite 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:​9.5:​4326" is a ScopedName, then "urn" is the head and "ogc:​def:​crs:​EPSG:​9.5:​4326" is the tail. GeoAPI extends the model by allowing navigation in the opposite direction, with "urn:​ogc:​def:​crs:​EPSG:​9.5" as the path and "4326" as the tip.

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. The NameFactory is an extension of the GeoAPI project designed to allow the construction of instances of these name types.

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 GenericName interface (not shown in above diagram) 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 aName property appears as toString in above UML diagram, 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 ISO 19103 NameSpace interface defines also mapping functions from a name to the object identified by that name. But this functionality does not appear in the GeoAPI NameSpace interface; instead we left these mappings to other frameworks (for example Java Naming and Directory Interface).

From ISO 19103:2015 §7.7

Records define new data type as an heterogeneous aggregation of component data types. Each data component is identified by a MemberName and has exactly one value per record.

TODO: add UML diagram (show how Field is replaced by Map<type,value>). Resolve https://github.com/opengeospatial/geoapi/issues/17

From ISO 19115-1:2014 §6.5.[2…14]; ISO 19115-1 §6.6; ISO 19157

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 replaced by the ISO 19111 interfaces from the referencing package.

Coordinate Reference Systems (CRS) are defined in details by the ISO 19111 interfaces in GeoAPI referencing packages. A Reference System may also use geographic identifiers (ISO 19112) instead of coordinates. The common parent interface of Coordinate Reference System and Reference System by Geographic Identifier is ReferenceSystem. GeoAPI inserts this interface between IdentifiedObject and CoordinateReferenceSystem in ISO 19111 interface hierarchy (this is a departure from ISO standards). Usages are shown below:

TODO: replace above table by UML diagram showing IdentifiedObject and ReferenceSystem.

The reference system identifier can be obtained by ReferenceSystem.identifier. The reference system type (geographic, projected, compound, etc.) can be determined using language-specific instructions, for example instanceof in Java. If a metadata instance does not have the full reference system definition but only its identifier, then the implementation can use a custom ReferenceSystem instance.

The interfaces in the GeoAPI metadata packages are primarily containers of primitive types and other metadata types. Metadata elements will be encountered in the data types from the referencing packages and the interfaces enable users to obtain the elements of the data type. As an example, we want to print a list of all the individuals (ignoring organizations) for a document starting with a Citation element:

The remainder of the metadata packages work in similar ways, where client code must disaggregate an instance to obtain the elements needed.

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 – Extensions for imagery and gridded data. 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. 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 on each property for declaring the originating standard. The metadata interfaces merged in such way are:

Another departure come from GeoAPI replacing the MD_ReferenceSystem interface by RS_ReferenceSystem. Coordinate Reference Systems (CRS) are defined in details by the ISO 19111 interfaces in GeoAPI referencing packages. But the ISO 19115 metadata standards do not reference those CRS interfaces directly (except in one case). 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, etc. The ISO 19115 standard combines those two information in a MD_ReferenceSystem interface. The following table lists the associations to referencing systems as defined by the metadata standards:

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. GeoAPI does that by omitting the MD_ReferenceSystem and MD_ReferenceSystemTypeCode interfaces, replacing them by associations to RS_ReferenceSystem instead as shown in the reference system section. The RS_ReferenceSystem interface is a common parent for Referencing by Coordinate (ISO 19111) and Referencing by Geographic Identifier (ISO 19112). The functionalities can by mapped as below:

As a side-effect of this replacement, verticalCRSId becomes redundant with verticalCRS. Consequently the former is omitted from GeoAPI interfaces.

Note that this requirement does not mean that vendors must implement all types and methods, or can not implement their own API in addition of GeoAPI. This requirement only means that modules or packages inside the org.opengis or opengis namespaces shall contain the exact same set of types as published at above links, and each of those types shall contain the exact same set of properties as published. But vendors are still free to implement only a subset of their choice and throw exception for unimplemented types and methods. Vendors can also add new types and methods, provided that those additions are in a namespace different than org.opengis and opengis. Finally, this requirement apply only to libraries redistributed for use by other developers. Final applications are free to remove any unused types or methods if such removal is invisible to other developers.

At runtime, the annotation of a reference to a GeoAPI interface can be obtained as follows, taking as an example the method getTitle() in the Citation interface:

Java provides a class instance like the Citation.class instance used here for every type, either interface or class, defined in the runtime. The getMethod(…) call uses introspection to obtain a reference to the method from which the annotation can then be obtained. The annotation system therefore provides access, at runtime, to the original definition of the element.