How to Add New License Rules for Enhanced Detection

ScanCode relies on license rules to detect licenses. A rule is a simple text file containing a license text or notice or mention; And a small companion YAML text file that tells ScanCode which license expression to report when the text is detected.

See the FAQ for a high level description of How to Add New License Rules for Enhanced Detection.

How to add a new license detection rule?

A license detection rule is a pair of files:

  • a plain text rule file that is typically a variant of a license text, notice or license mention.

  • a small text data file (in YAML format) documenting which license expression should be detected when the rule text is found in a codebase.

To add a new rule, you need to pick a unique base file name. As a convention, we like to include the license expression that should be detected in that name to make it more descriptive. For example: mit_and_gpl-2.0 is a good base name for a rule that would detect an MIT and GPL-2.0 license combination at once. Add a suffix to make it unique if there is already a rule with this base name. Do not use spaces or special characters in that name.

Then create the rule file in the src/licensedcode/data/rules/ directory using this name, replacing selected_base_name with the base name you selected:

selected_base_name.RULE

Save your rule text in this file.

Then create the YAML data file in the src/licensedcode/data/rules/ directory using this name:

selected_base_name.yml

For a simple mit and gpl-2.0 license expression detection, the content of this file can be this YAML snippet:

license_expression: mit AND gpl-2.0
is_license_notice: yes

Save these two files in the src/licensedcode/data/licenses/ directory and you are done!

See the src/licensedcode/data/rules/ directory for many examples.

More (advanced) rules options:

  • you can use a notes: text field to document this rule and explain where you found it first.

  • if no license should be detected for your .RULE text, do not add a license expression, just add a notes field.

  • Each rules needs have one flag such as is_license_notice. See the src/licensedcode/models.py directory for a list of all possible values and other options.

  • you can specify key phrases by surrounding one or more words between the {{ and }} tags. Key phrases are words that must be matched/present in order for a RULE to be considered a match.