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
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
DOOR JSON object JSON object describing physical door
EXTENSIONS STRING Lists formalized IMDF extensions used in the IMDF Archive
FEATURE-ID UUID Canonical Feature "id" member value or reference
FEATURE-REFERENCE JSON object Reference to a Feature by combination of "id" and "feature_type" values
FEATURE-TYPE STRING Feature "feature_type" member value or reference
HOURS STRING OSM Opening Hours formatted string
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
LABELS JSON object LANGUAGE-TAG keyed set of lexical labels
LANGUAGE-TAG STRING RFC 5646 compliant language tag and sub-tag, script, and region subtag registered in the IANA Language Subtag Registry
PHONE STRING E.164 compliant phone number (RFC 6116)
STRING JSON String A string literal value
TEMPORALITY JSON object JSON object describing the temporal nature of an entity
URI STRING RFC 3986 compliant URI
UUID STRING RFC 4122, section 4.4 compliant version 4 UUID
VERSION STRING A formally supported semantic version number
WEBSITE URI RFC 3986 compliant URI with "http" or "https" scheme

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"
}

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 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"
}

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"

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

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

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

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

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

Example

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

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

NOTE: Currently supported versions are limited to the following:
"1.0.0"

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