Map data schema

A Mapplic map is described by a single JSON object — the map data. It holds the map’s settings, its layers and locations, and every supporting structure (filters, groups, styles, legend, breakpoints, languages and routes).

This page is the canonical reference for that object and each of its parts. To read or change this data at runtime see the JavaScript API.

💡

Location data can also be supplied as CSV and merged into the JSON — see the csv, csvEnabled and csvMerge settings.

Structure

The top-level map data object:

Property	Type	Description
`settings` *	`MapSettings`	All map configuration. See Settings.
`layers` *	`Layer[]`	The map’s layers (SVG or image). At least one is required.
`locations`	`Location[]`	Location markers placed on the layers.
`presets`	`Location[]`	Reusable location templates referenced by `preset`. See Presets.
`groups`	`Group[]`	Categories used to group and filter locations.
`filters`	`Filter[]`	Filter controls shown in the directory.
`legend`	`LegendItem[]`	Legend entries.
`styles`	`Style[]`	Reusable appearance styles for SVG elements and markers.
`breakpoints` *	`Breakpoint[]`	Responsive layout breakpoints.
`languages`	`Language[]`	Available languages for localization.
`translations`	`Translation[]`	Translation strings per language.
`routes`	`Path[]`	Wayfinding route segments.

Properties marked * are required. Everything else is optional.

Settings

The settings object holds the map’s configuration, grouped by area below. Options marked * are required; everything else is optional. Settings whose value belongs to a fixed set link to the enums.

Layers and map

Name	Setting	Description
Map id	`mapId`	Identifier of the map.
Map width	`mapWidth` *	Native width of the map (SVG/image) in pixels.
Map height	`mapHeight` *	Native height of the map (SVG/image) in pixels.
Layer	`layer`	Id of the layer shown first.
Layer switcher	`layerSwitcher`	Configures the layer switcher control.
Geo	`geo`	Enable geographic (latitude/longitude) positioning.
Extent	`extent`	Geographic bounds used to map `latlon` to map coordinates.

Locations and CSV

Name	Setting	Description
CSV source	`csv`	URL of a CSV file that provides location data.
CSV enabled	`csvEnabled`	Load locations from the CSV source.
CSV merge	`csvMerge`	On a duplicate `id`, overwrite the matching JSON location’s fields with the CSV values. When off, the duplicate CSV row is ignored (the JSON location is kept). CSV-only locations are added either way.

Search and filters

Name	Setting	Description
Search	`search`	Enable the location search box.
Filters	`filters`	Show filter controls.
Always visible	`filtersAlwaysVisible`	Keep the filters expanded and always visible.
Opened	`filtersOpened`	Open the filters panel initially.
Auto collapse	`filtersAutoCollapse`	Collapse the filters automatically after interacting with the map.

Name	Setting	Description
Directory	`directory`	Show the location directory. Replaces the deprecated `sidebar`.
Toggle directory	`toggleDirectory`	Let the user show/hide the directory.
Directory closed	`directoryClosed`	Start with the directory collapsed.
Ordered	`ordered`	Sort directory entries alphabetically.
Group by	`groupBy`	Group directory entries: `groups` or `alphabetic` (see enums).
Collapsible groups	`collapsibleGroups`	Allow collapsing directory groups.
Directory counts	`directoryCounts`	Show item counts on group headers.
Image as thumbnail	`imageAsThumb`	Use the location `image` as its directory thumbnail.
Right sidebar	`rightSidebar`	Place the sidebar on the right.
Filter by layer	`filterByLayer`	Only list locations from the active layer.

Map interaction

Name	Setting	Description
Accessibility	`accessibility`	Enhance keyboard and screen-reader accessibility.
Fullscreen	`fullscreen`	Position of the fullscreen button: top-left, top-right, bottom-left, bottom-right, or omit to disable.
Hover tooltip	`hoverTooltip`	Show a tooltip when hovering a location.
Show about in	`showAboutIn`	Where to show a location’s `about` text: `tooltip`, `hover`. Replaces the deprecated `hoverAbout`.
Show thumb in	`showThumbIn`	Where to show thumbnails: `tooltip`, `hover`, `directory`. Replaces the deprecated `thumbnails`.
Deeplinking	`deeplinking`	Sync state to URL query parameters — `true`, or an array of `location`, `group`, `wayfinding`.
Scroll top	`scrollTop`	In portrait mode, a vertical scroll offset so a fixed header doesn’t cover the map when it scrolls into view.
Reduce motion	`reduceMotion`	Honor the user’s reduced-motion preference.
Kiosk	`kiosk`	Kiosk mode: fill the viewport and limit some interactions.

Zoom and pan

