Last updated 11 July 2016. Created on 9 July 2015.
Edited by gisle, kreynen. Log in to edit this page.

The Attributions module may be used by maintainers of Drupal modules and themes to create an attribution block or an attribution page that can be used to display the license and attribution information about third party materials (such as code libraries, fonts, icons and images) that are included in a repository and need to be documented and/or publicly attributed.

The declarations concerning licenses and attributions are pulled from files named ASSETS.yml.

Configuration

After installing and enabling Attributions there will be an attribution block named Attributions block, and an attribution page when you vist /attributions.

By default, only attributions specified by enabled modules and themes will be rendered. To render attributions from all modules and themes. set the boolean variable attributions_all TRUE. You may do this with drush:

drush vset attributions_all TRUE

 
There is no adminsitrative GUI.

Attributions should be placed in a file named ASSETS.yml, in the module's top directory, using the standard YAML.org data serialization format.

Attributions YAML format

YAML is a human-readable data serialization format.

For more information about this format, see:

Syntax

The data structure hierarchy in YAML is maintained by outline indentation. For attributions, each resource are represented by an unique (in this file) identifier, followed by colon+newline followed by an intented list of keys and values separated by colon+space:

identifier:
  key: value
  key: value
  …

 
For example, the resource identified by “images/griffin_head.jpg”, with associated keys and values, may look like this:

images/griffin_head.jpg:
  type: asset
  approved: allowed license
  title: Griffin Head
  attributionText: Paul Keller
  attributionUrl: http://flickr.com/people/paulk/
  license: CC BY 2.0
  rights: http://creativecommons.org/licenses/by/2.0/deed.no
  source: http://flickr.com/photos/paulk/2062848161/

 
In general there is no need to put quotes around strings, but there are exceptions:

  • Use quotes to force a string, e.g. if your key or value is 10 but you want it to return a String and not a Fixnum, write '10' or "10".
  • Use quotes if your value includes special indicators, such as a colon (:) followed by a space or a newline, or {, }, [, ], ,, &, *, #, ?, |, +, -, <<, >>, =, !, %, @, \.
  • Single quotes let you put almost any character in your string, and won't try to parse escape codes. '\n' would be returned as the string \n.
  • Double quotes parse escape codes. For instance, "\n" will be returned as a line feed character.
  • If > is used to indicate a scalar, indicators are not interpreted (so no quotes are required).

Identifier

Each resource entry should be identified with an unique (in this file) string that identify the resource. This string should be the path (from the root of the repo) to an individual file, or the path to a directory. In the latter case the entry applies to all the files that live below the directory, unless overriden by more specific (single file) entries.

The path may contain the star wildcard * (meaning any string, including the null string).

