node.js - Add custom metadata or config to package.json, is it valid?

Question

I have seen (don't remember where) a package.json file with custom keys starting with an underscore:

{
    "name": "application-name"
  , "version": "0.0.1"
  , "private": true
  , "dependencies": {
      "express": "2.4.7"
    , "jade": ">= 0.0.1"
  }
  , "_random": true
}

Are you allowed to do this? Is it still valid? If this is allowed, is there any documentation on the rules?

Thanks!

Answer 1

tl;dr:

• Yes, you're allowed to add custom entries to package.json.
• Choose a key name:
  • not already defined (details below)
  • not reserved for future use (details below)
  • avoid prefixes _ and $
  • and preferably use a single top-level key in which to nest your custom entries.

E.g., if you own domain example.org, you could store a custom random key as follows, inside a top-level key in reverse-domain-name notation with _ substituted for . and, if applicable, -^{(see comments)} (e.g., org_example):

{
    "name": "application-name"
  , "version": "0.0.1"
  , "private": true
  , "dependencies": {
      "express": "2.4.7"
    , "jade": ">= 0.0.1"
  }  
  , "org_example": {
      "random": true
  }
}

To read such custom properties, use the following technique:

require("./package.json").org_example.random // -> true

---

npm's package.json file format mostly complies with the CommonJS package specification:

• keys that npm currently uses: https://docs.npmjs.com/files/package.json
• keys defined in the spec: http://wiki.commonjs.org/wiki/Packages/1.1

As for choosing custom keys: the CommonJS package specification states (emphasis mine):

The following fields are reserved for future expansion: build, default, email, external, files, imports, maintainer, paths, platform, require, summary, test, using, downloads, uid.

Extensions to the package descriptor specification should strive to avoid collisions for future standard names by name-spacing their properties with innocuous names that do not have meanings relevant to general package management.

The following fields are reserved for package registries to use at their discretion: id, type. All properties beginning with _ or $ are also reserved for package registries to use at their discretion.