Multi Type Schema

The multi type is a special macro template that expands a single document containing key-value pairs into multiple YAML documents. This feature exists primarily to enable the use of YAML anchors across many objects, as YAML specification does not allow anchors to be shared between separate documents.

Basic Structure

---
type: multi

# Keys starting with 'x-' or '_' are ignored and can be used for
# metadata, extension fields, or YAML anchors
x-some-value: &some-value lalala
x-common-config: &common-config
  setting1: value1
  setting2: value2

# Each key-value pair where the value is a dictionary becomes a
# separate YAML document
alma-linux-10-build:
  type: tag
  extra-values:
    some: *some-value
    config: *common-config

alma-linux-9-build:
  type: tag
  extra-values:
    some: *some-value
    config: *common-config

alma-linux-10-candidate:
  type: target
  name: alma-linux-10-candidate
  build-tag: alma-linux-10-build

This expands to three separate documents:

---
type: tag
name: alma-linux-10-build
extra-values:
  some: lalala
  config:
    setting1: value1
    setting2: value2
---
type: tag
name: alma-linux-9-build
extra-values:
  some: lalala
  config:
    setting1: value1
    setting2: value2
---
type: target
name: alma-linux-10-candidate
build-tag: alma-linux-10-build

YAML Fields

Required Fields

type (str)

The type of the object, must be multi

Special Fields

Keys starting with _ or x-

These keys are ignored during expansion and can be used for:

  • YAML Anchors: Define anchors (&anchor-name) that can be referenced (*anchor-name) by all objects in the multi document

  • Metadata: Store metadata or extension fields that should not become separate documents

  • Shared Configuration: Define common values that multiple objects can reference

Example:

---
type: multi

x-version: &version "1.0.0"
x-common-extras: &common-extras
  maintainer: "team@example.com"
  project: "my-project"

my-tag:
  type: tag
  extras:
    version: *version
    maintainer: *common-extras

Object Entries

Each key-value pair where the value is a dictionary becomes a separate YAML document. The behavior depends on whether the dictionary has a name field:

  • If the dictionary has a ``name`` field: The object uses that name

  • If the dictionary lacks a ``name`` field: The key becomes the object’s name (automatically added)

Example with explicit names:

---
type: multi

my-tag:
  type: tag
  name: explicit-tag-name  # Uses this name

another-tag:
  type: tag
  # No name field, so 'another-tag' becomes the name

This expands to:

---
type: tag
name: explicit-tag-name
---
type: tag
name: another-tag

Expansion Rules

  1. Key Filtering: Keys starting with _ or x- are skipped and do not generate documents

  2. Empty Values: Keys with empty or falsy values are skipped

  3. Non-Dictionary Values: Keys with non-dictionary values are logged as debug messages and skipped

  4. Name Assignment: If a dictionary value doesn’t have a name field, the key is automatically assigned as the name

  5. Trace Information: Each generated document includes trace information indicating it came from a multi expansion

Use Cases

Shared YAML Anchors

The primary use case is to share YAML anchors across multiple objects. Since YAML anchors cannot be shared between separate documents, the multi type allows you to define anchors once and reference them in multiple objects:

---
type: multi

x-common-arches: &arches
  - x86_64
  - aarch64

tag1:
  type: tag
  arches: *arches

tag2:
  type: tag
  arches: *arches
Related Objects

Group related objects that share configuration patterns or need to reference common values:

---
type: multi

x-base-config: &base-config
  permission: admin
  locked: false

build-tag:
  type: tag
  <<: *base-config

dest-tag:
  type: tag
  <<: *base-config
Template Data Sharing

Provide shared template data that multiple objects need to reference without duplicating the data:

---
type: multi

x-product-info: &product-info
  product: "MyProduct"
  version: "1.0"
  release: "1"

product-build:
  type: tag
  extras:
    <<: *product-info

product-candidate:
  type: target
  build-tag: product-build
  extras:
    <<: *product-info

Dependencies

The multi type itself has no dependencies. However, each object generated from the multi document will have its own dependencies based on its type. For example, if a multi document contains tag objects with inheritance links, those will create dependencies on the parent tags.

Technical Reference

For developers: The multi type is implemented by the koji_habitude.templates.MultiTemplate class, which extends koji_habitude.templates.Template.