Regeln für agorum core YML-Dateien

Diese Dokumentation beschreibt praxiserprobte YML-Regeln für Konfigurationsdateien in agorum core (z. B. metadata.yml, structure-basis.yml, metadata-collection.yml, export.yml, project.yml). Ziel ist es, typische Parser- und Deployment-Fehler zu vermeiden und Dateien konsistent wartbar zu halten.

Hinweis: YAML ist ein eigenes Format. Viele Fehler entstehen nicht durch agorum core, sondern durch die Verwendung von Sonderzeichen oder inkonsistente Einrückungen.

Diese Regeln gelten für alle YML-Dateien, die in agorum core Konfigurationsprojekten unter /agorum/roi/customers/<Projekt>/yml/ verwendet werden.

Einrückung und Whitespace

Regel	Empfehlung
Einrückung muss konsistent sein.	Standard: 2 Leerzeichen. Keine Tabs.
Listenpunkte (`-`) gehören auf dieselbe Einrückungsebene wie das Listenfeld.	tags: - "A" - "B"
Trailing Spaces vermeiden.

Strings mit Sonderzeichen immer in Anführungszeichen setzen

YML interpretiert bestimmte Zeichen syntaktisch. Sobald ein String „ungewöhnlich“ ist, setzen Sie ihn in Anführungszeichen.

Doppelpunkt (:) im String

# ❌ falsch (führt häufig zu YAML-Parserfehlern)
regexText: Format muss sein: XX-YYYY-NNNNNN

# ✅ korrekt
regexText: "Format muss sein: XX-YYYY-NNNNNN"

Weitere Fälle, die Anführungszeichen brauchen (Best Practice)

# Zeichen am Anfang wie @ oder #
description: "@deprecated – bitte neues Feld verwenden"
comment: "#TODO: prüfen"

# Klammern, geschweifte Klammern, eckige Klammern
format: "${value}"
info: "[WICHTIG] Pflichtfeld"

# Pipe | oder > am Anfang
note: "|PIPE| benötigt Anführungszeichen"

Tipp: Wenn Sie unsicher sind: in Anführungszeichen setzen. YAML ist tolerant gegenüber Anführungszeichen – aber nicht gegenüber falsch interpretierten Sonderzeichen.

YML-Typisierung: reservierte Werte (true/false/yes/no/null)

YML wandelt viele Werte automatisch in Booleans oder Null um. Wenn diese Werte als String gespeichert werden sollen, müssen sie in Anführungszeichen gesetzt werden.

# ❌ wird als Boolean interpretiert
value: yes

# ✅ bleibt String
value: "yes"

# ❌ wird als null interpretiert
default: null

# ✅ bleibt String
default: "null"

Zahlen und Versionsnummern

YML kann Zahlen als Integer/Float interpretieren. Best Practice: Versionsnummern und IDs, die wie Zahlen aussehen, aber als String behandelt werden sollen, in Anführungszeichen setzen.

# ❌ 1.10 kann als 1.1 interpretiert werden
version: 1.10

# ✅ korrekt
version: "1.10"

Datum- und Formatstrings

Formatangaben (z. B. Datums-/Zahlformate) sollten immer in Anführungszeichen gesetzt werden – auch wenn es manchmal ohne Anführungszeichen funktioniert.

contract_start_date:
  type: date
  format: "dd.MM.yyyy"

amount:
  type: double
  format: "#,##0.00 €"

Regex in YAML (in Anführungszeichen setzen + Backslash doppeln)

Regex enthält fast immer Sonderzeichen. Darum: immer in Anführungszeichen setzen.

# ✅ korrekt
invoice_number:
  regex: "^[A-Z]{2}-[0-9]{4}-[0-9]{6}$"
  regexText: "Format: XX-YYYY-NNNNNN"

# Backslashes müssen in YML verdoppelt werden
pattern_digit: "\\d+"          # ergibt Regex: \d+
pattern_dot: "\\."            # ergibt Regex: \.

Listen und Arrays

Standardliste

priority:
  data:
    - "Low"
    - "Medium"
    - "High"

Liste mit Key-Value-Paaren

status:
  data:
    - [ draft, "Entwurf" ]
    - [ approved, "Freigegeben" ]
    - [ rejected, "Abgelehnt" ]

Inline-Liste

tags: ["A", "B", "C"]

Hinweis: In der structure-basis.yml werden Multi-Metadaten (Arrays) als YAML-Liste gesetzt (siehe dazu die Dokumentation im Abschnitt Listen / Multi-Metadaten).

Kommentare

Kommentare beginnen mit #. Achten Sie auf saubere Einrückung und kommentieren Sie komplexe Bereiche lieber über dem Eintrag statt inline.

# Globaler Kommentar
_prefix: demo_

field_name:
  type: string      # Inline-Kommentar