Reference

This is a specification reference for the content of an IMDF delivery.

Document Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

IMDF rules reference concepts that are nouns or noun phrases. A concept may be an “object,” e.g., a Fixture, a property held by the “object” such as an identifier, and any specific value or value-set that it possesses. A fact is a statement that connects concepts, through prepositions and verb phrases, into a set of business-related expectations. In essence, concepts and facts are the semantics behind the rules.

Features

A Feature object represents a physical or conceptual element of an indoor map as an RFC 7946 compliant GeoJSON object, with the following restrictions and additional foreign members per Sec. 6.1:

A Feature object MUST contain the GeoJSON "id" member with a FEATURE-ID value
A Feature object MUST contain a "feature_type" member with a FEATURE-TYPE value

Feature objects are used to capture ALL elements of a venue, and their structures are described throughout this document using separate sections to detail the following content:

Overview providing a description of the Feature's purpose and requirements for the names, types and semantic intent of top-level members of the Feature object
Property Keys describe the names, types and semantic intent of nested members of the GeoJSON "property" object
Examples provide individual sample Feature JSON payloads for reference, with NO description of their enclosing FeatureCollection
Guidance provides business and contextual requirements for the representation of the features and specific properties that need to be considered by map makers

Type Designators

The type designators listed below are used in descriptions throughout IMDF, but the relevant RFC or other linked documentation should be consulted for the type's formalized details where not described in this document.

Additional restrictions or requirements associated with the types are listed in dedicated sections below.

Designator	Value Type	Description
`STRING`	JSON String	A string literal value
`UUID`	`STRING`	RFC 4122, section 4.4 compliant version 4 UUID
`URI`	`STRING`	RFC 3986 compliant URI
`WEBSITE`	`URI`	RFC 3986 compliant URI with `"http"` or `"https"` scheme
`HOURS`	`STRING`	OSM Opening Hours formatted string
`PHONE`	`STRING`	E.164 compliant phone number (RFC 6116)
`ISO-639-1`	`2ALPHA`	ISO 639-1 language code
`ISO-639-2`	`3ALPHA`	ISO 639-2 language code
`ISO-3166`	`2ALPHA`	ISO 3166 alpha2 country code
`ISO-3166-2`	`STRING`	ISO-3166-2 subdivision/province code (Wikipedia)
`ISO-15924`	`4ALPHA`	ISO 15924 script code
`DATE-TIME`	`STRING`	ISO 8601 date-time with an offset (time difference in hours and minutes with UTC). Format is `yyyy-MM-ddTHH:mm:ss±hh:mm`. The offset part (`±hh:mm`) may be replaced by `Z` to denote UTC
`FEATURE-ID`	`UUID`	Canonical Feature `"id"` member value or reference
`FEATURE-TYPE`	`STRING`	Feature `"feature_type"` member value or reference
`FEATURE-REFERENCE`	JSON object	Reference to a Feature by combination of `"id"` and `"feature_type"` values
`LANGUAGE-TAG`	`STRING`	RFC 5646 compliant language tag and sub-tag, script, and region subtag registered in the IANA Language Subtag Registry
`LABELS`	JSON object	`LANGUAGE-TAG` keyed set of lexical labels
`DOOR`	JSON object	JSON object describing physical door
`TEMPORALITY`	JSON object	JSON object describing the temporal nature of an entity
`VERSION`	`STRING`	A formally supported semantic version number
`EXTENSIONS`	`STRING`	Lists formalized IMDF extensions used in the IMDF Archive

STRING

String literals and type designator values are represented as simple JSON strings per RFC 7159, Sec. 7, with the following pervasive requirements:

MUST be UTF-8 encoded
MUST NOT be an empty or blank (whitespace only) value
MUST NOT have leading or trailing whitespace characters

PHONE

Telephone numbers are provided for various Features to support an inquiry about the entity in the referenced location.

