OGC GeoAPI 3.1/4.0

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.

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 (§ 6.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.

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.

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 section 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:

An example in § E.1.1 shows how these annotations are applied in the Java language and how they are available at runtime by introspection.

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.

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.

(1) Wrapper types such as java.lang.Integer or java.util.OptionalInt may be used where appropriate.
(2) Sometime 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.
(5) Actually an extension data type defined in ISO 19103 annex C.2. See internationalization in § 6.2.8.

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.

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

From ISO 19103:2015 §6.5

The feature models abstract specification (annex G) defines controlled vocabulary as 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.

(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 can not be modified directly. An example in § E.1.2 shows how code lists are used in the Java language.

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.

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.

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:

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 amount of fields as (name, type) pairs. A Record is an instance of RecordType containing the actual field values.

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.

Map.Entry in above table means java.util.Map.Entry.

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.

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

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 RFC 4647 Matching of Language Tags). Consequently GeoAPI delegates most internationalization types to the target language standard library, as shown in the following table. An example in § E.1.4 shows the use of InternationalString in the Java language.

(1) Sometime 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).

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-363 (TODO: upgrade to JSR-385). When such language-specific standard exists and provides equivalent functionality to ISO 19103, that external standard is used. See Java profile (§ C.1) or Java example code (§ E.1.5) for more information.

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.

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) or may use geographic identifiers (ISO 19112). 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):

More information about the CoordinateReferenceSystem interface is given in the Referencing packages section (§ 6.5). The following table lists all association to a reference system from the metadata packages:

ISO 19115-3 – 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:

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 (§ E.1.1).

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.

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.

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.

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:

GeoAPI provides three ways to create a coordinate operation:

From OGC 01-009 §12.4.5

The Coordinate­Operation 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 get­MathTransform(). At the difference of Coordinate­Operation instances, Math­Transform 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 Math­Transform can be used for different pairs of CRS if the mathematical work is the same), Furthermore Math­Transform may be implemented in a very different way than what Coordinate­Operation said. In particular many conceptually different coordinate operations such as unit conversions, axis swapping, etc. can be implemented by Math­Transform as affine transforms and concatenated for efficiency. The result may be a MathTransform doing in a single step a calculation described by Coordinate­Operation as a chain of distinct operations. Having MathTransform separated from CoordinateOperation gives more flexibility to implementers for optimizations.

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 amount 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 § E.1.8 shows how to transform in Java the coordinates of 6 cities.

From ISO 19162 and OGC 01-009 §7.1

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:

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 Coordinate­Operation object can be as below:

The OGC 01-009 §7.1 representation of the Math­Transform 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.

Those two representations are complementary. Coordinate­Operation.toWKT() provides high-level information about the operation together with metadata for understanding the context. Math­Transform.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 create­FromWKT(…) methods defined in CRSFactory and Math­Transform­Factory interface.

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.

From OGC 18-075 figure 3

