Model Definition Reference

A definition for a model to be used with the National Infrastructure Modeling Service.

Field	Type	Values	Required	Description
api_version	string	['v1beta3']	Yes	The version of the API that should be used to process the document.
kind	string	['M', 'P', 'W']	Yes	The kind of object the document represents. Should equal 'M' for models
metadata	metadata object	-	Yes	The metadata for the Model.
spec	spec object	-	Yes	The model specification.

metadata

The metadata for the Model.

Field	Type	Values	Required	Description
description	string	-	Yes	A rich description of the Model's function.
display_name	string	-	Yes	The display name of the Model.
name	string	-	Yes	The name that the Model should be stored under. This can only contain alphanumeric characters and hyphens.
publisher	string	-	Yes	The name of the person or organisation who has published the Model.
summary	string	-	Yes	A short summary of the Model's function.
contact_point_name	string	-	Yes	The name of the person to contact for information about the Model.
contact_point_email	string	-	Yes	The email of the person to contact for information about the Model.
source_code	string	-	No	A URL pointing to the source code for this Model.
type	string	['model', 'service']	No	Whether this is a service or a model. The default is model.
licence	string	-	No	Permanent URL of applicable licence for this Model.
rights	string	-	No	Details of any usage rights, restrictions or citations required by users of this Model.
subject	string	['Biota', 'Boundaries', 'Climatology / Meteorology / Atmosphere', 'Economy', 'Elevation', 'Environment', 'Farming', 'Geoscientific Information', 'Health', 'Imagery / Base Maps / Earth Cover', 'Inland Waters', 'Intelligence / Military', 'Location', 'Oceans', 'Planning / Cadastre', 'Society', 'Structure', 'Transportation', 'Utilities / Communication']	No	Specific area of study or expertise.
project_name	string	-	No	Name or acronym of the model's associated project.
project_url	string	-	No	URL of the model's associated project.
funding	string	-	No	Funding details of the model's associated project.
embargo_end_date	string	-	No	Date when the embargo is lifted for this model, in single quotes (i.e. 'YYYY-MM-DD').

spec

The model specification.

Field	Type	Values	Required	Description
command	array of strings	-	No	The command to be run with the image.
inputs	inputs object	-	No	The possible model inputs in a model definition.
outputs	outputs object	-	No	The outputs of the model
resources	resources object	-	No	The hardware requirements of the model
sidecars	array of model_sidecars	-	No	The sidecars used by the model

inputs

The possible model inputs in a model definition.

Field	Type	Values	Required	Description
parameters	array of model_definition_parameters	-	No	Array of parameter definitions, this property is required but can be empty.
dataslots	array of model_definition_input_dataslots	-	No	The dataslots that contain the datasets that the Model expects as inputs when run in a Workflow, this property is required but can be empty.

model_definition_parameters

Metadata for the parameters a model uses as input. Depending on the type of the expected parameter some of these fields may be unnecessary (e.g. numeric variables should have a min and max value but these fields make no sense when set for a text variable.

Each input parameter has a type which, amongst other things, dictates how the parameter is represented on the front end to the user. For strings, integers, and numbers, the user is given an input field on the front end where they can type the value. Users will not be allowed to exceed the limitations given with min and max. String types that have options specified will have a dropdown box (as opposed to an input field) on the front end allowing users to pick from any of the options given in the list.

Boolean parameter types create a tick box on the front end which, if ticked, will set the corresponding envrionment variable to "True". If unticked, the variable will be set to "False".

JSON parameter types again provide the user with a text box. Given schema is a required field when using the JSON type, the JSON inputted by the user will be checked against that schema for validity.

The parameters are injected to Models as environment variables.

Given environment variables can only contain string values, all of the above types will be injected as string values which will need to be cast to the appropriate type at run time.

If the required property is set to False and a default property has also been set, the default will always be sent meaning that the runner of the model couldn't intentionally leave a parameter blank if it has a default associated with it. In addition to this, boolean parameters will always be sent by the front end regardless of whether you have set required or not. This is due to the desire to keep checkboxes simple and to avoid having a tri-state checkbox.

Field	Type	Values	Required	Description
name	string	-	Yes	The name of the parameter.
title	string	-	Yes	The title to use when displaying this variable.
description	string	-	Yes	What this parameter controls in the model.
type	string	['string', 'integer', 'number', 'boolean', 'json', 'link']	Yes	The type of the value to be assigned to the parameter.
default	-	-	No	The default value for this parameter.
min	number	-	No	The minimum value if this parameter is an integer or a number.
max	number	-	No	The maximum value if this parameter is an integer or a number.
regex	string	-	No	The regular expression which the parameter should match.
options	array of model_definition_parameters_options	-	No	A list of possible string values.
required	boolean	-	Yes	An indication as to whether or not the parameter is required for the model to run.
schema	schema object	-	No	The valid schema for a JSON type.

model_definition_parameters_options

Field	Type	Values	Required	Description
name	-	-	Yes	The name of this option.
title	-	-	Yes	The display name to use for this option.

schema

The valid schema for a JSON type.

Field	Type	Values	Required	Description
items	object	-	No	The items in a json array.
min_items	number	-	No	The minimum number of items in an array.
properties	object	-	No	The properties in a json object.

model_definition_input_dataslots

The metadata required for a Model to find a Dataset loaded into this slot.

Field	Type	Values	Required	Description
name	string	-	Yes	The name of the dataslot.
path	string	-	Yes	The path at which the Model expects to access the Datasets input into this slot.
default	array of strings	-	No	A list of the Datasets to be used as defaults for this slot. Must be specified if required is True.
description	string	-	No	A description of what kind of data this slot should contain.
required	boolean	-	Yes	A flag that determines whether this slot can be left empty. If required is True, default must be specified.

outputs

The outputs of the model

Field	Type	Values	Required	Description
datasets	array of model_output_dataset	-	No	The datasets that will be output from the model

model_output_dataset

Metadata associated with an output dataset.

Field	Type	Values	Required	Description
name	string	-	Yes	The path to the output file from the model.
type	string	-	Yes	The file format the data set will be in.
description	string	-	Yes	A description of the output file.

resources

The hardware requirements of the model

Field	Type	Values	Required	Description
use_gpu	boolean	-	No	A flag that determines whether or not your model will be assigned a GPU to run on.
readiness_probe	readiness_probe object	-	No	A url Argo can call to check that a service model is running

readiness_probe

A url Argo can call to check that a service model is running

Field	Type	Values	Required	Description
host	string	-	No	Host name to connect to, defaults to the pod IP
scheme	string	['HTTP', 'HTTPS']	No	Scheme to use for connecting to the host (HTTP or HTTPS). Defaults to HTTP.
path	string	-	No	Path to access on the HTTP server. Defaults to /.
port	integer	-	No	Number of the port to access on the container.

model_sidecars

The information required for this sidecar to be created.

Field	Type	Values	Required	Description
name	string	-	No	The name used by the sidecar. This can only container alphanumeric characters and hyphens.
image	string	-	No	The image to use for this sidecar.
command	array of strings	-	No	The command to be run with the image.