Product SiteDocumentation Site

3.3. Merging metadata

3.3.1. Introduction

Sometimes it is required to merge new metadata into existing metadata that is shipped by a different party. This includes tools which want to inject recommendations into the AppStream metadata pool, or vendors who want to augment the data shipped by their distribution with custom information (e.g. custom icons or categories).
To make this task easier, a special merge component type exists, which is only valid in distro metadata. The merge component type is not a component type in the classical sense. It is used to extend or override metadata provided by a different component with the same id.

3.3.2. Example

If you want to add the components org.example.FooBar and org.example.Frobnicate to the category Video and also rename the component org.example.Frobnicate, this can be achieved by dropping a file like this one into the distro metadata pool directory:
<?xml version="1.0" encoding="UTF-8"?>
<components origin="vendor-customization">
  <component type="merge">
    <id>org.example.FooBar</id>
    <categories>
      <category>Video</category>
    </categories>
  </component>

  <component type="merge">
    <id>org.example.Frobnicate</id>
    <name>MyVendor Frobnicator</name>
    <categories>
      <category>Video</category>
    </categories>
  </component>
</components>

3.3.3. File specification

The merge component type is only valid in distro metadata and may never be used in metainfo files. The component tag must have its type attribute set to merge to create a valid merge component.
The <id/> tag is the only required tag for merge component. It defines the ID of the component whose data should be extended or overriden.

3.3.4. Merge rules

When merging metadata, AppStream implementations have to follow these rules to fold in merge component data into the data of the target component:
  • If the priority of the merge component and its target component are equal, or if the priority of the merge component is <= 0, the merge component will override the target components data for all non-list values (e.g. name, description, url types, etc.). For all list types (e.g. categories, provides, etc.) it will extend the list and append the new value to the preexisting values.
  • If the priority of the merge component is bigger than the one of its target component, the merge component will override the target components data for all values. This includes list-types, which get set to the exact value present in the merge component.
  • If there are multiple merge components, the one with the highest priority wins over the one with the lower priority.
  • In case the merge components have equal priorities and try to change the same value of the target component, the behavior is undefined.