SMEbit YAML Reference

Field-level specification for SMEbit YAML definitions (smebits/smebit_*.yaml).

File Convention

• Location: smebits/smebit_*.yaml
• smebit_id must match the filename stem (e.g. smebit_foo.yaml requires smebit_id: smebit_foo)
• Validator: python3 scripts/smebitcheck.py
• Compiler: python3 scripts/smebitcompile.py

Levels

Level	Name	Has check block?	Produces dbt model?	Description
0	Observation	No	Registry only	Standalone knowledge — no SQL, no verdict
1	Check	Yes	Verdict model	Testable assertion compiled to SQL, produces confirmed/violated/no_data

Level is implicit: if the check block is present, it is Level 1. Otherwise Level 0.

Top-Level Fields

Field	Type	Required	Description
smebit_id	string	Yes	Must match filename stem
version	string	Yes	Semver (e.g. "1.0.0")
created_at	string	Warning	ISO date ("2026-03-17"). Validator warns if missing
modified_at	string	No	ISO date. Updated on change
provider	mapping	Yes	See Provider
scope	mapping	Yes	See Scope
category	string	Yes	See Valid Categories
tags	list of strings	No	Free-form tags for discoverability
subject	i18n mapping	Yes	One-line summary (en/de/fr required)
content	i18n mapping	Yes	Full explanation (en/de/fr required)
why	i18n mapping	Warning	Reason behind the observation (en/de/fr). Validator warns if missing but does not block
status	string	Yes	See Valid Statuses
superseded_by	string	Conditional	Required when status: superseded. Must reference an existing smebit_id
anchors	list	No	See Anchors
check	mapping	No	Presence makes this Level 1. See Check Block
prescription	mapping	No	See Prescription Block

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

Provider

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

Scope

Field	Type	Required	Description
tenant_id	string or null	No	Tenant this applies to. null = cross-tenant
source_system	string	No	Source system constraint
time_range	mapping	No	from and until (dates or null)

Valid Categories

Category	What it covers
data_quality	Incorrect or inconsistent values in source data
mapping	Wrong or outdated relationships between entities
business_rule	Known exceptions to standard patterns
process	How the organization actually works (workarounds, manual steps)
system	Known IT system limitations or behaviors
seasonal	Time-based patterns the SME knows about
historical	Past events that explain current data patterns
structural	Schema or modeling insights

Valid Statuses

Status	Description
active	Current, in effect
superseded	Replaced by another SMEbit (requires superseded_by)
contested	Under dispute or review
archived	No longer relevant

Anchors

Optional list of cross-references. Each entry must have at least one non-null field.

