doc: clarify license metadata guidelines

* explain license expressions with a link to spdx.js
* show how to upgrade old array-style license fields
* show how to correct bad multi-license metadata

1 files changed, 39 insertions, 5 deletions

diff --git a/doc/files/package.json.md b/doc/files/package.json.md
index b02773814..0251a6ca3 100644
--- a/doc/files/package.json.md
+++ b/doc/files/package.json.md
@@ -98,9 +98,8 @@ If a url is provided, it will be used by the `npm bugs` command.
 You should specify a license for your package so that people know how they are
 permitted to use it, and any restrictions you're placing on it.
 
-The simplest way, assuming you're using a common license such as BSD-3-Clause
-or MIT, is to just specify the standard SPDX ID of the license you're using,
-like this:
+If you're using a common license such as BSD-2-Clause or MIT, add a
+current SPDX license identifier for the license you're using, like this:
 
     { "license" : "BSD-3-Clause" }
 
@@ -108,8 +107,43 @@ You can check [the full list of SPDX license IDs](https://spdx.org/licenses/).
 Ideally you should pick one that is
 [OSI](http://opensource.org/licenses/alphabetical) approved.
 
-It's also a good idea to include a LICENSE file at the top level in
-your package.
+If your package is licensed under multiple common licenses, use an [SPDX license
+expression syntax version 2.0 string](http://npmjs.com/package/spdx), like this:
+
+    { "license" : "(ISC OR GPL-3.0)" }
+
+If you are using a license that hasn't been assigned an SPDX identifier, or if
+you are using an uncommon or custom license, do not include a "license" string
+in package.json. In those cases especially, but also more generally, it's a good
+idea to include a LICENSE file at the top level of the package.
+
+Some old packages used license objects or a "licenses" property containing an
+array of license objects:
+
+    // Not valid metadata
+    { "license" :
+      { "type" : "ISC"
+      , "url" : "http://opensource.org/licenses/ISC"
+      }
+    }
+
+    // Not valid metadata
+    { "licenses" :
+      [
+        { "type": "MIT"
+        , "url": "http://www.opensource.org/licenses/mit-license.php"
+        }
+      , { "type": "Apache-2.0"
+        , "url": "http://opensource.org/licenses/apache2.0.php"
+        }
+      ]
+    }
+
+Those styles are now deprecated. Instead, use SPDX expressions, like this:
+
+    { "license": "ISC" }
+
+    { "license": "(MIT OR Apache-2.0)" }
 
 ## people fields: author, contributors