MUST NOT be a facsimile (fax) number
MUST be prefixed with a country calling code
MAY contain an extension number
MUST be complete such that a telephone connection is assured whether the caller is located inside the venue or outside of the administrative area
MUST be E.164-compliant

WEBSITE

Website URIs are provided for various Features to directly support access to information about the referenced entity.

MUST have a scheme value of "http" or "https"
SHOULD return an HTTP 200 (OK) status response when resolved

HOURS

Hours of Operation communicate a fixed or predictable (yearly) set of opening hours for a Feature.

MUST communicate the actual advertised hours of operation of the entity
MUST NOT describe weekly, bi-weekly, monthly, or temporary operating hours
MUST NOT be assumed, guessed or derived using a third-party resource (e.g. Yelp, Google, etc.)
MUST be valid per the OSM Opening Hours specification

FEATURE-ID

The canonical identifiers assigned as the "id" member value of Features have the following requirements:

Feature IDs MUST be a globally unique, RFC 4122 compliant version 4 UUID
Feature IDs MUST be retained to identify the target feature during the lifetime of its existence across distinct deliveries
Feature IDs MUST NOT be re-assigned to another Feature of any type within the target dataset or any other

FEATURE-TYPE

The value of a Feature's "feature_type" member MUST be one of the following case-sensitive values:

"address"
"amenity"
"anchor"
"building"
"detail"
"fixture"
"footprint"
"geofence"
"kiosk"
"level"
"occupant"
"opening"
"relationship"
"section"
"unit"
"venue"

FEATURE-REFERENCE

Feature references are JSON objects comprised of the target feature's "id" and "feature_type" values.

Feature references MUST contain an "id" member with a FEATURE-ID value
Feature references MUST contain a "feature_type" member with a FEATURE-TYPE value

Example

{
  "id": "11111111-1111-1111-1111-111111111111",
  "feature_type": "unit"
}

LABELS

Labels are JSON objects used to capture a single lexical label for an entity in one or more explicitly stated languages.

Labels MUST use a valid LANGUAGE-TAG as their members
Labels MUST NOT contain duplicate LANGUAGE-TAG members
Labels MUST contain a STRING value for each member
Labels MUST contain an entry in the default language

Example

{
  "en": "red",
  "es": "rojo",
  "fi": "punainen",
  "fr": "rouge",
  "it": "rosso",
  "jp": "赤"
}

{
  "en-US": "Center Pavillion",
  "en-GB": "Centre Pavillion"
}

Label Values

A Venue Organization SHOULD align their internal naming convention to the Feature property (i.e. name vs. alt_name) that best suits their internal needs and that of the map application user. The Venue Organization is responsible for defining the intended use, purpose and type(s) of content captured in a label, as they are not defined by IMDF.

Other restrictions pertaining to the label values or language tag assignment:

A label SHOULD contain the term/expression/description that is associated with the physical object or service being modeled
A label SHOULD only include enough information to concisely describe what a map needs to show in a given location
A label SHOULD reflect what is physically present in reality to support display, search and wayfinding use-cases by a pedestrian using a mapping application. A label that is not consistent with ground truth disrupts cognitive recognition
A label SHOULD NOT duplicate or be a synonym for the Feature's category (where applicable)
When a label is in a language that is not the same as the default language, but is the only label a pedestrian would view when physically present at the Venue, then the LANGUAGE-TAG member MUST correspond with the default language

TEMPORALITY

Temporality is modeled as a JSON object capturing the various temporal aspects that may be applied or relevant to an entity.

Temporality objects are JSON objects
Temporality objects MAY have a "start" member indicating the point in time at which the entity is available or considered valid
Temporality objects MAY have an "end" member indicating the point in time at which the entity is no longer available or considered valid
Temporality objects MAY have a "modified" member indicating the point in time at which the entity or temporality content was modified
Temporality DATE-TIME values SHOULD use the ISO-8601 format most appropriate for the intended purpose and context

