BitBundle YAML Reference

Field-level specification for BitBundle YAML definitions (bitbundles/bb_*.yaml).

File Convention

• Location: bitbundles/bb_*.yaml
• bitbundle_id must match the filename stem and must start with bb_
• BitBundles are metadata-only: no SQL verdicts, no checks, no computation
• Compiles to two tables: bitbundle_registry and bitbundle_memberships
• Validator: python3 scripts/bitbundlecheck.py
• Compiler: python3 scripts/bitbundlecompile.py

Top-Level Fields

Field	Type	Required	Description
bitbundle_id	string	Yes	Must match filename stem. Must start with bb_
version	string	Yes	Semver (e.g. "1.0.0")
created_at	string	Warning	ISO date. Validator warns if missing
modified_at	string	No	ISO date. Updated on change
curator	mapping	Yes	See Curator
scope	mapping	Yes	See Scope
title	i18n mapping	Yes	Bundle title (en/de/fr required)
narrative	i18n mapping	Yes	Full narrative text (en/de/fr required)
smebits	list	Yes	Non-empty list of SMEbit references. See SMEbits List
status	string	Yes	active or archived
tags	list of strings	No	Free-form tags for discoverability

All i18n fields are mappings with keys en, de, fr (all three required).

Curator

Field	Type	Required	Description
name	string	Yes	Person or team name
role	string	Yes	Role or title
date	date	Yes	Date of curation (YYYY-MM-DD)

Scope

Field	Type	Required	Description
tenant_id	string or null	No	Tenant this applies to. null = cross-tenant

SMEbits List

Non-empty list. No duplicate smebit_id values allowed.

Field	Type	Required	Description
smebit_id	string	Yes	Must reference an existing smebits/*.yaml file
note	string or i18n mapping	No	Context note. Can be a plain string or an en/de/fr mapping

When note is an i18n mapping, missing languages produce a warning (not an error).

Example

bitbundle_id: bb_acme_item_data_quality
version: "1.0.0"
created_at: "2026-03-15"
modified_at: "2026-03-15"

curator:
  name: Materials Management
  role: Data Steward
  date: 2026-03-15

scope:
  tenant_id: acme_corp

title:
  en: "Item Master Data Quality Issues"
  de: "Artikelstammdaten-Qualitaetsprobleme"
  fr: "Problemes de qualite des donnees de base articles"

narrative:
  en: |
    A collection of known data quality issues in acme_corp's item
    master data, discovered during the initial catalogue migration from
    the legacy ERP. These SMEbits document specific items with wrong
    descriptions, misclassified categories, and outdated mappings.
  de: |
    Eine Sammlung bekannter Datenqualitaetsprobleme in den Artikelstammdaten
    von acme_corp, entdeckt waehrend der initialen Katalogmigration
    aus dem alten ERP.
  fr: |
    Une collection de problemes de qualite de donnees connus dans les
    donnees de base articles de acme_corp, decouverts lors de la
    migration initiale du catalogue depuis l'ancien ERP.

tags: [item, data-quality, catalogue]

smebits:
  - smebit_id: smebit_acme_item_638876a_wrong_description
    note:
      en: "Widget A / Widget B swap from 2024 migration"
      de: "Widget A / Widget B Vertauschung aus 2024 Migration"
      fr: "Echange Widget A / Widget B de la migration 2024"
  - smebit_id: smebit_acme_item_category_mismatch
    note: "Several high-value items classified under consumables"

status: active