Module Metadata and metadata.json

Included in Puppet Enterprise 2016.1. A newer version is available; see the version menu above for details.

Puppet modules should always contain a metadata.json file, which tracks important information about the module and can configure certain features. It’s used by several Puppet subsystems:

  • The puppet module command uses this file to display module information and prepare modules for publishing.
  • The Puppet Forge requires this file and uses it to create the module’s info page, provide dependency information to users installing the module, and more.
  • The Puppet lookup system relies on the data_provider key in metadata.json to configure module data.

Location

Every module should contain a metadata.json file. It should be located in the module’s main directory, outside any subdirectories.

Example

    {
      "name": "examplecorp-mymodule",
      "version": "0.0.1",
      "author": "Pat",
      "license": "Apache-2.0",
      "summary": "A module for a thing",
      "source": "https://github.com/examplecorp/examplecorp-mymodule",
      "project_page": "https://forge.puppetlabs.com/examplecorp/mymodule",
      "issues_url": "https://github.com/examplecorp/examplecorp-mymodule/issues",
      "tags": ["things", "stuff"],
      "operatingsystem_support": [
        {
        "operatingsystem":"RedHat",
        "operatingsystemrelease":[ "5.0", "6.0" ]
        },
        {
        "operatingsystem": "Ubuntu",
        "operatingsystemrelease": [ "12.04", "10.04" ]
        }
       ],
      "dependencies": [
        { "name": "puppetlabs/stdlib", "version_requirement": ">= 3.2.0 < 5.0.0" },
        { "name": "puppetlabs/firewall", "version_requirement": ">= 0.0.4 < 2.0.0" }
      ],
      "data_provider": "hiera"
    }

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.
  • issues_url — A link to your module’s issue tracker.
  • operatingsystem_support — An array of operating systems your module is compatible with. See Specifying Operating System Compatibility below for more details.
  • tags — An array of key words to help people find your module (not case sensitive). For example: ["msyql", "database", "monitoring"]

    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:
    • null — Same as if the key is absent. No data provider.
    • "none" — No data provider.
    • "hiera" — Uses Hiera-like data sources stored in your module, configured by a hiera.yaml (version 4) file.
    • "function" — Uses a hash returned by a function named <MODULE NAME>::data.
    • The name of a third-party data provider provided by a module.

Deprecated Keys

  • types — Resource type documentation generated by older versions of the Puppet module tool as part of puppet module build. You should remove this key from your metadata.json.

Specifying Dependencies

If your module depends on functionality in another module, you can express this in the dependencies key of metadata.json.

The dependencies key accepts an array of hashes, where each hash contains "name" and "version_requirement" keys. Here’s an example from the puppetlabs-postgresql module:

    "dependencies": [
      { "name": "puppetlabs/stdlib", "version_requirement": ">= 3.2.0 < 5.0.0" },
      { "name": "puppetlabs/firewall", "version_requirement": ">= 0.0.4" },
      { "name": "puppetlabs/apt", "version_requirement": ">= 1.1.0 < 2.0.0" },
      { "name": "puppetlabs/concat", "version_requirement": ">= 1.0.0 < 2.0.0" }
    ]

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:

 { "name": "puppetlabs/stdlib", "version_requirement": ">= 3.2.0 < 5.0.0" }

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.
"operatingsystem_support": [
  {
  "operatingsystem":"RedHat",
  "operatingsystemrelease":[ "5.0", "6.0" ]
  },
  {
  "operatingsystem": "Ubuntu",
  "operatingsystemrelease": [
    "12.04",
    "10.04"
    ]
  }
]

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):

"dependencies": [
  { "name": "puppetlabs/stdlib", "version_requirement": "4.x" },
]

↑ Back to top