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