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

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!

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.

Given the nature of JSON and this statement from the Nodejitsu documentation I don't see anything wrong with that.

NPM itself is only aware of two fields in the package.json:

{
   "name" : "barebones",
   "version" : "0.0.0",
}

NPM also cares about a couple of fields listed here. So as long as it is valid JSON and doesn't interfere with Node.js or NPM everything should be alright and valid.

Node's awareness of package.json files seems extends to the main field. Ref.

 { "name" : "some-library",
   "main" : "./lib/some-library.js" }

If this was in a folder at ./some-library, then require('./some-library') would attempt to load ./some-library/lib/some-library.js.

This is the extent of Node's awareness of package.json files.

To avoid possible conflicts you should prefixing your keys with some character or word. It is not recommended to use an underscore (_) or dollar sign ($) as those are reserved character prefixes, but other choices are viable.