The FMI standard uses semantic version numbers, as defined in [PW13], where the standard version consists of a triple of version numbers, consisting of major version, minor version, and patch version numbers [e.g. 1.2.3 for major version 1, minor version 2 and patch version 3].
-
Major versions will introduce changes that are neither backward nor forward compatible, including changes to the XML schemas to include new non-ignorable content.
-
Minor versions will only contain clarifications and include new layered standards, which may add new ignorable XML content, as defined below, into the core standard document, indicating that the standard needs to be supported by all conforming implementations.
-
Patch versions will only change explanatory text of the standard, make formerly defined content clearer, without any other changes to the XML schemas or other content definitions. For this reason, the version number attribute of all FMI files will only contain major and minor version numbers and not the patch version number: It should never be necessary for an importer to know the patch version number of the standard that the generating tool implemented.
In order to enable the backward-compatible extension of the FMI standard in minor releases and between minor releases, the FMI project intends the use of the layered standard mechanism to introduce new features in a fully backward-compatible and optional way.
A layered standard defines extensions to the base FMI standard by specifying, for example:
-
support for additional MIME types,
-
new values for [matchingRule] or [terminalKind] for Terminals and/or
-
adding C-API functions/variables.
Any FMU following a layered standard on top of FMI 3.0 must still be a compliant FMI 3.0 FMU.
Layered standards can fall into one of three categories:
Layered standards that have achieved enough adoption or importance to be included into the base standard could be incorporated into a new minor or major release version of the base standard, making support for this layered standard optional or required for conformance with the newly published release of the FMI standard.
To enable implementations to uniformly detect the presence of a layered standard in an FMU, even if they are not aware of the particular layered standard, adherence by layered standards to the following conventions is recommended:
A layered standard should require the presence of an XML file named fmi-ls-manifest.xml in the sub-directory of extra mandated by the layered standard.
The root element of this XML file shall have the following attributes in the XML namespace http://fmi-standard.org/fmi-ls-manifest:
fmi-ls-manifest.xml root attribute details.
| Attribute | Description |
|---|---|
|
Name, in reverse domain name notation, of the layered standard. |
|
Version of the layered standard. The use of semantic versioning is highly recommended. In case of semantic versioning it is up to the layered standard to define whether only major and minor version are included in the version attribute, or the full version is to be included. |
|
String with a brief description of the layered standard that is suitable for display to users. |
Otherwise the content of this XML file can be arbitrary, i.e. the layered standard is free to mandate any root element and other content, as well as any XML namespaces. This allows the use of the file for layered standard content, if the layered standard so wishes.
A simple example of a manifest file is shown below:
link:examples/fmi_ls_manifest_example.xml[role=include]A minimal example of a manifest file, for layered standards that have no need for additional content in that file is:
link:examples/fmi_ls_manifest_minimal_example.xml[role=include]The standard includes a schema for the attribute definitions and the minimal example element fmiLayeredStandardManifest shown above as fmi3LayeredStandardManifest.xsd.
An example schema that describes the simple example of a manifest above is shown below:
link:examples/fmi_ls_manifest_example_schema.xsd[role=include]