MVF v2 Data Model

Mappedin Venue Format (MVF) v2 is currently in an alpha state while Mappedin perfects a new design. Breaking changes may occur and this page will be updated to reflect this.

The following changes have occurred to the beta specification:

Oct 2024: MapStack mapstack.geojson was renamed to FloorStack floorstack.geojson.

Oct 2024: Map map.geojson was renamed to Floor floor.geojson.

The Mappedin Venue Format (MVF) bundle contains a number of GeoJSON and JSON files which describe the geometry of the map and suggest how it should be rendered. These files are grouped into Core (necessary geometry) and Extensions (render styles).

Core

The core data models of an MVF are the essential files required to render a building. They iclude Connection, Entrance, FloorStack, Floor, Manifest, Node, Obstruction and Space.

Connection

connection.json

A connection is a mechanism that facilitates traversal between levels, such as a staircase or an elevator. The connection.json file contains a array of the connections for the entire building.

Property	Description	Optional
id	A unique string identifier beginning with c_.	No
type	Possible values include "stairs" or "elevator".	No
nodes	A string array of node identifiers which are part of this this connection.	No
externalId	A string identifier which links this connection to an external service.	No
accessible	A boolean indicating whether or not this connection is wheelchair accessible.	Yes
metadata	An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed.	Yes

Entrance

entrance/m_*.geojson

An entrance is an opening in the wall which facilitates traversal between two spaces. Entrances are represented in FeatureCollections of GeoJSON LineStrings. They are split up by map ID within the entrance directory.

Property	Description	Optional
id	A unique string identifier beginning with e_.	No
externalId	A string identifier which links this entrance to an external service.	No
node	A string identifier of a node associated with this entrance.	Yes
details	A Details object containing additional information about an entrance.	Yes
details	An optional object containing additional properties. See Details.	Yes
metadata	An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed.	Yes

FloorStack

floorstack.json

A floor stack is a collection of maps for each floor in a building. The floorstack.json file contains an array of floors.

Property	Description	Optional
id	A unique string identifier beginning with fs_.	No
externalId	A string identifier which links this map stack to an external service.	No
name	A string containing the name of this map stack.	No
maps	A string array of map identifiers which are part of this this stack.	No
metadata	An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed.	Yes

Floor

floor.geojson

A floor is a level or floor within a floorstack. The floor.geojson file contains an array of maps for the current floorstack.

Property	Description	Optional
id	A unique string identifier beginning with f_.	No
externalId	A string identifier which links this map stack to an external service.	No
elevation	The elevation of the floor. Typically 0 is the ground floor. Negative values are below ground and positive values are above ground	No
name	A string containing the floor name.	No
shortName	A string containing the short floor name.	No
geometry	An object of of type Polygon, MultiPolygon or null with an array of coordinates.	Yes

Manifest

manifest.geojson

The manifest is a GeoJSON FeatureCollection containing a single feature. This feature has a Point property called geometry which is roughly the center point of the MVF. The manifest properties describe the MVF bundle.

Property	Description	Optional
name	A string containing the name of the building.	No
org_id	A unique string identifier for the organization which owns the building.	Yes
folder_struct	An array of objects describing the files and folders contained in the MVF bundle.	No
version	A string containing the MVF version.	No
time	An ISO 8601 date-time string, including timezone offset.	No

Node

node.geojson

Nodes are not included in an MVFv2 downloaded using the Mappedin Editor. They are included when downloadedusing the Mappedin REST API.

A node is a point on a floor that is used to create a path from a starting location to a destination. Nodes may be linked to other nodes which is represented by the neighbors property. The node.geojson file contains a FeatureCollection

Property	Description	Optional
id	A unique string identifier beginning with n_.	No
externalId	A string identifier which links this node to an external service.	No
map	A string identifier of the map this node is found on.	No
space	A string array of space identifiers which this node map be contained within.	No
neighbors	An array of objects identifying traversable nearby nodes. See Neighbor.	No

Obstruction

obstruction/m_*.geojson