A hash character (#), followed by an arbitrary string may be appended to the path to create multiple entries for the same directory or file. This can be used in the case where several assets or source code fragments, each associated with a different attributionText, etc. is aggregated in a single directory or file.

This line must not be indented.

The following identifier says that the entry applies to all the files that lives below the “images”-directory:

images:

 
The following identifier says that the entry applies to the single file “griffin_head.jpg” that is in the “images”-directory:

images/griffin_head.jpg:

 
The following identifier says that the entry applies to all the files that lives in a directory named “originals”, located below the “images”-directory:

images/*/originals:

 
The following is used to attribute a file named “slider.js” that is made up of two different components, the first authored by “John Smith”, the second by “Dojo Inc”.

lib/slider.js#foo:
  attributionText: John Smith

lib/slider.js#bar:
  attributionText: Dojo Inc

 

Administrative keys

Two keys are used for administrative purposes:

  • type: Must be set to 'code', 'asset' or comment'.
  • approved: Must be a link to an issue tracker in the LWG issue queue (for an exception request) or the string 'allowed license' (for own work made available under a whitelisted license).

The type should have the value code if the resource is program code, and asset if the resource is a non-code asset (e.g. text, image, video, audio, font, icon).

The type key must always be present in an entry. If the type of the entry is comment no other keys are required.

Metadata keys

The following set of keys may be used to document the source and license of a resource:

  • title: A human readable string identifying the licensed work (recommended).
  • source: Source of licensed work. This may be an URL, or a plain text string explaining how to locate the source of the work.
  • license: Human readable name of license, licenses, or policy of the work (required). In the case of multi-licensing, you may list multiple licenses separated by commas/conjunctions as a single value assigned this key.
  • copyrightNotice: The copyright notice for the (possibly adapted) resource, or directions for finding such information provided by other means. If the asset is a protected logo (trademark or wordmark), this must be stated explicitly here.
  • attributionText: Author (person, project or organization) or authors to receive attribution. You may list multiple authors separated by commas/conjunctions as a single value assigned this key.
  • attributionUrl: URL to the author's profile or home page. The author may be an individual, an organization, or a project.
  • rights: URL to license or policy document for resource (required unless the license is one of our approved licenses, or it is a protected logo with no reuse rights).

Unless the type of the entry is comment, those marked “required” must be present in the entry. The other keys are optional. If they are present, they may help downstream recipients understand how to fulfill the attribution requirement of licenses such as the Creative Commons licenses, but it is OK for a project to provide for this by other means. If you do, it may be helpful to use text bound to the key copyrightNotice to provide directions for finding such information.

Metadata keys for adaptions

If the work is an adapation, then the following additional keys may be used to document its origins. Only originalLicense is required.

  • originalTitle: A human readable string identifying the original of the adapted work.
  • originalLicense: Human readable name of license giving permission to adapt the work (required).
  • originalCopyrightNotice: The copyright notice for the original work
  • originalAttributionText: The name of the author of original that is adapted
  • originalAttributionUrl: URL to profile or home page of author of original.
  • originalRights: URL to license or policy document for original.

Presentation keys

The Attributions module will use the values bound to the metadata keys to provide text and links for the automatically generated attribution page and block. In addution, the Attributions module recognizes the following keys that is only used to structure the presentation of the metadata:

  • template: Defines a template string that may be used as a template for condtructing the attribution text.
  • weight: an optional integer that determines the weight of the resource.
  • hide: set to TRUE to hide the resource.
  • path: show the attribution block only on pages matching path (regexp)

The key template can be used to specify a text template for a custom attribution. You may use metadata keys, prefixed with the sigil @, to get the value of those keys inserted into the template. The string GPLv2+ is quoted to escape the +. There is no need to quote the template, even if it contains the YAML reserved indicator @, because the > indicates that this is a string.

sites/all/libraries/acmelib;
  type: code
  approved: https://www.drupal.org/node/123456
  license: 'GPLv2+'
  title: ACME Library
  attributionText: ACME Corporation
  template: >
    @title for PHP by @attributionText is relicensed for Drupal
    under GPLv2+ with permission from the authors.

 
The key weight accepts an integer value. It can be used to indicate the placement of the resource relative to other resources. The default weight value is 0, so you may a negative value to place the resource on top. In the example below, a comment in the Attributions Demo module's ASSETS.yml is assigned a negative weight value to make sure it is displayed before any of the (bogus) attributions shown by that module:

comment:
  type: comment
  weight: -1
  template: >
    The following list of attributions are only displayed for demo
    purposes. None of these resources are actually used by this
    module:

 
The key hide with a value set to TRUE can be used to indicate that the resource should not appear on the attribution page or in the attribution block. The use case for this key is to hide third party materials that one want to document using ASSETS.yml, but need not not appear in an attribution block that is visible on the site (for example: third party resources without a attribution requirement, such as MIT, GPL+FE, BSD SIL OFL, can be hidden). Example of use:

images/emptypurse.jpg:
  type: asset
  approved: allowed license
  hide: TRUE
  source: https://openclipart.org/detail/196212/empty-purse---portemonnaie
  license: public domain
  rights: https://openclipart.org/share

 
The key path may be used to specify a regular expression that must be matched for the attribution to appear in the attribution block. In this example, the attribution will only appear in the attribution block if the path to the page matches help_example/history:

help/180px-Lerdorf.jpg:
  type: asset
  approved: allowed license
  attributionText: Jud Dagnall
  source: http://en.wikipedia.org/wiki/File:Lerdorf.jpg
  title: Rasmus Lerdorf
  license: CC BY-SA 3.0
  rights: http://creativecommons.org/licenses/by-sa/3.0/deed.en
  path: 'help_example\/history'

 
Note that since the value assigned to path is a regular expression, the slash (/) must be escaped.

Troubleshooting

If your YAML does not parse, you may use one of the following online tools to check the validity of your YAML syntax:

Attribution semantics

Multiple licenses

Some projects are made available under multiple licenses, typically by including more than one license files, or by listing more than one license separated by commas, or with a conjunction (“and”, “or”). Examples:

MIT, BSD
MIT and GPL
MIT or GPL
MIT, BSD and GPL

 
If multiple licenses are listed, it is always assumed that the user can select any of them, not that they must accept all.

GNU GPL versions

There exists several versions of the GNU GPL. Each version is given a distinguishing version number. If a code library is simply licensed under (“GPL”) and does not specify a version number, you're may choose any version of the GNU GPL ever published by the Free Software Foundation. However, to use the library with Drupal, you should choose (“GNU GPL version 2 and later”.

If a code library specifies a version number of the GNU GPL License which applies to it and “any later version”, the user have the option of following the terms and conditions either of that version or of any later version of GNU GPL published by the Free Software Foundation.

For example, a code library licensed under one of the following specifications of the GNU GPL may be used in a project that is licensed under “GPL version 2 and later”, “GPL version 2”, “GPL version 3”:

GPL
GNU GPL version 2 and later
GNU GPL version 2 or later
GNU GPL version 2 and any later version
GPLv2+

 

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.