Tag Object Schema
==================

The ``tag`` type represents a Koji tag object.


Basic Structure
---------------

.. code-block:: yaml

   ---
   type: tag
   name: my-tag

   # Optional fields

   # Whether the tag is locked (prevents builds and other modifications)
   locked: false

   # Permission required to use this tag
   permission: admin

   # List of architectures this tag supports
   arches:
     - x86_64
     - aarch64

   # Whether Maven support is enabled for this tag
   maven-support: false

   # Whether to include all Maven artifacts in this tag
   maven-include-all: false

   # Additional tag metadata as key-value pairs
   extras:
     description: "My tag description"
     build_requires: "special-build-requirements"

   # List of extra fields that should be blocked from inheritance
   blocked-extras:
     - sensitive-data
     - internal-notes

   # Whether to enforce exact extras matching (removes undeclared extras)
   exact-extras: false

   # Package groups and their package lists. This is used to generate
   # the yum groups if this tag or one of its children is used as a
   # built tag in a target, and generates a repository.
   groups:
     my-group:
       - package1
       - package2

   # List of parent tags with their priorities
   inheritance:
     - parent: parent-tag
       priority: 10

   # List of external repositories attached to this tag
   external-repos:
     - name: my-repo
       priority: 100

   # List of packages in this tag. This is the list of build name
   # which are permitted to be tagged into this tag or its
   # children.
   packages:
     - package1
     - name: package2
       owner: dave-user-1

   # if True, then any packages which are in the real Koji tag
   # which are not defined in YAML will be removed from the real
   # tag.
   exact-packages: False


YAML Fields
-----------

Required Fields
~~~~~~~~~~~~~~~

``type`` (str)
   The type of the object, must be ``tag``

``name`` (str)
   The name of the tag


Optional Fields
~~~~~~~~~~~~~~~

``locked`` (boolean) - Default: False
   Whether the tag is locked (prevents builds and other modifications)

``permission`` (str)
   Permission required to use this tag

``arches`` (list of str)
   List of architectures this tag supports (e.g., ['x86_64', 'aarch64'])

``maven-support`` (boolean) - Default: False
   Whether Maven support is enabled for this tag

``maven-include-all`` (boolean) - Default: False
   Whether to include all Maven artifacts in this tag

``extras`` (dictionary of str to Any)
   Additional tag metadata as key-value pairs. These fields are inherited by child tags unless blocked.

``blocked-extras`` (list of str)
   List of extra field names that should be blocked from inheritance to child tags. These fields will not be passed down to tags that inherit from this tag.

``exact-extras`` (boolean) - Default: False
   Whether to enforce exact extras matching. When True, any extra fields present in the remote tag that are not declared in the YAML will be removed.

``groups`` (dict of str to TagGroup)
   Package groups and their package lists

``exact-groups`` (boolean) - Default: False
   Whether to remove undeclared groups or group packages from this tag

``inheritance`` (list of InheritanceLink)
   List of parent tags with their priorities

``external-repos`` (list of InheritanceLink)
   List of external repositories attached to this tag

``packages`` (list of PackageEntry)
   List of package names and their owners and blocked state

``exact-packages`` (boolean) - Default: False
   Whether to remove undeclared packages from this tag


Dependencies
------------

This object type depends on the ``tag`` object type for each parent tag listed in the
``inheritance`` field and the ``external-repo`` object type for each external repository listed in the
``external-repos`` field.


Technical Reference
-------------------

For developers: The ``tag`` object is implemented by the
:class:`koji_habitude.models.tag.Tag` class.