INSPIRE UML-to-GeoJSON encoding rule
Table of Contents
- Use Cases
- Technical Issues
- Technical Limitations
- Cross-cutting INSPIRE requirements
- Normative References
- Terms and Definitions
- Schema Conversion Rules
- Instance Encoding Rules
- Requirements and Recommendations
- Mapping from Conceptual Model to GeoJSON Logical Model
- Alternative Coordinate Reference Systems
- INSPIRE Theme Encoding Rules
This document is the outcome of Action 2017.2 on alternative encodings for INSPIRE data.
The action aimed at defining alternative encoding rules (mainly for the purpose of viewing/analysis in mainstream GIS systems) for a number of selected application schemas and a template and procedure for proposing and endorsing additional encoding rules in the future.
Proposals for alternative encodings rules were collected through an open call on the MIG collaboration platform and prioritised by Member State representatives in a survey. The results of the survey clearly showed support for GeoJSON as a possible alternative encoding. In addition, also simplified GML, database formats (geopackage, PostGIS, ESRI Geodatabase) and linked data had significant support. Further proposals included also GeoSciML as an alternative encoding for GE and MR.
In the 48th MIG-T meeting, it was agreed to continue the 2017.2 work in a sub-group focussing on the following tasks:
- developing an encoding rule for GeoJSON (as a first example)
- developing generic rules / approaches for simplifying the INSPIRE data models (which will be useful for a number of alternative encodings)
- developing the overall procedure for proposing and endorsing additional encodings
The work of the action encompassed the creation of generic encoding rules for GeoJSON as well as specific encoding rules for the INSPIRE themes Addresses (including
GeographicalName properties) and Environmental Monitoring Facilities (including O&M properties). These encoding rules will be maintained as separate INSPIRE Good Practice documents, and in the future additional theme-specific encoding rules may be developed by thematic communities and proposed for endorsement by the MIG following the INSPIRE Good Practice procedure.
This work is also related to
2017.3, where a major outcome is a detailed view on the capabilities of various GIS software of working with INSPIRE data (called CanIUse), encoded in GML or GeoJSON.
This section describes what this document contains and what the high-level objective of this encoding is.
GeoJSON features need not represent entities of the physical world only; mobile routing and navigation apps, for example, might describe their service coverage using GeoJSON.
The GeoJSON format has originally been defined by an Internet working group of developers who needed a solution to encode geometries for use in web applications. It has since been formalised by the IETF, a standards organisation which develops specifications concerning the Internet as RFC 7946.
Within INSPIRE, this encoding rule can be to encode data from several themes, with a focus on usability of the data in GIS desktop and web clients such as ArcMap, QGIS, OpenLayers, Leaflet, FME and hale studio. It can serve as an alternative encoding that can be used instead of the default encoding for simple data, where there is no information loss. In other cases, this GeoJSON encoding may serve as an additional encoding only.
This sections describes the scope of the INSPIRE UML-to-GeoJSON encoding rule. GeoJSON is not equally well suited for all themes and use cases.
This encoding rule specifically addresses data usability in web and desktop client software, such as ArcMap, QGIS, Leaflet and OpenLayers. It optimizes usage of INSPIRE data for mapping and geoprocessing in such applications.
Coverage of INSPIRE Themes
For each theme to be covered, a specific GeoJSON Encoding Rule is provided. These can reside in subfolders in the same repository as this general encoding rule (e.g.
efs), but can also be maintained in other places.
This encoding rule addresses specific technical issues that have been problematic when using the default encoding:
- Most GIS software cannot fully make use of non-simple attributes and nested structures for styling, processing and filtering;
- Multiple values per (complex) properties cannot be used fully in ArcGIS and other GIS tools;
- References to other features often cannot be resolved by GIS tools; Propertes of referenced features cannot be used in styling or for filtering ;
- Abstract geometry types for an object mean that a wide range of different geometries can be used for any single feature class;
- Mixed geometry types in a FeatureCollection are usually not supported.
In some cases such as the handling of high-cardinality properties, this encoding rule makes a trade-off, so not all issues are resolved. Implementers can apply additional model and instance transformation rules to make adjustments for specific data sets and environments.
The GeoJSON format cannot deal with 3D geometries and coverage/raster data, therefore this encoding rule cannot be used for those types of data.
INSPIRE Requirements for Encoding Rules
The Implementing Rules on interoperability of spatial data sets and services (Commission Regulation (EU) No 1089/2010) lays down the following requirements for encoding rules:
Article 7 -- Encoding
- Every encoding rule used to encode spatial data shall conform to EN ISO 19118. In particular, it shall specify schema conversion rules for all spatial object types and all attributes and association roles and the output data structure used.
- Every encoding rule used to encode spatial data shall be made available.
D2.7 specifies more detailed requirements and recommendations for encoding rules. The following list lists the requirements from that document and shows which ones are also met in this encoding rule:
- Requirement 12: ... documents shall be required to be encoded using UTF-8 as character encoding.
D2.7 also contains a relevant recommendation:
- Recommendation 3: Encoding rules should be based on international, preferably open, standards.
This section contains references to standards documents and related resources.
- GeoJSON - IETF RFC 7946
- INSPIRE Drafting Team Data Specifications. D2.7: Guidelines for the encoding of spatial data, Version 3.3
Terms and Definitions
Terms and Definitions can be found in the Glossary document.
Schema Conversion Rules
INSPIRE defines the conceptual model using UML.
The default encoding rule maps this UML model to XML Schema. For JSON, JSON Schema can be used to perform simple validation on JSON documents.
NOTE At this point, JSON Schema is not used in any of the targeted GIS tools. We thus do not use it normatively. Theme-specific GeoJSON Encoding Rules may use JSON Schema to provide a formal definition of the encoded data structures, and to help develop executable test suites.
In this encoding rule, we take a two-step approach, where we apply model transformations on the level of the conceptual model. This model can then be encoded in simple GeoJSON using the general schema and instance conversion rules laid out in the next sections.
All types that have the stereotype
<<featureType>> are converted to GeoJSON objects. The typenames remain as they are.
Where a class has one attribute with a geometry type, this attribute will be mapped to the
geometry property in GeoJSON, while all other properties (attributes and association roles) will be mapped to properties inside the
properties sub-object. Where a class has more than one Geometry property, a theme-specific profile has to define which geometry property is the "default" geometry that should be mapped to the
geometry property in GeoJSON. Additional geometry properties can either be mapped to additional GeoJSON objects, or they can be retained in the set of
All data types are mapped to JSON objects, where properties of the type are directly added to the root object. Their typenames remain as they are.
ISO 19103 - Basic types
All property types are transformed to the simple types that JSON knows about: Number, String, Boolean and Object. The exact mapping from the UML model to the JSON datatypes is outlined in the following table:
|UML Model property type||JSON datatype||Conversion Notes|
|DateTime||string||The string must follow the ISO 8601 format, including timezone information (e.g.
|Date||string||The string most follow the format
Any other UML Model property type are to be mapped to
string, with specific rules being defined on a case-by-case basis in each theme profile.
ISO 19107 - Geometry types
ISO 19107 defines a set of Geometry types, which need to be mapped to the types available in GeoJSON.
NOTE Not all types can be mapped to GeoJSON; if a data set requires such a type, it cannot use this encoding rule as an alternative encoding rule.
|ISO 19107 type||GeoJSON datatype||Conversion Notes|
|GM_Aggregate||GeometryCollection||Limitations apply as to which types in the collection can be included.|
|GM_Curve||LineString||In GML, Curves can also be nonlinear segments or arcs. GeoJSON only supports linear segments.|
|GM_MultiCurve||MultiLineString||In GML, Curves can also be nonlinear segments or arcs. GeoJSON only supports linear segments.|
|GM_Object||Any GeoJSON Geometry type||
|GM_PolyhedralSurface||not supported||At this point, this specification does not support 3D meshes.|
|GM_Primitive||Any GeoJSON Geometry type||
|GM_Tin||not supported||A TIN without triangulation could be converted to a MultiPoint object.|
ISO 19108 - Temporal types
For types from ISO 19108 used in INSPIRE schemas, suitable mappings need to be found on a case-by-case basis. The default should be to use the Simple Period substitution rule.
ISO 19115 - Metadata types
For types from ISO 19115 used in INSPIRE schemas, suitable mappings need to be found on a case-by-case basis. For
CI_Citation, the Simple Citation substitution rule can be applied.
Abstract Types as property types
Where an abstract type with multiple concrete sub-types is used as a property type, a suitable choice of a concrete subtype should be made on a case-by-case basis. As an example, limiting the potential geometry types in this way can make processing easier.
union represents a choice between multiple properties with potentially different value types, such as in the AreaOfResponsibilityType, where there are options such as
areaOfResponsibilityByNamedPlace. The multiplicity of these options may also differ.
For Union Types used in INSPIRE models, suitable mappings need to be found on a case-by-case basis.
Enumerations and Code Lists
No mapping for code lists and enumerations is required. Their values shall be identified by (ideally resolvable) HTTP URIs.
NOTE The INSPIRE Registry can provide the JSON representation of the code list and its entries.
Property names remain as they are.
If a property has a cardinality > 1, a suitable mapping needs to be found on a case-by-case basis. There is a model transformation rule that extracts a single value from a complex property and builds a JSON array which should be used if the number of occurences of such a property can be very high.
Properties that represent values form code lists are encoded using the
SimpleCodelistReference rule described here.
NOTE Namespace prefixes, as used in the default encoding, are not used in the GeoJSON encoding rule.
Properties with a
The unit of measurement attribute (
uom) on any property
x has to be retained. It is transformed to a new property of the type with the name
Property types for properties with a cardinality greater than
1 and a simple property type (e.g. String, Integer, Float, ...) may use arrays of these simple types. More information is available in the Extract Primitive Array transformation rule.
<<voidable>> is not converted. If a property has no value, it may be dropped.
Association roles are retained as they are, if they are not transformed using a profile-specific rule, such as Inline associated or aggregated components using type names.
Instance Encoding Rules
This section describes how the encoding is derived from the converted conceptual model, and describes which common rules have to be applied for this encoding rule.
The character encoding of all data encoding in GeoJSON shall be UTF-8.
Coordinate Reference Systems
As per the requirements of the GeoJSON - IETF RFC 7946 specification, the default CRS for any data set delivered using this encoding rule is a geographic coordinate reference system, using the World Geodetic System 1984 (WGS 84) datum, with longitude and latitude units of decimal degrees, unless there is prior arrangement. This is equivalent to the coordinate reference system identified by the Open Geospatial Consortium (OGC) URN
NOTE As INSPIRE mandates the use of the European Terrestrial Reference System 1989 (ETRS89, see Requirement 1) for the areas within the geographical scope of ETRS89 and both CRS84 and ETRS89 use the GRS 80 ellipsoid (although with minor enhancements), we shall assume CRS84 to be equivalent to ETRS89. If, for any dataset, this assumption would be problematic, then GeoJSON cannot serve as an alternative encoding rule for that dataset.
Alternative Coordinate Reference System support
While the required Coordinate Reference System for any data encoded in GeoJSON is CRS84, a client may request delivery of a data set using a different projected reference system, as per the mechanism described in Requirement 1 of the CRS extension of the OGC API - Features specification.
An INSPIRE Download service delivering data encoded in GeoJSON shall be able to deliver projected geometries if a client requests these explicitly, at least for the spatial reference systems documented in section 6.3. of the data specifications that fall within the scope of this encoding specification. When delivering data that is not in CRS 84, the GeoJSON data should include the
crs member as defined in the deprecated (Draft 6 of the GeoJSON specification)[http://wiki.geojson.org/GeoJSON_draft_version_6].
In the GeoJSON encoding rule,
nilReason information shall not be maintained per feature, but rather in the dataset metadata. Properties that have
nil values shall thus be ignored in the encoding process.
NOTE If, for any dataset, there is specific
nilReason information per feature, then GeoJSON cannot serve as an alternative encoding rule for that dataset
A spatial object encoded using the default encoding rule may have several properties that identify it:
gml:id: This property with the
IDproperty type is not present in the conceptual model, but mandatory for any spatial object encoded in GML. It represents a technical identifier that is unique within a document and can serve as the target of an anchor/reference.
gml:identifier: This property with the
gml:CodeWithAuthorityTypeproperty type is not present in the conceptual model, but inherited from the
AbstractGMLtype. It represents an identifier that is unique within the codeSpace given and serves as the external identifier of the object.
inspireId:This property with the type
IdentifierPropertyTypedefines a unique, persistent domain identifier for the spatial object within the INSPIRE infrastructure.
These properties are mapped to the encoded GeoJSON object as follows:
|Default Encoding property||Property Type||GeoJSON Property||Property Type||Conversion Notes|
||string||Can be omitted if empty in the source object.|
||string||Can be omitted if empty in the source object.|
INSPIRE Theme Encoding Rules
This document does not contain specific rules for each INSPIRE theme. These are maintained in separate documents to facilitate loosely coupled development cycles and groups.
Each of the theme-specific encoding rules defines at least one conformance class. Any conformance class in a theme encoding rule may define a number of model transformation rules that need to be applied before the encoding process. These transformations are documented in the Model Transformation Rules paper. They serve the purpose of adapting the conceptual model (UML) to better match the logical model of the target platform.