Field	Type	Required	Description
probe_id	string	No	Must reference an existing probes/*.yaml
hypothesis_id	string	No	Must reference an existing hypotheses/*.yaml
entity_type	string	No	Gold contract entity type
note	string	No	Free-text explanation of the link

Check Block

Present only on Level 1 SMEbits. Defines a testable SQL assertion.

Field	Type	Required	Description
description	i18n mapping	Yes	What the check verifies (at least en required)
entity_type	string	Yes	Gold contract entity type
query	string	Yes	SQL query using {{ ref('...') }} to reference dbt models
expect	string	Yes	confirmed or violated

The query can {{ ref() }} any layer (Bronze, Silver, Gold, signals). The verdict is confirmed if the query returns rows and expect: confirmed, or violated if it returns rows and expect: violated. no_data if the query returns no rows.

Prescription Block

Optional. Recommends a corrective action.

Field	Type	Required	Description
type	string	Yes	See Prescription Types
target_entity	string	Yes	Entity to modify
target_field	string	Yes	Field to modify
description	i18n mapping	Yes	What should be done (at least en required)
status	string	Yes	proposed, accepted, or implemented

Prescription Types

normalize_format, decompose_key, add_dimension, add_validation, reclassify, correct_mapping, redefine_grain, fix_ingestion

Examples

Level 0 — Observation (no check, registry only)

smebit_id: smebit_shanghai_customs_48h
version: "1.0.0"
created_at: "2026-03-17"
modified_at: "2026-03-17"

provider:
  name: Trade Compliance Team
  role: Customs Specialist
  date: 2026-03-17

scope:
  tenant_id: pacific_trade
  time_range:
    from: null
    until: null

category: business_rule
tags: [customs, shanghai]

subject:
  en: "Shanghai port holds containers for 48h minimum inspection for certain HS categories"
  de: "Der Hafen Shanghai haelt Container fuer bestimmte HS-Kategorien mindestens 48h zurueck"
  fr: "Le port de Shanghai retient les conteneurs pour une inspection minimale de 48h"

why:
  en: "Chinese customs regulation for high-value and controlled goods categories."
  de: "Chinesische Zollvorschrift fuer hochwertige und kontrollierte Warenkategorien."
  fr: "Reglementation douaniere chinoise pour les marchandises de haute valeur."

content:
  en: |
    Electronics (HS 84-85) and pharmaceutical products (HS 30) entering
    through Shanghai Yangshan port are subject to mandatory 48-hour
    inspection holds. This is a regulatory requirement, not a processing
    delay.
  de: |
    Elektronik (HS 84-85) und pharmazeutische Produkte (HS 30), die ueber
    den Hafen Shanghai Yangshan eingefuehrt werden, unterliegen einer
    obligatorischen 48-Stunden-Inspektionssperre.
  fr: |
    Les produits electroniques (SH 84-85) et pharmaceutiques (SH 30)
    entrant par le port de Shanghai Yangshan sont soumis a une retenue
    d'inspection obligatoire de 48 heures.

status: active

anchors:
  - probe_id: probe_dwell_time_anomaly
    note: "48h hold is regulatory, not anomalous"

Level 1 — Check (produces verdict model)

smebit_id: smebit_acme_item_638876a_wrong_description
version: "1.0.0"
created_at: "2026-03-10"
modified_at: "2026-03-10"

provider:
  name: Materials Management
  role: Data Steward
  date: 2026-03-10

scope:
  tenant_id: acme_corp
  time_range:
    from: null
    until: null

category: data_quality
tags: [item, description]

subject:
  en: "Item 638876a has wrong description in master data"
  de: "Artikel 638876a hat falsche Beschreibung in Stammdaten"
  fr: "L'article 638876a a une mauvaise description dans les donnees de base"

why:
  en: "Data entry error during initial catalogue import."
  de: "Dateneingabefehler beim initialen Katalogimport."
  fr: "Erreur de saisie lors de l'import initial du catalogue."

content:
  en: |
    Item 638876a is labelled "Widget A" but actually
    refers to Widget B. The description was swapped with item
    638876b during the 2024 catalogue migration.
  de: |
    Artikel 638876a ist als "Widget A" beschriftet,
    bezieht sich aber tatsaechlich auf Widget B.
  fr: |
    L'article 638876a est libelle "Widget A" mais
    designe en realite Widget B.

status: active

check:
  description:
    en: "Verify item 638876a still has wrong description"
    de: "Pruefen ob Artikel 638876a noch falsche Beschreibung hat"
    fr: "Verifier que l'article 638876a a encore la mauvaise description"
  entity_type: Material
  query: >
    SELECT material_id, description
    FROM {{ ref('gold_materials') }}
    WHERE material_id = '638876a'
      AND description ILIKE '%widget a%'
  expect: confirmed

prescription:
  type: correct_mapping
  target_entity: Material
  target_field: description
  description:
    en: "Update description from 'Widget A' to 'Widget B'"
    de: "Beschreibung von 'Widget A' zu 'Widget B' aendern"
    fr: "Mettre a jour la description de 'Widget A' a 'Widget B'"
  status: proposed

anchors:
  - probe_id: probe_catalogue_accuracy
    note: "This item will appear as a catalogue mismatch"