Extending IMDF

IMDF supports formalized extension by declaring new Feature types or additional foreign members and properties of existing Feature types for use in capable or interested environments.

Extension Guidelines

• MUST conform to the GeoJSON format, with the restrictions and additions defined in IMDF specification

• MAY define new Feature types, in conformance with the definition of Feature objects as described in IMDF specification

• MAY define new foreign members and properties for existing Feature types

• MUST NOT change the semantics of Feature types, Feature members or properties as defined in IMDF specification

• The Manifest object MAY contain an extensions member. If present, the value MUST be an array of Extension Identifier strings

• Extension Identifier strings MUST conform to the following ABNF rule

extension_identifier = "imdf:extension:" provider ":" name "#" version
extension_part       = (ALPHA / DIGIT) [ *VALIDCHAR (ALPHA / DIGIT) ]
provider             = extension_part
name                 = extension_part
version              = extension_part
VALIDCHAR            = ALPHA / DIGIT / "." / "-" / "_"

For example, imdf:extension:big-company:internal#1.0.0 is the identifier of an extension called "internal", defined by the provider "big-company", for version "1.0.0".

Validation of Extensions

• MAY define new validation rules

• MUST NOT alter the definition of an existing validation defined in IMDF specification

• New validation rules MAY refine validations defined in IMDF specification, provided that they do not contradict them. For example, an extension may define a new rule that restricts the length of the value strings in Label objects, but it cannot define a new rule that allows the keys in Label objects to be something else than valid LANGUAGE-TAGs

• Extension validations MUST NOT be run if the corresponding Extension Identifier is not present in the extensions array in the Manifest object

Conflict Awareness

Different extensions may define new Feature types, foreign members and properties with the same name. This specification does NOT address how conflicts caused by their concurrent use in the same archive should be resolved.

Example

Let's assume that Big Company wants to associate an internal identifier to all units of category "office". That identifier is called "office_id", and its value is expected to be a string starting with an uppercase "O" followed a dash character and five digits. In order to do that, Big Company defines the extension "internal":

• Extension identifier is set to be imdf:extension:big-company:internal#1.0.0 (1.0.0 meaning that it is the first version of the internal extension specification)

• Extension identifier will be present in the extensions array in the manifest:

{
  "version": "1.0.0",
  "created": "2020-09-09T12:34:56",
  "language": "en-US",
  "generated_by": null,
  "extensions": [ "imdf:extension:big-company:internal#1.0.0" ]
}

• Extension then specifies that Unit features may have a new property called "office_id"

{
  "id": "11111111-1111-1111-1111-111111111111",
  "type": "Feature",
  "feature_type": "unit",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [100.0, 0.0],
        [101.0, 0.0],
        [101.0, 1.0],
        [100.0, 1.0],
        [100.0, 0.0]
      ]
    ]
  },
  "properties": {
    "category": "office",
    "office_id": "O-72551",
    "restriction": null,
    "accessibility": null,
    "name": {
      "en": "Ball Room"
    },
    "alt_name": null,
    "display_point": {
      "type": "Point",
      "coordinates": [ 100.0, 1.0 ],
    },
    "level_id": "22222223-2222-2222-2222-222222222222"
  }
}

• Finally, the extension specifies the following validation rules:
  • OfficeIdMustBeValid validates that "office_id" values must be strings that conform to the expected format (an uppercase "O" followed by a dash character and five digits)
  • OfficeIdsMustBeUnique validates that two Units must not have the same value for "office_id"
  • OfficeUnitMustHaveOfficeId validates that Units of category "office" have "office_id" among their properties