Format

A metadata.json file uses standard JSON syntax, and contains a single JSON object. (A JSON object is a map of keys to values; it’s equivalent to a Ruby or Puppet hash. In the Puppet docs, we sometimes refer to a JSON object as a hash.)

The main object can only contain certain keys, which are listed below.

Allowed Keys in metadata.json

Required keys are labeled as such; the rest are optional.

name (required) — The full name of your module, including the Puppet Forge username (like "username-module").

version (required) — The current version of your module. This should follow semantic versioning.

author — The person who gets credit for creating the module. If absent, this key will default to the username portion of name.

license (required) — The license under which your module is made available. License metadata should match an identifier provided by SPDX.

summary (required) — A one-line description of your module.

source (required) — The source repository for your module.

dependencies (required) — An array of other modules that your module depends on to function. See Specifying Dependencies below for more details.

project_page — A link to your module’s website that will be linked on the Forge.

Tags cannot contain whitespace. We recommend using four to six tags. Note that certain tags are prohibited, including profanity and anything resembling the $::operatingsystem fact (including but not limited to redhat, centos, rhel, debian, ubuntu, solaris, sles, aix, windows, darwin, and osx). Use of prohibited tags will lower your module’s quality score on the Forge.

data_provider — The name of a Puppet lookup data provider for your module, which it can use to set default values for class parameters. For more details, see the docs on Puppet lookup and module data. This can have the following values:

Note: Once you’ve generated your module and gone through the metadata dialog, you must manually edit the metadata.json file to include the dependency information.

Version Specifiers

The version requirement in a dependency isn’t limited to a single version; you can use several version specifiers that allow multiple versions. When installing your module, the Puppet module command will install the newest allowed version of a dependency that isn’t installed yet, and won’t touch any installed dependencies whose versions are OK.

The version specifiers allowed in module dependencies are:

1.2.3 — A specific version.

> 1.2.3 — Greater than a specific version.

< 1.2.3 — Less than a specific version.

>= 1.2.3 — Greater than or equal to a specific version.

<= 1.2.3 — Less than or equal to a specific version.

>= 1.0.0 < 2.0.0 — Range of versions; both conditions must be satisfied. (This example would match 1.0.1 but not 2.0.1.)

1.x — A semantic major version. (This example would match 1.0.1 but not 2.0.1, and is shorthand for >= 1.0.0 < 2.0.0.)

1.2.x — A semantic major and minor version. (This example would match 1.2.3 but not 1.3.0, and is shorthand for >= 1.2.0 < 1.3.0.)

Note: You cannot mix semantic versioning shorthand (.x) with greater/less than versioning syntax. The following would be incorrect.

>= 3.2.x

< 4.x

Best Practice: Set an Upper Bound for Dependencies

When your module depends on other modules, make sure to set the upper version boundary in your version range; for example, 1.x (any version of 1, but less than 2.0.0) or >= 1.0.0 < 3.0.0 (greater than or equal to 1.0.0, but less than 3.0.0). If your module is compatible with the latest released versions of its dependencies, set the upper bound to exclude the next, unreleased major version.

Without this upper bound, users might run into compatibility issues across major version boundaries, where incompatible changes occur. It is better to be conservative and set an upper bound, and then release a newer version of your module after a major version release of the dependency. Otherwise, you could suddenly have to fix broken dependencies.

If your module is compatible with only one major or minor version, you can use the semantic major/minor version shorthand (e.g., 1.x). If your module is compatible with versions crossing major version boundaries, such as with stdlib, you can set your supported version range to the next unreleased major version. For example:

In this example, the current version of stdlib is 4.8.0, and version 5.0.0 is not yet released. Under the rules of semantic versioning, 5.0.0 is likely to have incompatibilities, but every version of 4.x should be compatible. We don’t know yet if the module will be compatible with 5.x. So we set the upper bound of the version dependency to less than the next known incompatible release (or major version).

Specifying Operating System Compatibility

If you are publishing your module to the Forge, we highly recommend that you include operatingsystem_support in metadata.json. Even if you do not intend to publish your module, including this information can be helpful for tracking your work.

This key accepts an array of hashes, where each hash contains operatingsystem and operatingsystemrelease keys.

operatingsystem should be a string. The Puppet Forge uses this for search filters.

operatingsystemrelease should be an array of strings. The Puppet Forge displays these versions on module pages, and you can format them in whatever way makes sense for the OS in question.

A Note on Semantic Versioning

When writing your metadata.json file, you’re setting a version for your own module and optionally expressing dependencies on others’ module versions. We strongly recommend following the Semantic Versioning specification. Doing so allows others to rely on your modules without unexpected change.

Many other users already use semantic versioning, and you can take advantage of this in your modules’ dependencies. For example, if you depend on puppetlabs-stdlib and want to allow updates while avoiding breaking changes, you could write the following line in your metadata.json (assuming a current stdlib version of 4.2.1):