Model settings

model_settings.json describes a model’s runtime capabilities, lookup configuration and defaults. It is supplied by the model and validated by ods_tools against model_settings_schema.json. Nested objects (e.g. model_settings, lookup_settings) are expanded into their own subsections below.

Field	Type	Required	Constraints	Description
version	string		minimum 3	The schema version for model settings validation (optional)
name	string			Name of the model associated with this settings file (optional)
description	string			Short Description of the catastrophe model (optional)
model_supplier_id	string			The supplier ID for the model. (optional)
model_name_id	string			The model ID for the model. (optional)
model_version_id	string			The version ID for the model. (optional)
model_run_mode	enum		one of: V1, V2	OasisPlatform execution mode for running an analysis, V1 = ‘Single server execution’ (worker versions 1.x.x or 2.3.x) , V2 = ‘Distributed execution’ scale an analysis across multiple nodes (Only workers 2.3.x and above)
model_configurable	boolean			Marks this model as a ‘complex model’ with configuration options at the input file generation stage. (optional)
model_default_samples	integer		minimum 0	The default number of samples generated per event. (optional)
model_settings	object	Yes		Runtime settings available to a model
lookup_settings	object	Yes		Model lookup section
correlation_settings	array[object]			Legacy Correlation Settings. Now moved to model_settings
data_settings	object			Additional data options for a model
computation_settings	object			List of parameters that will be passed as arguments to the MDK, options are dependent on the package version. To see these look at releases 2.4.0 and up (https://github.com/OasisLMF/OasisLMF/releases)

model_settings

Runtime settings available to a model

Field	Type	Required	Constraints	Description
event_set	object			The ‘id’ field from options is used as a file suffix’ events_.bin
event_occurrence_id	object			The ‘id’ from options is used as a file suffix’ occurrence_.bin
footprint_set	object			The ‘id’ field from options is used as a file suffix, e.g. footprint_.bin, footprint_.idx.z, footprint_.parquet
vulnerability_set	object			The ‘id’ field from options is used as a file suffix, e.g. vulnerability_.bin, vulnerability_.csv, vulnerability_.parquet
pla_loss_factors_set	object			The ‘id’ field from options is used as a file suffix, e.g. lossfactors_.bin, lossfactors_.csv, lossfactors_.parquet
valid_output_perspectives	array[string]			If set, the model only supports the given output perspectives. This can be overridden per event set using the ‘valid_perspectives’ field. ‘gul’: ground up losses, ‘il’: insured losses, ‘ri’: reinsurance net losses, ‘rl’: reinsurance losses at all inuring priorities.
valid_output_metrics	array[string]			If set, the model only supports the given output metrics. This can be overridden per event set using the ‘valid_metrics’ field. Values must match the output options in the summaries section from the analysis_settings.json file. Example: ‘valid_output_metrics’:[‘ptl’,’elt’].
correlation_settings	array[object]			The Correlation Settings.
vulnerability_adjustments	object			Object containing vulnerability adjustments and replacements.
pla	boolean		default False	Legacy - moved to ‘computation_settings’.
do_disaggregation	boolean		default True	Legacy - moved to ‘computation_settings’
summary_report_fields	array[string]			If set, the exposure summary report will include additional breakdowns from the listed fields. Note that the field must exists in the exposure file.
string_parameters	array[object]			Single string paramters
list_parameters	array[object]			List of strings parameters
dictionary_parameters	array[object]			Generic dictionary parameters
boolean_parameters	array[object]			Boolean parameters
float_parameters	array[object]			Bounded float paramters
numeric_parameters	array[object]			unbounded numeric paramters
integer_parameters	array[object]			Integer paramters
dropdown_parameters	array[object]			Generic dropdown paramters
multi_parameter_options	array[object]			Sets of parameters with pre-assigned values
parameter_groups	array[object]			Parameter Groups

model_settings.event_set

The ‘id’ field from options is used as a file suffix’ events_.bin

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	string	Yes		Initial setting for event set
options	array[object]	Yes		Array of possible event sets

model_settings.event_set.options

Event sets option

Field	Type	Required	Constraints	Description
id	string	Yes		String value used to select an event set
desc	string	Yes		UI description for selection
number_of_events	integer		minimum 0	The total number of events in the set. (optional)
valid_occurrence_ids	array[string]			An optional list of viable occurrence file ids to use with this event set
valid_footprint_ids	array[string]			An optional list of viable footprint file ids to use with this event set
valid_pla_loss_factors_ids	array[string]			An optional list of viable PLA lossfactors file ids to use with this event set
valid_perspectives	array[string]			If set, this event set only supports the given output perspectives. ‘gul’: ground up losses, ‘il’: insured losses, ‘ri’: reinsurance net losses, ‘rl’: reinsurance losses at all inuring priorities.
valid_metrics	array[string]			If set, this event set only supports the given output metrics, matches the output types set in the summaries section on an analysis_settings.json file. Example: ‘valid_metrics’:[‘ptl’,’elt’] means that only valid summary outputs are ‘eltcalc’ and ‘pltcalc’.
tooltip	string			Long description (optional)

model_settings.event_occurrence_id

The ‘id’ from options is used as a file suffix’ occurrence_.bin

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	string	Yes		Initial setting for occurrence
options	array[object]	Yes		Array of possible occurrence sets

model_settings.event_occurrence_id.options

Occurrence set options

Field	Type	Required	Constraints	Description
id	string	Yes		String value used to select an occurrence set
desc	string	Yes		UI description for selection
tooltip	string			Long description (optional)
max_periods	integer		minimum 1	Maximum periods for this occurrence set

model_settings.footprint_set

The ‘id’ field from options is used as a file suffix, e.g. footprint_.bin, footprint_.idx.z, footprint_.parquet

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	string	Yes		Initial setting for footprint set
options	array[object]	Yes		Array of possible footprint sets

model_settings.footprint_set.options

Footprint set options

Field	Type	Required	Constraints	Description
id	string	Yes		String value used to select a footprint set
desc	string	Yes		UI description for selection
tooltip	string			Long description (optional)

model_settings.vulnerability_set

The ‘id’ field from options is used as a file suffix, e.g. vulnerability_.bin, vulnerability_.csv, vulnerability_.parquet

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	string	Yes		Initial setting for vulnerability set
options	array[object]	Yes		Array of possible vulnerability sets

model_settings.vulnerability_set.options

Vulnerability set options

Field	Type	Required	Constraints	Description
id	string	Yes		String value used to select a vulnerability set
desc	string	Yes		UI description for selection
tooltip	string			Long description (optional)

model_settings.pla_loss_factors_set

The ‘id’ field from options is used as a file suffix, e.g. lossfactors_.bin, lossfactors_.csv, lossfactors_.parquet

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	string	Yes		Initial setting for lossfactors set
options	array[object]	Yes		Array of possible lossfactors sets

model_settings.pla_loss_factors_set.options

Lossfactors set options

Field	Type	Required	Constraints	Description
id	string	Yes		String value used to select a lossfactors set
desc	string	Yes		UI description for selection
tooltip	string			Long description (optional)

model_settings.correlation_settings

Field	Type	Required	Constraints	Description
peril_correlation_group	integer			The Peril Correlation Group
correlation_value	string			The Legacy Correlation Value, retained for backward compatibility
hazard_correlation_value	string			The Correlation Value for harard sampling
damage_correlation_value	string			The Correlation Value for vulnerability sampling

model_settings.vulnerability_adjustments

Object containing vulnerability adjustments and replacements.

Field	Type	Required	Constraints	Description
adjustments	object			Dictionary containing vulnerability adjustments with vulnerability ID as integer keys and adjustment factors as float values.
replace_data	object			Detailed vulnerability replacements.
replace_file	string			Path to a CSV file containing vulnerability data to be replaced.

model_settings.string_parameters

User selected string value

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	string	Yes		Default ‘string’ for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

model_settings.list_parameters

User selected list values

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	array[string]	Yes		Default ‘list’ set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

model_settings.dictionary_parameters

User selected dictionarys

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	object	Yes		Defaults set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

model_settings.boolean_parameters

User selected boolean option

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	boolean	Yes		Default ‘value’ set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

model_settings.float_parameters

Select float value

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	number	Yes		Default ‘value’ set for float variable
max	number	Yes		Maximum Value for float variable
min	number	Yes		Minimum Value for float variable
stepsize	number			The slider widget’s step interval for adjusting the float parameter.
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

model_settings.numeric_parameters

Select float value

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	number	Yes		Default integer or float ‘value’ set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

model_settings.integer_parameters

Select float value

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	integer	Yes		Default integer ‘value’ set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

model_settings.dropdown_parameters

The ‘id’ field is mapped into the analysis settings as ‘paramter_name’: ‘’

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	string	Yes		Initial setting for dropdown option
options	array[object]	Yes		Array of possible event sets
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

model_settings.dropdown_parameters.options

Dropdown option

Field	Type	Required	Constraints	Description
id	string	Yes		String value used to select an event set
desc	string	Yes		UI description for selection
tooltip	string			Long description (optional)

model_settings.multi_parameter_options

Parameter group option

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
config	object	Yes		JSON object holding <parameter_name>: pairs
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

model_settings.parameter_groups

Defines which parameter are related

Field	Type	Required	Constraints	Description
name	string	Yes		Reference for the group element
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
priority_id	integer	Yes		Set which parameter groups to display first
presentation_order	array[string]	Yes		List of parameters reference by their ‘name’ property
collapsible	boolean			Boolean to mark if this parameter group is collapsible
default_collapsed	boolean			Boolean to mark if parameter group starts collapsed

lookup_settings

Model lookup section

Field	Type	Required	Constraints	Description
supported_perils	array[object]			Valid Peril codes for this model

lookup_settings.supported_perils

Selection Item

Field	Type	Required	Constraints	Description
id	string	Yes		OED three letter peril code
desc	string	Yes		Short string describing the peril
peril_correlation_group	integer			the peril correlated group ID

correlation_settings

Field	Type	Required	Constraints	Description
peril_correlation_group	integer			The Peril Correlation Group
correlation_value	string			The Correlation Value

data_settings

Additional data options for a model

Field	Type	Required	Constraints	Description
supported_oed_versions	array[string]			A list of OED releases that this model supports.
uses_model_files	boolean			Marks the model as requiring external model data.
model_data_version	string			Version ID of the Model data.
keys_data_version	string			Version ID of the lookup keys data.
worker_image	string			The model worker’s docker image name
worker_version	string			The model worker’s version ID
docs_version	string			Version ID of the model documents
test_files_version	string			Version ID of the test files
countries	array[string]			A list of country codes that this model covers.
mandatory_fields	array[string]			List of OED fields that the model requires.
additional_assets	array[object]			Data assets available to the model
damage_group_fields	array[string]			List of OED fields from location file to form damage group ids
hazard_group_fields	array[string]			List of OED fields from location file to form hazard group ids
datafile_selectors	array[object]			Select file_ids from the API endpoint /v1/data_files/ to connect with an analyses run

data_settings.additional_assets

Name, version and location of data

Field	Type	Required	Constraints	Description
name	string	Yes		Name of the Asset file
version	string			Version of Asset
path	string			Filesystem path to the asset
deploy	string			Target for deploying this additional asset

data_settings.datafile_selectors

File Selection Parameter

Field	Type	Required	Constraints	Description
name	string	Yes		name used store the selection under
desc	string	Yes		UI description for selection
tooltip	string			Long description (optional)
model_id	integer			call to /v1/models/{id}/data_files/ to filter files by model association
allow_multiple	boolean	Yes		Allow the user to link multiple files to an analyses.
search_filters	array[object]			File options filter

data_settings.datafile_selectors.search_filters

Build a query string from the following fields

Field	Type	Required	Constraints	Description
user	string			File was uploaded by ‘user’
filename	string			Filename exactly matches ‘value’
filename__contains	string			‘value’ is a substring of filename
file_description	string			File description matches ‘value’ exactly
file_description__contains	string			‘value’ is a substring of a File’s description’
content_type	string			file exactly matches a MIME type
content_type__contains	string			A files MIME type contains ‘value’

computation_settings

List of parameters that will be passed as arguments to the MDK, options are dependent on the package version. To see these look at releases 2.4.0 and up (https://github.com/OasisLMF/OasisLMF/releases)

Field	Type	Required	Constraints	Description
string_parameters	array[object]			Single string paramters
list_parameters	array[object]			List of strings parameters
dictionary_parameters	array[object]			Generic dictionary parameters
boolean_parameters	array[object]			Boolean parameters
float_parameters	array[object]			Bounded float paramters
numeric_parameters	array[object]			unbounded numeric paramters
integer_parameters	array[object]			Integer paramters
dropdown_parameters	array[object]			Generic dropdown paramters
multi_parameter_options	array[object]			Sets of parameters with pre-assigned values
parameter_groups	array[object]			Parameter Groups

computation_settings.string_parameters

User selected string value

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	string	Yes		Default ‘string’ for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

computation_settings.list_parameters

User selected list values

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	array[string]	Yes		Default ‘list’ set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

computation_settings.dictionary_parameters

User selected dictionarys

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	object	Yes		Defaults set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

computation_settings.boolean_parameters

User selected boolean option

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	boolean	Yes		Default ‘value’ set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

computation_settings.float_parameters

Select float value

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	number	Yes		Default ‘value’ set for float variable
max	number	Yes		Maximum Value for float variable
min	number	Yes		Minimum Value for float variable
stepsize	number			The slider widget’s step interval for adjusting the float parameter.
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

computation_settings.numeric_parameters

Select float value

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	number	Yes		Default integer or float ‘value’ set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

computation_settings.integer_parameters

Select float value

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	integer	Yes		Default integer ‘value’ set for variable
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

computation_settings.dropdown_parameters

The ‘id’ field is mapped into the analysis settings as ‘paramter_name’: ‘’

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
default	string	Yes		Initial setting for dropdown option
options	array[object]	Yes		Array of possible event sets
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

computation_settings.dropdown_parameters.options

Dropdown option

Field	Type	Required	Constraints	Description
id	string	Yes		String value used to select an event set
desc	string	Yes		UI description for selection
tooltip	string			Long description (optional)

computation_settings.multi_parameter_options

Parameter group option

Field	Type	Required	Constraints	Description
name	string	Yes		UI name for selection
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
config	object	Yes		JSON object holding <parameter_name>: pairs
visible	boolean			tell if parameter should be visible in UI
editable	boolean			tell if parameter should be editable in UI

computation_settings.parameter_groups

Defines which parameter are related

Field	Type	Required	Constraints	Description
name	string	Yes		Reference for the group element
desc	string	Yes		UI description for selection
used_for	enum		one of: all, generation, losses	Set if this parameter is ONLY used at input ‘generation’ or for output ‘losses’
tooltip	string			Long description (optional)
priority_id	integer	Yes		Set which parameter groups to display first
presentation_order	array[string]	Yes		List of parameters reference by their ‘name’ property
collapsible	boolean			Boolean to mark if this parameter group is collapsible
default_collapsed	boolean			Boolean to mark if parameter group starts collapsed