SPDX License Whitelist Checker

1.0.0 · active · verified Tue Apr 21

spdx-whitelisted is a JavaScript library designed to evaluate whether a given SPDX license expression satisfies a provided whitelist of allowed SPDX licenses. It operates on structured SPDX expression objects, typically generated by parsers like `spdx-expression-parse`, and a list of structured license objects representing the whitelist. This package, currently at version 1.0.0, was forked from version 5.0.0 of `spdx-satisfies`. Its primary function is to return a boolean indicating satisfaction. The library is intended for legal and compliance checks within software projects, helping to ensure that declared licenses conform to organizational policies. It is a stable release with no explicit rapid release cadence mentioned, suggesting a focus on correctness for its specific utility.

Common errors

```
TypeError: Invalid first argument.  Expects an object.
```
cause The first argument (the SPDX expression to check) was a string or a malformed object, not a properly structured SPDX expression object.

fix Ensure the first argument is an object adhering to the `spdx-expression-parse` AST schema. Always use `require('spdx-expression-parse')('YOUR-SPDX-EXPRESSION')` to generate this input.
```
TypeError: Invalid second argument.  Expects an array.
```
cause The second argument (the license whitelist) was not an array of structured license objects, or contained malformed entries.

fix Provide the second argument as an array, where each element is a structured license object (e.g., `{ license: 'MIT' }`). For robustness, use `require('spdx-expression-parse')('LICENSE-ID')` to generate each entry in the whitelist array.

Warnings

gotcha The exported `whitelisted` function performs only naive type checks on its arguments. It does not provide rigorous validation of the SPDX expression or whitelist data structures. Developers must ensure valid input formats, typically by parsing with `spdx-expression-parse`.
Fix: Always parse raw SPDX strings into structured objects using a robust parser like `spdx-expression-parse` before passing them to `spdx-whitelisted`.

Install

npm install spdx-whitelisted npm
yarn add spdx-whitelisted yarn
pnpm add spdx-whitelisted pnpm

Imports

whitelisted
wrong:
```
import whitelisted from 'spdx-whitelisted';
```
correct:
```
const whitelisted = require('spdx-whitelisted');
```
Package exports a single CommonJS function. Direct ESM import is not supported in v1.0.0.

Quickstart

Demonstrates how to use `spdx-whitelisted` to check if various SPDX license expressions satisfy a defined whitelist, including complex expressions and 'plus' version logic.

const assert = require('assert');
const whitelisted = require('spdx-whitelisted');
const parse = require('spdx-expression-parse'); // Required to generate valid SPDX expression objects

// Define a sample license expression object (parsed from 'MIT')
const expressionMIT = parse('MIT');

// Define a sample whitelist
const whitelist = [
  parse('ISC'),
  parse('MIT'),
  parse('Apache-2.0')
];

// Example 1: Simple MIT license against a whitelist including MIT
assert(
  whitelisted(
    expressionMIT,
    whitelist
  )
);
console.log('MIT is whitelisted (expected true)');

// Example 2: GPL-3.0 is NOT in the whitelist
const expressionGPL = parse('GPL-3.0');
assert(
  !whitelisted(
    expressionGPL,
    whitelist
  )
);
console.log('GPL-3.0 is not whitelisted (expected false)');

// Example 3: Complex expression (MIT OR Apache-2.0) AND (ISC OR GPL-2.0) against a partial whitelist
const complexExpression = parse('(MIT OR Apache-2.0) AND (ISC OR GPL-2.0)');
const partialWhitelist = [
  parse('Apache-2.0'),
  parse('ISC')
];

assert(
  whitelisted(
    complexExpression,
    partialWhitelist
  )
);
console.log('Complex expression is whitelisted (expected true)');

// Example 4: Demonstrating the 'plus' logic for license versions
assert(whitelisted(
  parse('GPL-3.0'),
  [parse('GPL-2.0', { plus: true })]
));
console.log('GPL-3.0 is satisfied by GPL-2.0+ (expected true)');

view raw JSON →