solution.yaml (Fields and Parameter Types)

Every solution folder must contain a solution.yaml file. This file describes the solution from both a business and technical perspective.

Using the solution.yaml file, you specify, among other things:

how the solution is displayed in the Solution Gallery
for which OPC Router versions it should be offered
which parameters the user must enter or select during import
in which files parameter values may be replaced

Resolution Process

As soon as a solution is to be used, parameter values are replaced in the permitted files, transferred to the project files, and automatically loaded into the configuration.

The following points should be noted:

Parameters in the files must follow the format ${<parameter_id>}. For the parameter ID notation, snake_case is recommended¹.
Files whose content has been modified by parameter resolution are written using UTF-8 encoding.
For the "ParameterReplacementFileRegex" check, only the filename is used, not the entire file path.
Parameters without a default value, an optional specification, or an entered value are replaced with an empty value. This can cause unintended behavior and should be checked beforehand.
If a solution contains functions (FX), these are assigned an internal identity when the solution is created. Reinstalling the same solution in the same project creates a second function with the same internal identity; existing calls may subsequently point to either of the two copies. Therefore, install a solution only once per project.

In practice, this means: Any information that may vary in the target project should be deliberately modeled as a parameter. This helps you avoid rework after the import and reduces the risk of incomplete or incorrect project customizations.

Definitions

solution.yaml

Field Name	Type	Description	Example
FormatVersion	int	Specifies the format version	`1`
CompatibleVersionRange	string	Version specification in loose Semver format. This is used to check whether the product version is compatible. If not, the solution is hidden. Omitting this field accepts any version.	`">=5.2 <=6.0"`
Tags	List (string)	List of tag IDs. Tags serve as search and filter aids in the Solution Gallery to help find solutions by topic or technology. See `tags.yaml`	`["Example"]`
DisplayName	TranslatableString	Display name	`DE: "Beispiel"`
IconFile	string	File name of the icon file at the solution level. All common image formats such as PNG, JPG, and SVG are supported.	`"example.svg"`
ShortDescription	TranslatableString	Short description of a solution used in the overview.	`DE: "Kurze Beschreibung"`
Description	TranslatableString	Description of the solution with usage instructions. Can be overridden by a Markdown file (see below).	`DE: "Ausführliche Beschreibung"`
Parameters	Mapping (Solution Parameters)	Mapping with parameter ID as the key and solution parameter as the value. The parameter ID is used in the format `${<parameter_id>}` when using the solution.	`example_string:`
ParameterReplacementFileRegex	string	Regular expression for filtering filenames during parameter resolution when using the solution. If not specified, all files are considered valid. If specified, only matches are resolved.	`".*yaml"`

Solution Parameters

Parameters define the values that a user enters or selects when importing a solution. They allow you to control which parts of the solution can be customized for the target project without manually editing the project files.

Each parameter consists of a parameter ID and an associated configuration. The parameter ID is used in the project files as a placeholder in the format ${<parameter_id>}.

Select the parameter type so that it matches the expected input. This makes the input clearer for the user and avoids error-prone free-text entry.

Basic

The basic configuration applies to all parameter types.

Field Name	Type	Description	Example
Type	string	Parameter type. The following are allowed: `String`, `FileName`, `Integer`, `Boolean`, `Dropdown`, and `SecretKey`. If this is missing or unknown, the parameter is not evaluated.	`"String"`
Label	TranslatableString	Name of the parameter in the input mask	`DE: "Servername"`
HelpText	TranslatableString	Help text for the user, for example regarding the expected format or purpose	`DE: "Geben Sie den Hostnamen für den Zielserver ein."`
Required	bool	Specifies whether the user must enter a value. The default is `true`.	`true`

Boolean

Use this type for yes/no decisions or to enable or disable a feature.

Field Name	Type	Description	Example
Default	bool	Default value for user input. Omitting a value results in `false`.	`true`

Used to provide a selection of constant values.