Zooming and panning enhance visibility over static, fixed-size maps. Turning zoom off is possible when the map is clear enough not to need enlarging.

Name	Setting	Description
Zoom	`zoom`	Enable zooming and panning.
Max zoom	`maxZoom` *	Maximum zoom level; `1` is the fit scale (map fits the container).
Padding	`padding`	Extra padding (in pixels) around the map when zoomed all the way out.
Initial area	`initArea`	Area visible on load, as `[x1, y1, x2, y2]`.
Reset button	`resetButton`	Position of the reset button: top-left, top-right, bottom-left, bottom-right, or omit to disable.
Zoom buttons	`zoomButtons`	Position of the +/- buttons (same positions as above) or omit to disable.
Mousewheel	`mouseWheel`	Enable/disable mousewheel zooming.
Shift key	`mouseWheelShift`	Require the Shift key for mousewheel zooming.
Close reset	`closeReset`	Reset the zoom when a location is closed (loses focus).

Appearance

Name	Setting	Description
Primary color	`primaryColor`	Primary accent color (light theme).
Primary color (dark)	`primaryColor_dark`	Primary accent color (dark theme).
Theme	`theme`	Initial color theme.
Invert popup theme	`invertPopupTheme`	Invert the popup’s theme for contrast.
Rounding	`rounding`	Corner radius (in pixels) for UI elements.
Animations	`animations`	Animation level: `full` or `reduced`.
Custom CSS	`css`	Custom CSS injected into the map. See the Appearance guide.

Localization

Name	Setting	Description
Language	`language`	Default language code.
Localization	`localization`	Show the language switcher.

Legend

Name	Setting	Description
Legend	`legend`	Show the legend.
Position	`legendPos`	Legend position on the map.
Title	`legendTitle`	Legend heading text.
Toggle	`legendToggle`	Allow collapsing the legend.
Closed	`legendClosed`	Start with the legend collapsed.
Columns	`legendColumns`	Number of legend columns.

Live opening hours

Drives the open/closed status from each location’s hours.

Name	Setting	Description
Live opening hours	`liveOpeningHours`	Show live open/closed status.
Timezone	`timezone`	IANA timezone used to evaluate hours.
Opening notice	`openingNotice`	Lead time to flag “opening soon”: `1h`, `30m`, `15m`. Defaults to `1h`.
Closing notice	`closingNotice`	Lead time to flag “closing soon”: `1h`, `30m`, `15m`. Defaults to `1h`.
Hours display	`hoursDisplay`	How hours are shown: `button` or `inline`. Defaults to `button`.
Week start	`weekStart`	First day of the week: `dynamic`, `monday`, `sunday`. Defaults to `dynamic`.

Wayfinding

💡

Wayfinding is a Professional-plan feature.

Name	Setting	Description
Wayfinding	`wayfinding`	Enable A→B wayfinding.
Controls	`wayfindingControls`	Position of the wayfinding controls (top-left … bottom-right) or `false`.
Opened	`wayfindingOpened`	Open the wayfinding panel initially.
Line width	`wayfindingLineWidth`	Route line width in pixels.
Line color	`wayfindingLineColor`	Route line color.
Speed	`wayfindingSpeed`	Route animation speed.
Smoothing	`wayfindingSmoothing`	Path smoothing amount.
Fixed from	`wayfindingFixedFrom`	Fixed starting location id.
Fixed from position	`wayfindingFixedFromPos`	Position of the fixed-start control or `false`.
Accessibility	`wayfindingAccessibility`	Prefer step-free routes.

Analytics

Name	Setting	Description
Analytics	`analytics`	Enable analytics tracking.
Analytics URL	`analyticsUrl`	Custom analytics endpoint URL.

Advanced

Name	Setting	Description
Enable all links	`enableAllLinks`	Allow all location links, overriding link restrictions.

Responsivity

A distinct layout can be configured at an unlimited number of breakpoints. Each breakpoint is a Breakpoint entry in the map data.

The breakpoint name is added to the component as a CSS class, so it can also be used for custom styling. For example, to hide the layer switcher on mobile:


.mobile .mapplic-layer-switcher {
    display: none;
}

Deprecated aliases

These older keys still work but should be replaced:

Deprecated	Use instead
`sidebar`	`directory`
`toggleSidebar`	`toggleDirectory`
`sidebarClosed`	`directoryClosed`
`thumbnails`	`showThumbIn`
`hoverAbout`	`showAboutIn`

Layer

A layer is one SVG file or raster image. The map renders one layer at a time; the layer switcher lets the user move between them.

