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:
package.json._ and $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:
npm currently uses: https://docs.npmjs.com/files/package.jsonAs for choosing custom keys: the CommonJS package specification states (emphasis mine):
The following fields are reserved for future expansion:
build,default,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.
"org_example" instead of "org.example" – or an XML-namespace-like "http://example.org"?
org.example or http://example.org, but, given that the JSON key names are also JavaScript object property names, it would make it awkward to access these properties later, because you'd have to use something like pkg['org.example'], because the more natural pkg.<propertyname> syntax wouldn't work with them.@example: I suppose that would work if you use your / your organization's npm username. Note that we're talking about a self-chosen convention in any case here, so personally I'd go for the reverse-domain-notation, because it is (a) common practice in other contexts), and (b) "more unique" than an npm username._ is for, e.g., org_example to be recognized as a single word, forming a regular JS property name. You're referring to - (hyphen) chars. in domain names, which indeed wouldn't work. However, you can replace - instances with _ instances as well; while this renders the transformation potentially non-reversible, it still strikes me as preferable to property names such as http://domain-name.org, especially in view of the fact that using - in domain names is increasingly rare. However, this is ultimately a matter of preference.
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.
_ (or $) for custom properties: "All properties beginning with _ or $ are also reserved for package registries to use at their discretion." - wiki.commonjs.org/wiki/Packages/1.1 See my answer for more.