{
  "start": "2018-06-01T00:00:00+05:00",
  "end": "2018-12-31T11:59:59+05:00",
  "modified": "2018-03-01T12:34:56+05:00"
}

DOOR

Doors are JSON objects used to capture details about the physical nature of a door

Door objects are JSON objects
Door objects MAY have a "type" member
Door objects MAY have an "automatic" member
Door objects MAY have a "material" member

`"type"`

The "type" member of a Door object indicates the physical nature of the door present at the Opening, and MUST be either null or one of the following values:

"movablepartition"
"open"
"revolving"
"shutter"
"sliding"
"swinging"
"turnstile"
"turnstile.fullheight"
"turnstile.waistheight"

If the "type" member is null, the physical nature of the door or opening is considered unspecified and MAY be rendered by a mapping application according to the default cartographic rules of that application.

`"automatic"`

The "automatic" member of a Door object indicates the manual or automatic operation of the physical door at the opening.

Value	Description
`true`	Explicit indication of automatic operation (i.e. proximity detection, continual revolving motion, etc.)
`false`	Explicit indication of manual operation (i.e. hinged door)

If the "automatic" member is null, the automatic nature of the door is considered unspecified and MAY be rendered by a mapping application according to the default cartographic rules of that application.

`"material"`

The "material" member of a Door object indicates the (primary) material used to fabricate the physical door and MAY be used for cartographic representation of the structure by a mapping application. Permissible values are as follows:

"wood"
"glass"
"metal"
"gate"

If the "material" member is null, the material from which the door is constructed is considered unspecified and MAY be rendered by a mapping application according to the default cartographic rules of that application.

Example

{
  "type": "sliding",
  "automatic": true,
  "material": "glass"
}

VERSION

The semantic version number of IMDF that a Venue dataset was constructed in compliance with is required to ensure proper processing and treatment of the data delivery.

MUST correlate to the semantic version number designated by an officially released and supported version of IMDF

Currently supported versions are limited to the following:

"1.0.0"

Geometry Type Designators

Listed below are the geometry type designators used to describe the exact nature of a Feature's spatial component(s).

Designator	Value Type	Description
`GEOMETRY`	`object`	GeoJSON `Geometry` object
`POINT`	`GEOMETRY`	GeoJSON `Point` geometry
`MULTI-POINT`	`GEOMETRY`	GeoJSON `MultiPoint` geometry
`LINE-STRING`	`GEOMETRY`	GeoJSON `LineString` geometry
`MULTI-LINE-STRING`	`GEOMETRY`	GeoJSON `MultiLineString` geometry
`POLYGON`	`GEOMETRY`	GeoJSON `Polygon` geometry
`MULTI-POLYGON`	`GEOMETRY`	GeoJSON `MultiPolygon` geometry
`POLYGONAL`	`POLYGON` or `MULTI-POLYGON`	Option of `POLYGON` or `MULTI-POLYGON` geometry
`LINEAL`	`LINE-STRING` or `MULTI-LINE-STRING`	Option of `LINE-STRING` or `MULTI-LINE-STRING` geometry
`DISPLAY-POINT`	`POINT`	`POINT` based representation of Polygonal or Lineal Features

DISPLAY-POINT

A Display Point represents a curated, Point-based representation of a non-puntal Feature.

Display Points are members of a Feature's "property" object
Display Points MUST be captured as GeoJSON Point objects
Display Points MUST be within the geometry of the Feature that possesses it
Display Points SHOULD be positioned in a location where map label "collision" is least expected

Polygon Winding Order

RFC 7946, Section 3.1.6 states the following when describing Polygons and the winding order of linear rings:

"A linear ring MUST follow the right-hand rule with respect to the area it bounds, i.e., exterior rings are counterclockwise, and holes are clockwise."