Property	Type	Description
`id` *	`string`	Unique layer identifier.
`name` *	`string`	Display name, shown in the layer switcher.
`file`	`string`	URL or path to the SVG/image file.
`switchReset`	`boolean`	Close the open location and reset the zoom when switching to or from this layer.
`disable`	`boolean`	Disable the layer — removed from the switcher, and its locations are not shown.

Location

A location is an interactive marker. Only id is required; presets and custom fields make the rest flexible. See the Locations guide for the task-oriented walkthrough.

Property	Type	Description
`id` *	`string`	Unique location identifier. Matches the SVG element id for interactive vector locations.
`preset`	`string`	Id of a preset to inherit values from.
`title`	`string`	Location name.
`about`	`string`	Short description shown in the tooltip/hover.
`desc`	`string`	Longer rich-text description shown in the popup.
`thumb`	`string`	Thumbnail image URL.
`image`	`string`	Full image URL shown in the popup.
`imagePlacement`	`'background'`	Render `image` as the popup background.
`enlargeableMedia`	`boolean`	Allow popup media to be opened full-size.
`popupThumb`	`boolean`	Show the thumbnail inside the popup.
`action`	`LocationAction`	What happens on click (popup, redirect, switch layer, …).
`popupType`	`PopupType`	Where/how the popup is displayed.
`link`	`string`	URL opened for the `redirect` action or the “more” link.
`target`	`string`	Link target, e.g. `_blank`.
`more`	`string`	Custom label for the link button.
`tags`	`string \| string[]`	Tags used by filters and search.
`group`	`string \| string[]`	Group name(s) this location belongs to.
`layer`	`string \| string[]`	Layer(s) the location appears on.
`coord`	`number[]`	`[x, y]` position on the map.
`latlon`	`number[]`	`[lat, lon]` position for geo-calibrated maps.
`zoom`	`number`	Zoom level applied when the location is opened.
`switch`	`string`	Layer id to switch to (for the `switch-layer` action).
`color`	`string`	Marker/accent color.
`style`	`string`	Name of a style to apply.
`scaleMode`	`'screen' \| 'map'`	Whether the marker scales with the screen or the map.
`hours`	`string`	Opening-hours definition (used by live opening hours).
`phone`, `email`, `link`	`string`	Contact details.
`facebook`, `instagram`, `youtube`, `gmaps`	`string`	Social / maps links.
`crowding`	`string`	Crowding mode resolving marker overlap — `hide`, `minimize`, `resize`, `uniform`, or `cluster`.
`ignoreMapFilters`	`boolean`	Exclude the location from filtering.
`autoroute`	`boolean`	Generate a wayfinding route automatically.
`hide`	`boolean`	Hide the location from the directory (it stays on the map).
`disable`	`boolean`	Disable the location — no marker is rendered and its SVG element is not interactive.

💡

Locations may carry custom fields — any extra key beyond those above is preserved and available in popup/directory templates. See the Locations guide.

Marker configuration

These marker properties may be set on a location (or on a preset):

Property	Type	Description
`noMarker`	`boolean`	Don’t render a marker pin (interactive area only).
`markerThumb`	`boolean`	Use the thumbnail image as the marker.
`markerTitle`	`'left' \| 'right' \| 'bottom' \| 'dynamic'`	Position of the always-visible title label.
`markerStyle`	`string`	Name of a style applied to the marker.
`label`	`string`	Short text drawn on the marker.
`icon`	`string`	Icon/SVG id drawn in the marker.
`radius`	`number`	Marker radius in pixels.
`scale`	`number`	Marker size multiplier.
`rotation`	`number`	Marker rotation in degrees.

Presets

presets is an array of Location objects used as templates. A location with a preset field inherits all of the named preset’s values, then overrides them with its own. This keeps repeated markers (e.g. every “restroom”) consistent and editable in one place.

Group

Groups categorize locations for the directory and the tags filter.

Property	Type	Description
`name` *	`string`	Group identifier, referenced by `Location.group`.
`title`	`string`	Display name.
`color`	`string`	Group color.
`icon`	`string`	Group icon.
`hide`	`boolean`	Hide the group in the directory.

Filter

A filter is a control in the directory. Its type selects the behaviour — see FilterType. See the Directory guide for usage.

Property	Type	Description
`id` *	`string`	Unique filter identifier.
`type` *	`FilterType`	`checkbox`, `tags`, `alphabetic`, `dropdown` or `toggle`.
`name`	`string`	Display name.
`showName`	`boolean`	Show the filter’s name as a label.
`value`	`string`	Internal filter value.
`logic`	`string`	Matching logic/condition.
`include`	`string \| string[]`	Restrict the filter to these values.
`default`	`string \| string[]`	Value(s) selected by default.
`single`	`boolean`	Allow only one selection at a time.
`inline`	`boolean`	Render inline.
`toggleLayout`	`boolean`	Use the chip/toggle layout.
`disable`	`boolean`	Hide the filter.