Field Name	Type	Description	Example
Default	string	Default value for user input. Refers to the internal value of an item in the selection.	`"1"`
Items	List (DropdownItem)	Available options.	`"Option 1"`, `"Option 2"`

DropdownItem

Field Name	Type	Description	Example
DisplayText	TranslatableString	Display name	`DE: "Option 1"`
Value	string	Internal value. Used during parameter resolution.	`"1"`

Integer

Used to specify an integer.

Field Name	Type	Description	Example
Default	int	Default value for user input.	`1234`
Min	int	Minimum value	`10`
Max	int	Maximum value	`9999`

SecretKey

Use this type if the user is to select a secret key from an existing secret store. This ensures that sensitive values do not have to be stored in plain text in the solution or in project files.

No additional fields available.

String

Use this type for free-form text entries, such as URLs, server names, client IDs, or other identifiers.

Field Name	Type	Description	Example
Default	string	Default value for user input.	`"server01"`
MinLength	int	Minimum length	`3`
MaxLength	int	Maximum length	`50`

FileName

Use this type when the user is required to enter a filename.
Unlike the string parameter, the input is checked for valid characters. Additionally, the user interface can display filename conflicts more specifically.

Field Name	Type	Description	Example
Default	string	Default value for user input.	`"export.csv"`
MinLength	int	Minimum length	`3`
MaxLength	int	Maximum length	`64`

Markdown Description

A Markdown file can optionally be created to describe a solution. The following naming conventions apply:

The file must be located at the solution level (at the level of solution.yaml).
The base filename is description. Translations are optional and can be added using a _de or _en suffix.
- Example: description.md or description_de.md
The file must end with .md.
Only features from the CommonMark Standard are supported.

Example of a `solution.yaml` file

solution.yaml
FormatVersion: 1
ParameterReplacementFileRegex: .*yaml
CompatibleVersionRange: ">=5.2 <=6.0"
Tags:
  - Example
IconFile: "example.svg"
DisplayName:
  DE: "Beispiel"
  EN: "Example"
ShortDescription:
  DE: "Kurze Beschreibung"
  EN: "Short description"
Parameters:
  # String parameters
  example_string:
    Type: "String"
    Label:
      DE: "Ein String"
      EN: "A string"
    HelpText:
      DE: "Hilfetext"
      EN: "Help text"
    Default: "Test"
    MinLength: 5
    MaxLength: 30
  # File-Name-Example
  example_file_name:
    Type: "FileName"
    Label:
      DE: "Ein Dateiname"
      EN: "A file name"
    HelpText:
      DE: "Hilfetext"
      EN: "Help text"
    Default: "test-file-name"
  # Integer Parameters
  example_integer:
    Type: "Integer"
    Label:
      DE: "Beispiel Ganzzahl"
      EN: "Example integer"
    Default: 1234
    Min: 10
    Max: 9999
  # Dropdown Parameters
  example_dropdown:
    Type: "Dropdown"
    Label:
      DE: "Beispiel Dropdown"
      EN: "Example dropdown"
    Items:
      - DisplayText:
          DE: "Option 1"
          EN: "Option 1"
        Value: "1"
      - DisplayText:
          DE: "Option 2"
          EN: "Option 2"
        Value: "2"
    Default: "1"
  # Secret Key Parameter
  example_secret_key:
    Type: "SecretKey"
    Label:
      DE: "Geheim"
      EN: "Secret"
  # Boolean parameters
  example_boolean:
    Type: "Boolean"
    Label:
      DE: "Beispiel Boolean"
      EN: "Example Boolean"
    Default: true

snake_case refers to a naming convention using lowercase words and underscores as separators, for example, server_url or project_name. ↩

Resolution Process​

Definitions​

solution.yaml​

Solution Parameters​

Basic​

Boolean​

Dropdown​

DropdownItem​

Integer​

SecretKey​

String​

FileName​

Markdown Description​

Example of a solution.yaml file​

Footnotes​