An obstruction is a non-traversable area (e.g. desk or chair), meaning a path will never be created through an obstruction. Obstructions are represented in FeatureCollections of GeoJSON Polygons or LineStrings. They are split up by floor ID within the obstruction directory.

Property	Description	Optional
id	A unique string identifier beginning with o_.	No
externalId	A string identifier which links this obstruction to an external service.	No
kind	object	Yes
footprintComponent	A boolean indicating whether this obstruction is considered part of the footprint of the building it is a part of. For example, an exterior wall would be considered part of the building footprint.	Yes
center	The center of mass of this obstruction, if it is a polygon. This is undefined for line strings as this can be trivially derived.	Yes
entrances	A string array of entrance identifiers which can be used to navigate through this obstruction.	No
details	An optional object containing additional properties. See Details.	Yes
metadata	An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed.	Yes

Space

space/m_*.geojson

A space is traversable and enclosed with walls, such as a room or hallway. Spaces are represented in FeatureCollections of GeoJSON Polygons, LineStrings, or Points. They are split up by floor ID within the space directory.

Property	Description	Optional
id	A unique string identifier beginning with s_.	No
externalId	A string identifier which links this space to an external service.	No
kind	Possible values include "default", "hallway", "exterior", "void", "connection.stairs", "connection.elevator", or "poi".	Yes
details	An optional object containing additional properties. See Details.	Yes
metadata	An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed.	Yes

Enterprise Data Types

Enterprise Data Types include additional data specific to Enterprise Tier maps.

Venue

enterprise/venue.json

A Venue is the most top level data model that encompasses all other enterprise data models.

Property	Description	Optional
name	A string that represents the name of the venue.	No
slug	A string that represents a human-readable unique identifier for the venue.	No
externalId	A string identifier which links this space to an external service.	No
defaultLanguage	A object containing strings code and name, representing the default language code and name.	No
languages	An array of objects containing string code, string name and boolean enabled representing a supported language code, name and whether it is enabled.	No
icon	A string that contains the URL of the venue's icon.	Yes
logo	A string that contains the URL of the venue's logo.	Yes
mappedinWebUrl	A string that contains the URL to a Mappedin Web v2 instance of the map.	Yes
defaultMap	A string that contains the default floor Id.	No
countrycode	A string that contains the country code of the venue's location.	No
tzid	A string that contains venue's time zone.	No
topLocations	An array of string that contains the location Ids of the venue's top locations.	Yes

Categories

enterprise/categories.json

A category is used to group of locations with shared characteristics, such as Restaurants or Meeting Rooms.

Property	Description	Optional
id	A unique string identifier beginning with ec_.	No
name	A string that represents the name of the category	No
externalId	A string identifier which links this space to an external service.	No
sortOrder	A number indicating the category's sort position.	No
iconFromDefaultList	A string identifying the icon used for the location's label.	No
locations	An array of locations within this category.	No
children	An array of child categories of this category.	Yes
color	The color to be used when labelling this location.	No

Locations

enterprise/locations.json

A location is a place of interest that is linked to a Space, such as a store or meeting room. Locations do not contain geometry.

Property	Description	Optional
id	A unique string identifier.	No
name	A string that represents the name of the location.	Yes
type	The location type, i.e. “tenant" or "amenity".	No
externalId	A string identifier which links this space to an external service.	No
sortOrder	A number indicating the location's sort position.	No
polygons	An array containing map and id, representing the floor ID and space ID where the location exists.	Yes
nodes	An array containing map and id, representing the floor ID and node ID where the location exists.	Yes
description	A string containing the location's description.	No
logo	A string that contains image urls for the logo of the location.	Yes
phone	An object that contains the phone numbers of the location	Yes
showFloatingLabelWhenImagePresent	An boolean representing whether floating labels should be shown.	No
states	An object containing strings of type, start and end that contain temporary closure information for the location.	Yes
social	An object that contains social media urls of the location	Yes
tags	An array of strings containing tags for the location that could be used when searching or filtering.	yes
operationHours	An array of objects that contain the hours of operation of the location.	Yes
gallery	An array of URLs to gallery images.	Yes