Style

A style is a named, reusable set of appearance properties applied to SVG elements or markers across three states — base, hover and active. See the Appearance guide.

Property	Type	Description
`class` *	`string`	Style name; the SVG/marker references it.
`svg`	`boolean`	Apply to matching SVG elements.
`marker`	`boolean`	Apply to matching markers.

State properties follow the pattern {state}-{property}, where {state} is base, hover or active:

Suffix	Type	Description
`-color`	`string`	Fill color. A `_dark` variant (e.g. `base-color_dark`) sets the dark-theme color.
`-stroke`	`string`	Stroke color (`_dark` variant supported).
`-stroke-width`	`string`	Stroke width.
`-text`	`string`	Text color (`_dark` variant supported).
`-effects`	`string[]`	Named visual effects.
`-css`	`string`	Raw CSS applied in that state.
`-bring-to-front`	`boolean`	Raise the element above others (`hover`/`active` only).

Two base keys are irregular: the base stroke width is stroke-width (not base-stroke-width), and the base text color is text-color (not base-text).

Legend item

Property	Type	Description
`id` *	`string`	Unique legend item identifier.
`text`	`string`	Label text.
`color`	`string`	Swatch color.
`icon`	`string`	Swatch icon.
`selector`	`string`	CSS selector the item highlights.
`action`	`string`	Action triggered when the item is clicked.
`default`	`boolean`	Active by default.
`scale`	`number`	Swatch size.
`radius`	`number`	Swatch radius.
`disable`	`boolean`	Hide the item.

Breakpoint

Breakpoints define responsive layout at decreasing viewport widths. Also described, with a custom-CSS example, under Responsivity.

Property	Type	Description
`name` *	`string`	Unique name; also added to the map element as a CSS class.
`below`	`number`	Applies when the container width falls below this pixel value.
`portrait`	`boolean`	Use the portrait (stacked) layout instead of the sidebar layout.
`container`	`number`	Map container height in pixels.
`sidebar`	`number`	Sidebar width in pixels (landscape layout).
`type`	`'list' \| 'grid'`	Directory display type.
`column`	`number`	Number of directory columns.
`element`	`number`	Component height in portrait mode (map + directory).

Language

Property	Type	Description
`code` *	`string`	Language code, e.g. `en`, `de`, `fr`.
`name`	`string`	Display name.
`flag`	`string`	Flag emoji or icon.

Translation

Each translation maps an original UI string to its translated value per language code.

Property	Type	Description
`orig` *	`string`	The original (source) string.
`[code]`	`string`	Translated value for each language `code` (e.g. `de`, `fr`).

Path

The routes array holds Path objects — individual route segments used by wayfinding.

Property	Type	Description
`id` *	`string`	Unique route identifier.
`layer`	`string`	Layer the segment belongs to.
`points`	`string`	SVG points describing the path.
`element`	`string`	SVG element id the path is drawn from.
`endpoint`	`string`	Location id this segment connects to.
`connect`	`boolean`	Mark the path as a layer connector — see Multi-layer support.
`weight`	`string`	Traversal cost/weight.
`inaccessible`	`boolean`	Mark the segment as not step-free.
`oneway`	`'>' \| '<'`	One-way direction along the points.

Enums

Several fields and settings accept a fixed set of values:

Type	Values	Used by
`LocationAction`	`none`, `popup`, `switch-layer`, `redirect`, `media`	`Location.action`
`PopupType`	`map`, `directory`, `container-left`, `container-right`, `container-bottom`, `container-center`	`Location.popupType`
`FilterType`	`checkbox`, `tags`, `alphabetic`, `dropdown`, `toggle`	`Filter.type`
`ControlZone`	`false`, `top-left`, `top-right`, `bottom-left`, `bottom-right`	`resetButton`, `zoomButtons`, `wayfindingControls`, …
`GroupMode`	`groups`, `alphabetic`	`groupBy`
`Animations`	`full`, `reduced`	`animations`
`DeeplinkingKeys`	`location`, `group`, `wayfinding`	`deeplinking`
`HoursDisplay`	`button`, `inline`	`hoursDisplay`
`WeekStart`	`dynamic`, `monday`, `sunday`	`weekStart`
`LiveHourStatusChangeNotice`	`1h`, `30m`, `15m`	`openingNotice`, `closingNotice`
`AboutLocation`	`tooltip`, `hover`	`showAboutIn`
`ThumbLocation`	`tooltip`, `hover`, `directory`	`showThumbIn`