YAML is a human-readable data serialization format. The Drupal Git Repository Usage Policy requires assets contained in a repo to be specified in a file named ASSETS.yml. That uses a subset of this format for metadata.

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:

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).

This line must not be indented.

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.

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

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 tow 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:

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, license and provenance, of a resource:

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 fulfil 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 provenance. Only originalLicense is required by the LWG.

Again, the required key is necessary to fulfil the documentation requirements of the Drupal.org Git Repository policy. The other keys may be helpful for downstream recipients to determine the provenance of a resource.

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:

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 need to be documented in ASSETS.yml per Drupal.org Git Repo policy, but need not not appear in an attribution block on a site (e.g. resources that does not carry a public attribution requirement, such as MIT, GPL+FE, public domain or CC zero). 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: