YAML Features

The YAML file format, with ServiceX extensions, provides a compact way to represent ServiceX queries. Two features in particular reduce duplication and improve clarity: definitional anchors/aliases, and file inclusion.

Anchors and Aliases

Standard YAML provides anchors and aliases. An anchor is a string prefixed with & that names a particular YAML item; an alias is the same string prefixed with * that reuses it (conceptually similar to creating and dereferencing a pointer in C/C++). Anchors must be defined before use.

An anchor can be defined once and reused as an alias many times. For example, a cut defined as &DEF_mycut <cut definition> can be referenced elsewhere as *DEF_mycut. By convention, anchors are grouped in a Definitions block at the start of the file to avoid clutter in the General and Sample blocks and to eliminate ordering concerns.

A configuration file using this feature:

Definitions:
  - &DEF_query !PythonFunction |
        def run_query(input_filenames=None):
              return []

Sample:
  - Name: mysample
    Query: *DEF_query
    ...

Including Other YAML Files

ServiceX extends the standard YAML format with !include syntax, which inserts the contents of another YAML file in place.

A main YAML file using inclusion:

Definitions:
    !include definitions.yaml

Sample:
  - Name: mysample
    Query: *DEF_query
    ...

The included definitions.yaml:

- &DEF_query !PythonFunction |
        def run_query(input_filenames=None):
            return []

Factoring definitions into a separate file and referencing them via anchors and aliases keeps the top-level file readable.

String Handling

YAML provides several ways to embed multiline strings, which can produce unexpected results. The block scalar style — introducing a multiline string with a pipe (|) and using consistent indentation — is recommended. The YAML multiline reference demonstrates the available modes.