Principles for Annex I schema updates

The main goal for these updates should be that, where possible, any data sets and, where possible, software that have already been created according to the current schemas (v3.0) should also be valid according to the updated schemas.

Versioning of schema documents

The current proposal for versioning of xml schemas (inspired by the rules set up for schema versioning by the OGC) is included in the Annex.

According to these rules, all changes that are being proposed to the schemas in this document should be considered minor revisions, since they actually reflect semantic changes in the data models and not bug fixes, while still being backwards-compatible. This means that new versions (in most cases v3.1) of the schema documents will be created and published in the INSPIRE schema repository.

EXAMPLE v3.1 of the Addresses xml schema will be published at http://inspire.ec.europa.eu/schemas/ad/3.1/Addresses.xsd

DISCUSSION ISSUE Versioning of importing schema documents All schema documents that include imports to the updated Annex I schemas should be updated as well. If the updates of the importing schema documents were also considered as minor revisions (rather than bug fixes), this would cause a cascade of new schema versions that would need to be created. It is therefore proposed to treat the updates of import statements in the importing schemas as bugfix releases (i.e. to replace the importing schemas with new schema documents whose import statements point to the updated schema location).

EXAMPLE The current Addresses.xsd (v3.0) schema are imported by the following 3 schemas: /act-core/3.0/ActivityComplex_Core.xsd, /base2/1.0/BaseTypes2.xsd and /us-govserv/3.0/GovernmentalServices.xsd. If new minor revisions were created for these schemas, too, more than 20 further schema documents would need to be updated (which would yet again cause further schema to be updated).

If we follow the proposed approach for namespaces (see below), this means that in some cases, the version number of the schema is not reflected in the namespace, e.g. it is proposed to keep the namespace inspire:specification:gmlas:HydroBase:3.0 for version 3.1 of the HydroBase.xsd schema. Thus, the rules for namespaces and versions used previously (see Annex) needs to be revisited.

Namespaces

It is proposed to keep the current namespaces for the updated schemas, so that existing data using the current schemas will remain valid.

This approach may create problems for existing applications in cases where in the new version of the schema new elements are added. In order not to invalidate data sets created according to the old schema version, all additional elements must be optional. However, if an application tries to consume data with the additional elements (created according to the new schema) and validates it according to the old schema it will complain about the unexpected elements. Therefore, all applications always need to use the latest available schema version for parsing INSPIRE data.

An alternative would be to create a new namespace (e.g. inspire:specification:gmlas:HydroBase:3.1) and to state that all 3.0 data will be valid according to the new schema, if the namespace in the XML instance document is changed to the 3.1 namespace and the rest of the file is left unchanged.

Deprecation / supersession of types

During the Annex I development process, a number of candidate types and placeholders were defined. These were included in v0.0 schemas for the target theme.

EXAMPLE The Building placeholder type is defined in http://inspire.ec.europa.eu/schemas/bu/0.0/Buildings.xsd

In the amendment of the Implementing Rules, a number of Annex I candidate types and references to them have been removed or superseded by other types in the Annex II+III themes. For details, see Annex II of Commission Regulation (EU) No 1253/2013.