Extensions

Extensions are additional data models which describe how an MVF should be rendered and other properties not essential to the building geometry. Extensions are Annotation, Shapes, ShapeInstances, Styles, Polygons, LineStrings and Window.

Annotation

annotation/m_*.geojson

Property	Description	Optional
id	A unique string identifier beginning with a_.	No
symbolId	A string identifier for the annotation symbol to be displayed.	No

Floor Images

floorImages/f_*.json

The floor images files contain a list of images to be drawn on spaces. The filename will match the ID of the floor its images belong to. The images are organized in the JSON file as an array of features, which contain a Point with the image's latitude and longitude coordinates. They also contain a properties field that contains the following data.

Floor Images Properties

Property	Description	Optional
anchorId	A string containing the id of the space the image should be anchored to.	No
rotation	A number containing the degrees the image should be rotated.	No
path	A string containing a URL to the image.	No
width	A number containing the width of the image.	No
height	A number containing the height of the image.	No

Shapes

shapes.json

For future use, not currently used.

Property	Description	Optional
geometry	An array of number tuples for each vertex in a local coordinate system, measured in metres.	No
altitude	A number indicating how far off the "ground" the shape is, in metres.	No
height	A number indicating the height of the shape, in metres.	No

ShapeInstances

shapeInstances/m_*.json

For future use, not currently used.

Property	Description	Optional
id	A unique string identifier beginning with sh_.	No
material	An object describing the appearance of this shape instance. See Material.	No

Styles

styles.json

Styles are non-essential properties which describe how the GeoJSON geometry should be rendered. The style.json file contains key-value pairs of styles. The key is a user-defined string and can be any value. The value is an object containing properties depending on the GeoJSON type.

Default

These style properties are available for all GeoJSON types.

Property	Description	Optional
altitude	A number indicating how far off the "ground" the objects belonging to this layer should be drawn, in metres.	No
color	A string containing a hex code beginning with #.	No
height	A number indicating the height of the objects belonging to this layer, in metres.	No
opacity	A number between 0 and 1 indicating the opaqueness of objects belonging to this layer.	No

Polygons

These style properties apply only to GeoJSON Polygons.

Property	Description	Optional
polygons	A string array of obstruction or space identifiers which this style applies to.	No

LineStrings

These style properties apply only to GeoJSON LineStrings.

Property	Description	Optional
width	A number indicating how far off the "ground" the objects belonging to this layer should be drawn, in metres.	No
lineStrings	A string array of entrance, obstruction, or space identifiers which this style applies to.	No

Window

window/m_*.geojson

A window is a non-traversable cutout in an wall, meaning a path will never be created through a window. Windows are represented in FeatureCollections of GeoJSON LineStrings. They are split up by floor ID within the window directory.

Property	Description	Optional
id	A unique string identifier beginning with w_.	No

Additional Data Types

Additional data types provide further information about a map. They are made up of Details, Neighbor, Material and Texture.

Details

Additional information about a given entity.

Property	Description	Optional
name	Name of the entity.	Yes
description	Description of the entity.	Yes
links	An array of objects containing properties url and optional displayName.	Yes
images	An array of objects containing properties url and optional altText.	Yes

Neighbor

A traversable node neighbour.

Property	Description	Optional
flags	A string containing special properties for this node.	No
id	The string identifier of the node.	No
weight	The cost of navigating to this node. Minimum is 0.	Yes

Material

The color and/or texture that should be applied to an instance of a Shape.

Property	Description	Optional
color	A string containing a hex code beginning with #.	Yes
texture	An object describing the texture properties of the material. See Texture.	Yes

Texture

A reference to an image texture and how it should be applied to a component.

Property	Description	Optional
path	The path to this asset, relative to the MVF's images folder.	No
repeat	An object describing how the texture should be placed on a component. Its properties are a number u and a number v.	Yes