Each CleverMaps project consists of data and metadata.

In metadata, we configure the user interface, create the data model, define metrics, define map visualizations, etc.

All metadata are written using JSON format. JSON is designed to be human-readable, and basic understanding of JSON is enough to work with CleverMaps metadata.

Metadata objects

All object types are based on a template and share a common syntax. Each type extends this syntax with its own specific keys. It contains useful keys like id, name or description and is further described in the common syntax article.

There are 13 types of metadata objects which can be divided into 2 groups:

  • public metadata objects - these are exposed to user in project dump when using CleverMaps Shell and thus can be directly created, fetched, updated or deleted

    • dashboards are ordered lists of indicator and indicator drill pairs

    • datasets describe the data model, the links and the constraints of all database tables

    • data permissions refine data access to specific data for users on the level of database rows

    • exports define set of dataset properties to be included in an exported file

    • indicators describe a phenomena - the visualisation of a metric on a map

    • indicator drills define more detailed components of an indicator for better analysis and understanding of the phenomenon it describes

    • markers define the type and style of map markers which are displayed in the map window

    • marker selectors define groups of map markers and combine them with datasets

    • metrics provide a formal way to define the actual computations which will be performed on the project data

    • project settings object is used to define project specific features

    • views is a visualization of certain theme using a set of related indicators and groups of objects displayed on a map

  • internal metadata objects - these are not exposed to user in project dump when using CleverMaps Shell and thus cannot be directly created, fetched, updated nor deleted

    • shares persist the state of the application when using the Share function

    • bookmarks is a persistent version of a Share object. Bookmarks has been deprecated in favor of “personal saved views” functionality. See Project settings - Default views for more info.

Visualization of the model

This is the basic overview of the model. As you can see, the model is built around datasets - other objects mostly process and/or visualise their data in some way.

The objects have references between them. There are two types of references:

  • by URI link reference

    • e.g. "indicator": "/rest/projects/$projectId/md/indicators?name=customers_indicator"

  • by reference to dataset property

    • e.g. "property": "shops.name"

In case of the URI link references, we enforce a reference validation. This means that to successfully add an object A which references object B, then object B must exist in the project first. Also, using the same case, it's not possible to delete object B if it's still referenced by object A. This validation tightly couples the objects in the data model and prevents possible errors on the front end side.


The examples in all articles in this section describe and use examples of metadata objects from the publicly available Retail Solution Demo project.