Entity YAML Reference

Field-level specification for Entity YAML definitions (entities/*.yaml).

File Convention

• Location: entities/*.yaml
• entity_id must match the filename stem (e.g. cases.yaml requires entity_id: cases)
• Columns are validated against contracts/gold_contract.v1.json
• Validator: python3 scripts/entitycheck.py
• Compiler: python3 scripts/entitycompile.py

Top-Level Fields

Field	Type	Required	Description
entity_id	string	Yes	Must match filename stem
created_at	string	No	ISO date ("2026-03-17")
modified_at	string	No	ISO date. Updated on change
dbt_model	string	Yes	Target dbt model name. Must start with gold_
display_name	i18n mapping	Yes	Human-readable name (en/de/fr required)
icon	string	No	Single character or emoji for UI display
is_browseable	boolean	No	Whether this entity appears in Explorer browse views
probe_entity_type	string	No	Gold contract entity type name (e.g. Case, BillingEvent). Must exist in gold_contract.v1.json
taxonomy	mapping	No	See Taxonomy
columns	mapping	Yes	See Columns
relationships	list	No	See Relationships

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

Columns

Defines which model columns serve which UI role. Column names are validated against the gold contract fields for the specified dbt_model.

Field	Type	Required	Description
primary_key	string	Yes	Surrogate key column
business_id	string	Yes	Human-readable business identifier
label	string	No	Main display label column
detail	string	No	Secondary detail column
timestamp	string or null	No	Primary timestamp column
amount	string or null	No	Primary monetary amount column
formats	mapping	No	Column-level format hints. See Column Formats

Column Formats

A mapping of column_name to format string. Column names must exist in the gold contract.

Format	Description
plain	No formatting
year	Year display (e.g. 2025)
currency	Monetary value with currency symbol
percent	Percentage value
number	Numeric with thousands separator
date	Date display
id	Identifier (monospace, no formatting)

Taxonomy

Field	Type	Required	Description
dimension_type	string or null	No	Taxonomy dimension type (e.g. cost_center)
caption_column	string	No	Column used as display caption in taxonomy views

Relationships

List of related entities. Each relationship defines a join from this entity to a target model.

Field	Type	Required	Description
target_model	string	Yes	Target dbt model name. Must start with gold_
join_column	string	Yes	Column on this entity to join from
target_join_column	string	Yes	Column on target model to join to
order_column	string	Yes	Column to order related records by
label	i18n mapping	Yes	Relationship display label (en/de/fr required)
custom_sql	string	No	Custom SQL for complex joins. Must contain {schema} and $1 placeholders

When custom_sql is provided, {schema} is replaced with the tenant schema and $1 with the entity’s primary key value at runtime.

Example

entity_id: cases
created_at: "2026-03-10"
modified_at: "2026-03-15"
dbt_model: gold_cases

display_name:
  en: Cases
  de: Faelle
  fr: Cas

icon: "+"
is_browseable: true

probe_entity_type: Case

taxonomy:
  dimension_type: null
  caption_column: case_id

columns:
  primary_key: case_key
  business_id: case_id
  label: case_id
  detail: case_type
  timestamp: admission_date
  amount: total_amount
  formats:
    admission_date: date
    discharge_date: date
    total_amount: currency
    case_year: year

relationships:
  - target_model: gold_billing_events
    join_column: case_id
    target_join_column: case_id
    order_column: billing_date
    label:
      en: Billing Events
      de: Rechnungspositionen
      fr: Evenements de facturation

  - target_model: gold_procedures
    join_column: case_id
    target_join_column: case_id
    order_column: procedure_date
    label:
      en: Procedures
      de: Prozeduren
      fr: Procedures