Features often have an attribute of type Geometry (ISO 19107). A sub-type of Geometry is Trajectory (ISO 19141). 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.

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 (§ 6.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 (§ C.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 (§ 6.7.3).

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 Binary­Comparison­Operator and Distance­Operator are not shown in this diagram.

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 "Property­Is­Equal­To" uses two expressions. The first expression may be a Value­Reference fetching the value of a property and the second expression may be a Literal with the desired value.

From ISO 19143:2010 §7.13

Filter­Capabilities is the entry point for listing which expressions and filter operators are available. It capabilities are separated in the following categories:

The enumeration of scalar, spatial and temporal capabilities use de code lists shown in § 6.7.2.

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.

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.

"Getter" methods (methods which obtain a value from an object) are documented through annotations in the Javadoc as mandatory or optional. Mandatory "getter" methods are expected to return the requested value unless the value is missing in which case they shall throw an exception. An exception is made to this requirement in the metadata packages because of the extensive existence of incomplete metadata (§ 6.3.3).

TODO: write a Java program verifying signature of all classes and methods in the org.opengis namespace. This verification would be done for the "libraries" target type only, not the "applications" target type.

This does not require that all instances be tested but merely that if the instances were tested, they would validate.

The annotations in API (§ 6.1.3) are available at runtime by introspection. This is useful, for example, when code needs to marshall data using the names defined by the ISO standard rather than the GeoAPI names. In the following example, the top-level annotations indicate that the ProjectedCRS interface was derived from a type also named ProjectedCRS in the ISO 19111 standard. The enclosed annotation indicates that the getCoordinateSystem() method was derived from a property named coordinateSystem in the ISO 19111 standard, and that a non-null value must be provided by every ProjectedCRS instance:

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

Java provides a class instance like the ProjectedCRS.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.

Controlled vocabulary (§ 6.2.4) can take the form of enumerations or code lists. Those two types are implemented by java.lang.Enum and org.opengis.util.CodeList respectively. The use of CodeList classes includes accessing statically defined elements, defining new elements and retrieving any element defined for the code list. Considering, for example, org.​opengis.​referencing.​cs.​AxisDirection, the following codes could be used:

where the second and third locutions will create a new value if it does not exist. Special care should be taken to keep such calls consistent throughout the code since the CodeList will create a new element if there are any difference in the String parameters. The list of all elements (including new elements created by valueOf(…)) can be obtained as below:

The ISO 19103 name types (§ 6.2.5) define mapping methods from a name to the object identified by that name. But the mapping methods defined by ISO 19103 are not part of the NameSpace interface defined by GeoAPI. Instead, GeoAPI leaves that functionality to frameworks such as the Java Naming and Directory Interface™ (JNDI). Java applications which need such mapping may use the methods in the javax.naming.Context interface:

Internationalization (§ 6.2.8) is handled using objects provided by the standard Java library such as java​.util​.Locale, with the addition of one GeoAPI interface. The org​.opengis​.util​.InternationalString interface provides a container for multiple versions of the same text, each for a specific Locale — the identifier used in Java for a specific language, possibly in a named territory.

The method to obtain factories is not specified by this standard and therefore depends on the design of the library implementation. Also, the locale used by default depends on the choice of the implementation so the result of the call toString() without parameters will depend on the implementation.

Units of measurement are represented in Java by JSR-363 parameterized interfaces (see § C.1 for an overview). Units of the same parameterized type can be used in unit conversions like below (the Units class must be provided by a JSR-363 implementation):

where the initial calls define units of length and then a converter is used to obtain the equivalent length in a new unit. The next example below creates a "kPa" unit of measurement from the "Pa" unit.

The next example creates a new quantity derived from the operand types. It may print "8 mW" – the exact number and unit shown depend on the implementation:

The interfaces in the GeoAPI metadata packages (§ 6.3) are primarily containers of primitive types and other metadata types. Metadata elements will be encountered for example from interfaces in the referencing packages. The metadata interfaces enable users to decompose a given element into smaller elements. As an example, the following code prints a list of all 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 decompose an instance to obtain the elements needed.

A Coordinate Reference System (§ 6.5) can be constructed on its own or can be derived from other systems. This example mixes both cases by creating a ProjectedCRS derived from a GeographicCRS with the Mercator projection. Here we use an authority which has already defined the geographic CRS, the coordinate system and the projection method that we need for this example. Then the example creates a defining conversion from the parameter values and combines it with above-cited predefined components for creating the projected CRS.

TODO: Get factories from ServiceLoader.

Above example created the "Makassar / NEIEZ" coordinate reference system in a hard way for showing the use of factories. But when an authority code is available (which is the case of above example), the use of an authority factory is recommended not only because it is easier, but also because it generally provides more metadata information such as scope and domain of validity. The following example creates the same CRS than above example:

This usage examples lets implementation infers a coordinate operation (§ 6.5.3) for a pair of coordinate reference systems. The Coordinate­Operation­Factory does all the work of establishing which parameters should be used and correctly instantiating the operation.

The following example uses the operation we just created for transforming coordinate tuples. It is possible to transform DirectPosition instances, but if there is many points to transform then packing them in a single array is generally more efficient. For simplicity reasons, this example performs the coordinate operation in-place (i.e. transformed coordinates overwrite source coordinates) and assumes that both source and target CRS are two-dimensional. But GeoAPI is not restricted to these assumptions.