Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.

This page is about the YAML-based module descriptor for a Magnolia light module. If you are using a Magnolia Maven module, you should use an XML-based module descriptor.

The file must be in the root folder of the module and its name has to be module.yaml. 

The YAML-based module descriptor  allows you to define the version of the module and dependencies to other Magnolia modules.


Example

$magnolia.resources.dir/example-light-module/module.yaml
version: 1.0
dependencies:
  core:
    version: 5.4.7
  cache:
    version: 5.4.5
    optional: true

Module descriptor elements

version

required

The module versions.

dependencies

optional

Dependencies on other modules - the module will install only after the specified modules.

Module versions

The syntax for a version is:
from version / to version

where the version number consists of three parts: x.y.z. In this notation x.y denotes a major version and z a maintenance release. The last two parts are optional. For a strict version dependency, use just one version string.

The VersionRange class supports the following notation to indicate version dependency.

Only three parts are supported. The major, minor and security version positions. The build number is not supported. See Runtime.Version for more information.

  • * - Includes all versions - (warning) When using this option in a YAML file, please wrap * with quotes (version: "*")
  • 1.2 - Matches only 1.2 exactly.
  • 1.2/* - Matches all versions including and above 1.2.
  • 1.2/1.2.9 - Matches all versions including and between 1.2 and 1.2.9.
  • [1.2,1.2.9] - Inward square brackets mean inclusion. Same as above. Matches all versions including and between 1.2 and 1.2.9.
  • [1.2,1.2.9[ - Outward square brackets mean exclusion. Matches all versions between 1.2 and 1.2.9, including 1.2 but excluding 1.2.9.
  • [1.2,1.2.9) - Parentheses mean exclusion. Same as outward square brackets above. Matches all versions between 1.2 and 1.2.9, including 1.2 but excluding 1.2.9.

Examples:

Example

Description

3

Must have major version 3.

3.6

Must have major version 3.6.

3.6.3

Must have major version 3.6 and maintenance version 3.

3/*

Must have major version 3 or higher.

3.6/*

Must have major version 3.6 or higher.

3.6.3/*

Must have major version 3.6 and maintenance version 3 or higher.

*/3

Must have major version 3 or lower.

*/3.6

Must have major version 3.6 or lower.

*/3.6.3

Must have major version 3.6 and maintenance version 3 or lower.

3.5/3.6.2

Version not lower than 3.5 and not higher than 3.6.2.

[3.5/3.6.2]Versions between 3.5 and 3.6.2 including the boundaries.
[3.5/3.6.2[Versions between 3.5 and 3.6.2, excluding the upper boundary 3.6.2.
[3.5/3.6.2)Versions between 3.5 and 3.6.2, excluding the upper boundary 3.6.2. Same as above but alternative syntax.

Module dependencies

You can define runtime or install time dependencies (not build dependencies). If you define a dependency on a module, then this module will be installed and started before your module. A dependency can be optional. Optional in this context means that if an optional module is not present, installation will proceed, but if the optional module is present, this module will be installed first. The dependencies could look like this:

$magnolia.resources.dir/example-light-module/module.yaml
version: 1.0
dependencies:
  core:
    version: 5.4.7
  # If the Cache module is present, install the current module 
  # after Cache so we can add a cache bypass.
  cache:
    version: 5.4.5
    optional: true

The module dependencies define the order in which modules are loaded during startup. For example, if module-a depends on module-b, module-b will be loaded before module-a. The order becomes important, for example, if both module-a and module-b decorate the same definition or if module-a inherits a definition from module-b.

Decorations are applied in the module load order.