In order not to invalidate any xml documents that have been developed in compliance with the current schemas, these elements should not be removed in the schema updates. Instead, the following approach is proposed:

  • Keep the schemas containing the deprecated/superseded candidate types and placeholders (e.g. http://inspire.ec.europa.eu/schemas/bu/0.0/Buildings.xsd)
  • Deprecate elements with references to deprecated types (see section 2.3.1)
  • Update <targetElement> element to refer to superseded types (see section ...)

Moving types into a different package

In some cases, in the amendment of the Implementing Rules, candidate types have been moved from their initial package to another one.

EXAMPLE The type Wetland has been moved from "Land Cover" to "Hydrography – Physical Waters".

Such moves of a type T from package A (namespace: ns-a) to B (ns-b) can be implemented as a combination of the following steps:

  • keep ns-a:T unchanged in A (v0.0)
  • add type ns-b:T to B (v3.1)
  • update references

By following this approach, data created using the old schema can be made compliant with the new schema by simply changing the namespace for instances of T from ns-a to ns-b.

Deprecation of elements

Since there is no existing best practice for marking deprecated elements in xml schemas, we propose to use the <annotation> element as follows:

  • An <appinfo> element should be used to mark the element as deprecated. In order to allow specifying additional metadata about the deprecation, a boolean <deprecated> element should be defined (e.g. in the INSPIRE base types 2 schema). It is proposed to add a number of metadata attributes to the <deprecated> element: the date and version indicating since when the element was deprecated and a date after which the deprecated element is no longer supported, i.e. should no longer be used.
    <xs:element name="deprecated">
      <xs:complexType>
        <xs:simpleContent>
          <xs:extension base="xs:boolean">
            <xs:attribute name="sinceVersion" type="xs:string" use="required"/>
            <xs:attribute name="sinceDate" type="xs:date" use="required"/>
            <xs:attribute name="supportedUntil" type="xs:date" use="optional"/>
          </xs:extension>
          </xs:simpleContent>
      </xs:complexType>
</xs:element>

EXAMPLE <deprecation> element in a schema document.

<annotation>
  (...)
  <appinfo>
    <deprecated xmlns="http://inspire.ec.europa.eu/..." sinceVersion="3.1" sinceDate="2013-10-21" sup-portedUntil="2016-12-31">true</deprecated>
    <targetElement xmlns="http://www.opengis.net/gml/3.2">stat:NUTSRegion</targetElement>
  </appinfo>
</annotation>

DISCUSSION ISSUE Documenting deprecation in the schema Is it useful to include these "deprecation metadata" in the schema or is a simple string "DEPRECATED" sufficient?

EXAMPLE Deprecation using a simple string in an <appinfo> element.

<annotation>
  (...)
  <appinfo>DEPRECATED</appinfo>
  <appinfo>
    <targetElement xmlns="http://www.opengis.net/gml/3.2">stat:NUTSRegion</targetElement>
  </appinfo>
</annotation>

DISCUSSION ISSUE What deprecation metadata to include? If metadata are included, are the 3 attributes (deprecation date and version and date by when the element should no longer be used) sufficient or do we need additional ones?

DISCUSSION ISSUE Deprecation metadata - Date for supportedUntil What should be the date used for the supportedUntil attribute?

DISCUSSION ISSUE In which schema to define the <deprecated> element? If metadata are included, in which schema should the new <deprecated> element be defined – in one of the INSPIRE base type schemas, or in a new schema?

  • If there is a <documentation> element in the annotation, a warning on the deprecation should be included here in addition, e.g.
<annotation>
  <documentation>-- Definition --&#13;
NUTS region that topologically contains this administrative unit.&#13;
&#13;
-- Description --&#13;
WARNING This property has been removed in COMMISSION REGULATION (EU) No 1253/2013 (the Annex II+III amendment of the IRs). Therefore, this element is deprecated.&#13;&#13;
NOTE 1 (...) </documentation>
  (...)
</annotation>

Where there is a deprecated element is required in the original schema, it should be made optional (minOccurs="0"), e.g.

EXAMPLE The NUTS element of au:AdministrativeUnit has been removed in the IR amendment. It should thus be made optional.

<element minOccurs="0" maxOccurs="3" name="NUTS" nillable="true" type="gml:ReferenceType" />

Updating the <targetElement>

EXAMPLE The type of the Address.building property has been updated from bui:Building (package Buildings v0.0) to bu-base:AbstractConstruction (schema Buildings Base v3.0).

References to other types are implemented in the schema using gml:ReferenceType, i.e. through a URI. The type that should be returned when dereferencing this URI is described in a <targetElement> in the annotation.

EXAMPLE Reference to the bui:Building type from the Address.building property (in the Address schema v3.0)

<element name="building" type="gml:ReferenceType" nillable="true" minOccurs="0" maxOccurs="unbounded">
  <annotation>
    <documentation> (...) </documentation>
    <appinfo>
      <targetElement xmlns="http://www.opengis.net/gml/3.2">bui:Building</targetElement>
    </appinfo>
  </annotation>
</element>

Therefore, the required schema update does not affect the actual schema (the type of the property will remain gml:ReferenceType), but only the <targetElement> in the annotation. It is unclear if existing tools and applications analyse the <targetElement>. However, following the principle of only relaxing the schema during the update, it is proposed to include the new type as an additional <targetElement> to indicate that either of these types may be used.

EXAMPLE Reference to the bui:Building and bu-base:AbstractConstruction types from the Address.building property (in the proposed Address schema v3.1)

<element name="building" type="gml:ReferenceType" nillable="true" minOccurs="0" maxOccurs="unbounded">
  <annotation>
    <documentation> (...) </documentation>
    <appinfo>
      <targetElement xmlns="http://www.opengis.net/gml/3.2">bui:Building</targetElement>
      <targetElement xmlns="http://www.opengis.net/gml/3.2">bu-base:AbstractConstruction</targetElement>
    </appinfo>
  </annotation>
</element>

DISCUSSION ISSUE Include 2 <targetElement> elements or update the current ... If the <targetElement> information is not used by current tools and applications and hence a change in the type listed in this element would not break existing implementations, the <targetElement> could also simply be updated to the new type.

EXAMPLE Reference to only the bu-base:AbstractConstruction type from the Address.building property (as an alternative solution for the proposed Address schema v3.1)

<element name="building" type="gml:ReferenceType" nillable="true" minOccurs="0" maxOccurs="unbounded">
  <annotation>
    <documentation> (...) </documentation>
    <appinfo>
      <targetElement xmlns="http://www.opengis.net/gml/3.2">bu-base:AbstractConstruction</targetElement>
    </appinfo>
  </annotation>
</element>

Change of property types

EXAMPLE The type of Shore.geometry has been changed in the IR amendment from GM_Surface to GM_MultiSurface.

Following the principle of only relaxing the schema during the update, the change should be implemented using a <choice> element allowing the usage of both the old and the new type.

EXAMPLE Implementing the change of the Shore.geometry type using a <choice> element.

<sequence> 
  (...)
  <element name="geometry" type="gml:SurfacePropertyType"> 
    <annotation>
       <documentation>-- Definition --&#13;
The geometry of the shore, as a surface.&#13;
       </documentation>
  </element>
  (...) 
</sequence>

should be changed to

<sequence>

  (...)

  <choice>
    <element name="geometry" type="gml:SurfacePropertyType">
      <annotation>
        <documentation>-- Definition --&#13;The geometry of the shore, as a surface.&#13;</documentation>
        <appinfo>
          <deprecated xmlns="http://inspire.ec.europa.eu/..." sinceVersion="3.1" sinceDate="2013-10-21" noLongerSupported="2016-12-31">true</deprecated>
        </appinfo>
      </annotation>
    </element>
    <element name="geometry" type="gml:MultiSurfacePropertyType">
      <annotation>
        <documentation>-- Definition --&#13;The geometry of the shore, as a MultiSurface.&#13;
        </documentation>
      </annotation>
    </element>
  </choice>

  (...) 

</sequence>

DISCUSSION ISSUE Implement choice between GM_Surface and GM_MultiSurface f... The Shore type is also moving from the "Land Cover" to the "Hydro – Physical Waters" package. Therefore the change of type could also be simply implemented in the additional type in the updated "Hydro – Physical Waters" schema. But in this case, existing Shore data could not be made compliant to the new schema by simply changing the namespace in the instance document (cf. section 2.3.1).

Changes to mixin types

In the Annex II+III data models, new sub-types of the type HydroObject have been defined, while others have been deprecated or moved into other packages. Since HydroObject is used in multiple inheritance in the "Hydro – Network" package, it has been defined as a mixin type . In the schema, property elements for mixin classes are defined as choice elements of all their (known) sub-classes.

EXAMPLE Property type for HydroObjects (Hydro – Base schema v3.0)

<complexType name="HydroObjectPropertyType">
    <choice minOccurs="0">
      <element ref="hy-n:WatercourseSeparatedCrossing"/>
      <element ref="wfd:WFDWaterBody"/>
      <element ref="lc:Shore"/>
      <element ref="lc:Wetland"/>
      <element ref="lc:GlacierSnowfield"/>
      <element ref="hy-p:DrainageBasin"/>
      <element ref="hy-p:SurfaceWater"/>
      <element ref="hy-n:WatercourseLink"/>
      <element ref="hy-n:WatercourseLinkSequence"/>
      <element ref="nrz:InundatedLand"/>
      <element ref="hy-p:ManMadeObject"/>
      <element ref="sr:OceanRegion"/>
      <element ref="hy-n:HydroNode"/>
      <element ref="hy-p:HydroPointOfInterest"/>
    </choice>
    <attributeGroup ref="gml:AssociationAttributeGroup"/>
    <attributeGroup ref="gml:OwnershipAttributeGroup"/>
  </complexType>

The elements included in the <choice> element would need to be updated every time a new sub-type of HydroObject is created (even in a national or local extension). In order to remove this dependency and since all references to HydroObject in INSPIRE are encoded using gml:ReferenceType (i.e. the HydroObjectPropertyType property type is not used), it is proposed to simplify the definition of such mixin types to:

<complexType name="<MixinTypeName>PropertyType">
  <sequence>
    <element ref="gml:AbstractFeature"/>
  </sequence>
  <attributeGroup ref="gml:AssociationAttributeGroup"/>
  <attributeGroup ref="gml:OwnershipAttributeGroup"/>
</complexType>

Updated code list encoding

To allow data providers to use the same approach for encoding code lists for Annex I, II and III data sets, while not invalidating existing instance documents created according to the old schemas, it is proposed to change the type of code list-valued properties in the Annex I schemas to the following type (which represents a "union" of gml:CodeType and gml:ReferenceType):

<complexType name="CodeListType">
   <annotation>
      <documentation>...</documentation>
    </annotation>
    <simpleContent>
      <extension base="string">
        <attribute name="codeSpace" type="anyURI"/>
        <attributeGroup ref="gml:OwnershipAttributeGroup"/>
        <attributeGroup ref="gml:AssociationAttributeGroup"/>
      </extension>
   </simpleContent>
</complexType>

NOTE In the proposed schema updates, the changes of the types of code list-valued properties are not included.

NOTE The attribute group gml:AssociationAttributeGroup already contains the attribute nilReason : gml:NilReasonType. Therefore, for voidable properties, this attribute does not have to be explicitly added in the schema any more when using the newly defined base-cl:CodeListType.

EXAMPLE Replacing gml:CodeType with base-cl:CodeListType for voidable code list-valued properties

<element name="level" nillable="true">
  <annotation> ... </annotation>
  <complexType>
    <simpleContent>
      <extension base="gml:CodeType">
        <attribute name="nilReason" type="gml:NilReasonType"/>
      </extension>
    </simpleContent>
  </complexType>
</element>

is replaced by

<element name="level" type="base-cl:CodeListType" nillable="true">

EXAMPLE Replacing gml:CodeType with base-cl:CodeListType for non-voidable code list-valued properties

<element name="nationalLevel" type="gml:CodeType">

is replaced by

<element name="nationalLevel" type="base-cl:CodeListType">

DISCUSSION ISSUE In which schema to define CodeListType? In which schema should the new CodeListType type be defined – in one of the INSPIRE base type schemas, or in a new schema?

DISCUSSION ISSUE Versioning of schema documents with only code list updates It is proposed to publish the new versions of schema documents, in which only the type of code list-valued properties is updated, as bug fix releases (i.e. to replace the current schema documents with new schema documents including the new code list type) rather than minor releases (in a new schema location). Similar to the problem described in Versioning of importing schema documents, if these schema documents were published as minor revisions (rather than bug fixes), all schemas that import these schema documents would need to be updated too, and this would cause a cascade of schema updates