Note: the [GJ2008] specification did not discuss linear ring winding order. For backwards compatibility, parsers SHOULD NOT reject Polygons that do not follow the right-hand rule.

As a result, Features with polygonal geometries that do not follow the right-hand rule will NOT be rejected at this time, but MAY produce informative warnings if and when observed.

Horizontal Positional Accuracy

Features that explicitly reference this rule-set MUST be within +/- 5 meters of their actual ground location when tested using an independent source of higher accuracy.

The independent source of higher accuracy shall be of the highest accuracy feasible and practicable to evaluate the accuracy of the feature

Precision

Precision SHOULD be at least seven (7) decimal places.

Seven (7) decimal places is equivalent to a planar distance of ~11mm which is tolerable for mapping and surveying purposes

Referential Feature IDs

The following type designators are used to succinctly describe the use of referential Feature IDs in a non-ambiguous way by explicitly specifying the target feature layer name.

The value MUST be a valid reference to the FEATURE-ID of an existing feature in the target feature layer.

Designator	Data Type	Referenced Type
`VENUE-ID`	`FEATURE-ID`	Venue
`BUILDING-ID`	`FEATURE-ID`	Building
`LEVEL-ID`	`FEATURE-ID`	Level
`UNIT-ID`	`FEATURE-ID`	Unit
`FIXTURE-ID`	`FEATURE-ID`	Fixture
`KIOSK-ID`	`FEATURE-ID`	Kiosk
`DETAIL-ID`	`FEATURE-ID`	Detail
`SECTION-ID`	`FEATURE-ID`	Section
`GEOFENCE-ID`	`FEATURE-ID`	Geofence
`KIOSK-ID`	`FEATURE-ID`	Kiosk
`OPENING-ID`	`FEATURE-ID`	Opening
`AMENITY-ID`	`FEATURE-ID`	Amenity
`OCCUPANT-ID`	`FEATURE-ID`	Occupant
`ANCHOR-ID`	`FEATURE-ID`	Anchor
`ADDRESS-ID`	`FEATURE-ID`	Address
`RELATIONSHIP-ID`	`FEATURE-ID`	Relationship

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.

Filename	Presence	Description
`manifest.json`	Required	Manifest object
`address.geojson`	Required	FeatureCollection of all Address features
`venue.geojson`	Required	FeatureCollection of the lone Venue feature
`amenity.geojson`	Optional	FeatureCollection of all Amenity features
`anchor.geojson`	Optional	FeatureCollection of all Anchor features
`building.geojson`	Optional	FeatureCollection of all Building features
`detail.geojson`	Optional	FeatureCollection of all Detail features
`fixture.geojson`	Optional	FeatureCollection of all Fixture features
`footprint.geojson`	Optional	FeatureCollection of all Footprint features
`kiosk.geojson`	Optional	FeatureCollection of all Kiosk features
`level.geojson`	Optional	FeatureCollection of all Level features
`occupant.geojson`	Optional	FeatureCollection of all Occupant features
`opening.geojson`	Optional	FeatureCollection of all Opening features
`relationship.geojson`	Optional	FeatureCollection of all Relationship features
`section.geojson`	Optional	FeatureCollection of all Section features
`geofence.geojson`	Optional	FeatureCollection of all Geofence features
`unit.geojson`	Optional	FeatureCollection of all Unit features

Reference

Document Conventions

Features

Archives

Type Designators

STRING

PHONE

WEBSITE

HOURS

FEATURE-ID

FEATURE-TYPE

FEATURE-REFERENCE

Example

LABELS

Example

Label Values

TEMPORALITY

DOOR

"type"

"automatic"

"material"

Example

VERSION

Geometry Type Designators

DISPLAY-POINT

Polygon Winding Order

Horizontal Positional Accuracy

Precision

Referential Feature IDs

Extending IMDF

Extension Guidelines

Validation of Extensions

Conflict Awareness

Example

`"type"`

`"automatic"`

`"material"`