Configuration data schema

About this page

On this page you'll be able to look up the meaning and opportunities of all the variables (potentially) contained in an MSP Challenge session configuration JSON file. Should some of the documentation on this page be wrong or incomplete, then we encourage you to update it yourself. Just make sure you're logged in and click on Edit Source to get started. Thank you!

This page follows the structure of the configuration file to the letter. This means that you should be able to recognize and find all of the headers on this page (e.g. 'metadata', 'datamodel') within any of the MSP Challenge JSON configuration files we ship.

Configuration schema version covered by this documentation: 1.1.x (since v4.0.1)

A good example of a configuration file is the North Sea Basic configuration that's shipped with the server installation, of which its characteristics are explained on this page.

We note that the MSP Challenge Configuration Editor, shipped with the full platform installer, helps you a lot with explaining variables and defining proper values for them. However, the documentation on this page and its sub-pages is considerably more detailed and referential.

metadata

The main object for all things metadata, i.e., data about this data.

Field	Type	Description
date_modified	string	Date with format dd/mm/yyyy representing the date the configuration file was last modified
data_model_hash	string	A string that's unique to the configuration content, auto-generated by the MSP Challenge Configuration Editor (shipped with the Windows full platform installer).
errors	int	Always 0. The idea was that this variable could store errors in the configuration content. Not implemented.
editor_version	string	Version number of the MSP Challenge Configuration Editor software by which the particular configuration file was generated.
config_version	string	Version number of the configuration schema adopted in the particular configuration file.

datamodel

The main object for everything that's *not* metadata, but just actual content.

Field	Type	Description
restrictions	object[], with keys	Documented on this separate restrictions page.
plans	object[]	Documented on this separate plans page.
CEL	object	Documented on this separate CEL page.
SEL	object	Documented on this separate SEL page.
MEL	object	Documented on this separate MEL page.
meta	object[]	Documented on this separate meta page.
expertise_definitions	object[]	Documented on this separate expertise_definitions page.
objectives	object[]	Documented on this separate objectives page.
edition_name	string	Name that the client should show when a session created with this configuration file has been created on the server, e.g. 'North Sea edition'
edition_colour	string	Colouring of the MSP Challenge logo/icon accompanying the edition name, as shown by the client.
edition_letter	string	Letter to add into the MSP Challenge logo/icon accompanying the edition name, as shown by the client.
region	string	name of the region (must be the same as the name of the folder on geoserver
projection	string	PROJ.4 formatted string representing the projection system that should be used with the geodata referenced under meta and obtained from the GeoServer.
start	int	Start year. The first month of the simulation is always 0 and thus represents January of the year defined in this variable. So setting this to 2024 means the first month (month 0) will be January 2024.
end	int	End year. The last month of the simulation will subsequently be January of the year defined in this variable. So setting this to 2050 means the last simulated month will be January 2050.
era_total_months	int	Total number of months in each era. There are always four eras between the start and end year. So this means that this variable has to fit with the start and end year you define above. Setting the start year to 2020 and end year to 2060 means that the whole simulation will take 40 years, which has to mean that each era has to last 10 years, so 120 months.
era_planning_months	int	Each era has a default setting for the number of months should be normal planning months (during which players/users can actually make plans) and simulation months (during which they can't). So how many months of the era are taken up by the planning period? The rest will be simulation. This is just the default setting. When an administrator user logs on to the session after its initial creation, the Setup phase will allow that administrator user to alter and finally confirm the planning/simulation distinction.
era_planning_realtime	int	Duration (seconds) that the planning period takes, so real-life seconds. This setting becomes relevant once an administrator user hits the 'play' button to start the simulation. At that moment the speed of the simulation will be calculated by dividing this value over the total number of months (see era_planning_months) that should be simulated during that time. The result of that division represents the number of seconds between each simulated month.
countries	string	What layer (referenced under meta > layer_name) contains the planning regions? Each of this layer's types will become a separate country/team, with the 'value' as its country identifier (used in other areas of the configuration file, such as MEL or plans) and the 'displayName' as its name. See meta > layer_type > value and displayName.
minzoom	int	Minimum camera zoom-in level. At present believed not to be not implemented. The minimum zoom-in level is determined by the _PLAYAREA geometry provided under meta.
maxzoom	int	Maximum camera zoom-in level.
user_admin_name	string	Name of the administrator user in the game. This user has all rights, including the right to plan and (dis)approve plans on behalf of all countries/teams, and to manipulate the simulations.
user_region_manager_name	string	Name of the region manager user in the game. This user has the right to plan and (dis)approve plans on behalf of all countries/teams.
user_admin_color	string	Hexadecimal colour code of the administrator user (last two digits representing transparency).
user_region_manager_color	string	Hexadecimal colour code of the region manager user (last two digits representing transparency).
team_info_base_url	string	The base URL used by the logo button in the top-left corner to open the Knowledge Base on a specific page. This will bring the user to the info page about their country/team.
restriction_point_size	float	Size of the restriction area around points
wiki_base_url	string	The base URL for all media and layer_media references under meta. Basically the base of the Knowledge Base website in use for this particular configuration.
windfarm_data_api_url	string	The base URL for communicating with the wind farm levelized cost of energy calculation API as developed and maintained by Deltares, the Netherlands. Currently only in use in the North Sea Digitwin configuration.