Compile Stage

The compile stage transforms YAML dataface definitions into normalized, validated CompiledFace objects ready for execution and rendering.

YAML string → parse → validate → normalize → size → CompiledFace

Entry Points

compile

The main entry point for compiling YAML content:

compile

compile(yaml_content: str, options: dict[str, Any] | None = None, base_dir: Path | None = None, project_dir: Path | None = None) -> CompileResult

Compile YAML content to a CompiledFace.

Stage: COMPILE (Full Pipeline)

This is the main entry point for compilation. It orchestrates: 1. PARSE: YAML string → Face object 2. VALIDATE: Check structure and references 3. NORMALIZE: Resolve references, add metadata

Layout sizing happens later in the render pipeline (data-aware).

PARAMETER	DESCRIPTION
yaml_content	YAML string to compile TYPE: str
options	Optional compilation options TYPE: dict[str, Any] | None DEFAULT: None
base_dir	Base directory for resolving file references TYPE: Path | None DEFAULT: None
project_dir	Project directory for resolving project-level sources TYPE: Path | None DEFAULT: None

RETURNS	DESCRIPTION
CompileResult	CompileResult with compiled face or errors

Example

yaml_content = ''' ... title: My Dataface ... queries: ... users: SELECT * FROM users ... charts: ... user_count: ... query: users ... type: kpi ... value: count ... rows: ... - user_count ... ''' result = compile(yaml_content) if result.success: ... face = result.face ... print(face.title) # "My Dataface"

Source code in dataface/core/compile/compiler.py

def compile(
    yaml_content: str,
    options: dict[str, Any] | None = None,
    base_dir: Path | None = None,
    project_dir: Path | None = None,
) -> CompileResult:
    """Compile YAML content to a CompiledFace.

    Stage: COMPILE (Full Pipeline)

    This is the main entry point for compilation. It orchestrates:
    1. PARSE: YAML string → Face object
    2. VALIDATE: Check structure and references
    3. NORMALIZE: Resolve references, add metadata

    Layout sizing happens later in the render pipeline (data-aware).

    Args:
        yaml_content: YAML string to compile
        options: Optional compilation options
        base_dir: Base directory for resolving file references
        project_dir: Project directory for resolving project-level sources

    Returns:
        CompileResult with compiled face or errors

    Example:
        >>> yaml_content = '''
        ... title: My Dataface
        ... queries:
        ...   users: SELECT * FROM users
        ... charts:
        ...   user_count:
        ...     query: users
        ...     type: kpi
        ...     value: count
        ... rows:
        ...   - user_count
        ... '''
        >>> result = compile(yaml_content)
        >>> if result.success:
        ...     face = result.face
        ...     print(face.title)  # "My Dataface"
    """
    options = options or {}
    errors: list[CompilationError] = []
    warnings: list[str] = []

    # ════════════════════════════════════════════════════════════════════
    # STEP 1: Parse YAML
    # ════════════════════════════════════════════════════════════════════
    # Convert YAML string to Face object. Handles syntax errors.
    try:
        face = parse_yaml(yaml_content)
    except ParseError as e:
        return CompileResult(errors=[e])

    # ════════════════════════════════════════════════════════════════════
    # STEP 2: Validate Structure
    # ════════════════════════════════════════════════════════════════════
    # Check references and semantic constraints.
    validation_errors = validate_face(face)
    if validation_errors:
        # Cast to List[CompilationError] since ValidationError inherits from it
        return CompileResult(errors=list(validation_errors))

    # ════════════════════════════════════════════════════════════════════
    # STEP 3: Get Default Source and Extract Named Sources
    # ════════════════════════════════════════════════════════════════════
    # Get project-level sources when available so named source references and
    # project defaults behave consistently for file-based compiles.
    project_sources = None
    if project_dir is not None:
        from dataface.core.compile.config import get_project_sources

        project_sources = get_project_sources(project_dir)

    # Get the face's default source to pass to query normalization.
    default_source = face.get_default_source()
    if default_source is None and project_sources is not None:
        default_source = project_sources.default

    # Extract named source configurations from the sources section
    # These are used to resolve source references in queries (e.g., source: profiles)
    sources_registry = {}
    if project_sources is not None:
        assert project_dir is not None
        sources_registry.update(
            resolve_project_source_paths(project_sources.sources, project_dir)
        )
    sources_registry.update(_extract_sources(face))

    # ════════════════════════════════════════════════════════════════════
    # STEP 4: Build Query Registry
    # ════════════════════════════════════════════════════════════════════
    # Collect and normalize all queries before normalization.
    # This allows charts to reference queries from any part of the face.
    try:
        query_registry = build_query_registry(
            face, base_dir, default_source=default_source
        )
    except CompilationError as e:
        return CompileResult(errors=[e])

    # ════════════════════════════════════════════════════════════════════
    # STEP 5: Detect Circular Dependencies
    # ════════════════════════════════════════════════════════════════════
    # Check for {{ queries.* }} cycles in SQL.
    if query_registry:
        try:
            detect_query_dependencies(query_registry)
        except JinjaError as e:
            return CompileResult(errors=[e])

    # ════════════════════════════════════════════════════════════════════
    # STEP 5b: Build Chart Registry
    # ════════════════════════════════════════════════════════════════════
    # Collect all charts from the entire face tree (global namespace).
    # Charts are global like queries - any layout can reference any chart.
    try:
        chart_registry = build_chart_registry(face, base_dir=base_dir)
    except CompilationError as e:
        return CompileResult(errors=[e])

    # ════════════════════════════════════════════════════════════════════
    # STEP 6: Normalize (Transform to CompiledFace)
    # ════════════════════════════════════════════════════════════════════
    # Resolve references, add metadata, create unified layout.
    # Note: Variable registry is built by renderer at render time (not needed here)
    try:
        compiled = normalize_face(
            face,
            query_registry=query_registry,
            chart_registry=chart_registry,
            base_path=base_dir,
        )
    except ReferenceError as e:
        return CompileResult(errors=[e])
    except CompilationError as e:
        return CompileResult(errors=[e])
    except PydanticValidationError as e:
        msg = format_validation_error(e, yaml_content)
        return CompileResult(errors=[CompilationError(msg)])

    compiled.sources = _to_plain_dict(sources_registry)

    # Orphan charts: defined but never referenced from any layout in the tree.
    # Warn rather than error — a content-only face still renders, the warning
    # surfaces lazy authoring. Render-side has the harder check for the
    # specific case of "face has charts but layout is empty" (Case A) which
    # would produce a silently empty dashboard.
    for chart_id in _collect_orphan_charts(compiled):
        warnings.append(
            f"Chart '{chart_id}' is defined but not referenced in any layout. "
            "Add it to `rows:`/`cols:`/`grid:`/`tabs:` or delete the definition."
        )

    # Layout dimensions are calculated later in the render pipeline
    # (after query execution) so table heights can use actual row counts.

    return CompileResult(
        face=compiled,
        errors=errors,
        warnings=warnings,
        query_registry=query_registry,
        meta_config=options.get("meta_config"),
    )

compile_file

Compile from a file path:

compile_file

compile_file(file_path: Path, options: dict[str, Any] | None = None, apply_meta: bool = True, root_path: Path | None = None) -> CompileResult

Compile a YAML file to a CompiledFace.

Convenience function that reads a file and compiles it. Optionally applies meta.yaml cascading configuration from parent directories.

PARAMETER	DESCRIPTION
file_path	Path to YAML file TYPE: Path
options	Optional compilation options TYPE: dict[str, Any] | None DEFAULT: None
apply_meta	If True, resolve and apply meta.yaml chain (default: True) TYPE: bool DEFAULT: True
root_path	Project root for meta resolution (default: auto-detect) TYPE: Path | None DEFAULT: None

RETURNS	DESCRIPTION
CompileResult	CompileResult with compiled face or errors

RAISES	DESCRIPTION
FileNotFoundError	If file doesn't exist

Example

result = compile_file(Path("face.yml")) if result.success: ... print(result.face.title)

Source code in dataface/core/compile/compiler.py

def compile_file(
    file_path: Path,
    options: dict[str, Any] | None = None,
    apply_meta: bool = True,
    root_path: Path | None = None,
) -> CompileResult:
    """Compile a YAML file to a CompiledFace.

    Convenience function that reads a file and compiles it. Optionally
    applies meta.yaml cascading configuration from parent directories.

    Args:
        file_path: Path to YAML file
        options: Optional compilation options
        apply_meta: If True, resolve and apply meta.yaml chain (default: True)
        root_path: Project root for meta resolution (default: auto-detect)

    Returns:
        CompileResult with compiled face or errors

    Raises:
        FileNotFoundError: If file doesn't exist

    Example:
        >>> result = compile_file(Path("face.yml"))
        >>> if result.success:
        ...     print(result.face.title)
    """

    if isinstance(file_path, str):
        file_path = Path(file_path)

    if not file_path.exists():
        return CompileResult(errors=[CompilationError(f"File not found: {file_path}")])

    # Markdown report files: translate to YAML before compiling
    if file_path.suffix.lower() == ".md":
        from dataface.core.compile.markdown import markdown_to_yaml

        try:
            raw_text = file_path.read_text()
            yaml_content = markdown_to_yaml(raw_text)
        except (OSError, ValueError) as e:
            return CompileResult(
                errors=[CompilationError(f"Markdown parse error: {e}")]
            )
    else:
        try:
            yaml_content = file_path.read_text()
        except OSError as e:
            return CompileResult(errors=[CompilationError(f"Failed to read file: {e}")])

    # Apply meta.yaml chain if enabled
    meta_config = None
    if apply_meta:
        try:
            # Parse YAML to dict first
            face_data = yaml.safe_load(yaml_content) or {}

            # Resolve meta chain and merge with face
            meta_config = get_meta_for_face(file_path, root_path=root_path)
            if not meta_config.is_empty():
                merged_data = merge_meta_with_face(meta_config, face_data)
                # Re-serialize to YAML for the compile function
                yaml_content = yaml.dump(merged_data, default_flow_style=False)
        except CompilationError as e:
            return CompileResult(errors=[e])
        except (yaml.YAMLError, OSError) as e:
            # Meta resolution errors are warnings, not failures
            # Continue with original content, but log the issue for debugging
            logger.warning(
                "Meta resolution failed for %s, continuing with original content: %s",
                file_path,
                e,
            )

    project_dir = root_path
    if project_dir is None:
        from dataface.core.project_roots import discover_render_context

        compile_boundary = Path(file_path.anchor) if file_path.anchor else None
        project_dir, _ = discover_render_context(file_path.parent, compile_boundary)

    # Thread meta lint config through to compile for query diagnostics
    compile_options = dict(options) if options else {}
    if meta_config is not None:
        compile_options["meta_config"] = meta_config

    return compile(
        yaml_content,
        options=compile_options,
        base_dir=file_path.parent,
        project_dir=project_dir,
    )

CompileResult

The result object returned by compilation:

CompileResult dataclass

CompileResult(face: CompiledFace | None = None, errors: list[CompilationError] = list(), warnings: list[str] = list(), suppressed_warnings: list[str] = list(), diagnostics: list[QueryDiagnostic] = list(), query_registry: dict[str, CompiledQuery] = dict(), meta_config: Any = None)

Result of compilation.

Contains the compiled face (if successful), any errors encountered, and warnings that don't prevent compilation.

ATTRIBUTE	DESCRIPTION
face	Compiled face (None if errors occurred) TYPE: CompiledFace | None
errors	List of compilation errors TYPE: list[CompilationError]
warnings	List of non-fatal warnings (human-readable strings) TYPE: list[str]
diagnostics	Structured query diagnostics from validate_compiled_queries. Includes all severity levels; warnings only includes warning+error. Infrastructure for structured consumers (UI, AI agents). TYPE: list[QueryDiagnostic]
query_registry	All normalized queries (for executor) TYPE: dict[str, CompiledQuery]
sources	Source configurations (for resolving named source references) TYPE: dict[str, CompiledQuery]

Example

result = compile(yaml_content) if result.success: ... print(f"Compiled: {result.face.title}") ... else: ... for error in result.errors: ... print(f"Error: {error}")

success property

success: bool

Check if compilation was successful.

---

Compiled Types

These types represent the output of compilation, with all fields guaranteed to be present.

CompiledFace

CompiledFace

Bases: BaseModel

Compiled face ready for execution and rendering.

Stage: COMPILE output / EXECUTE and RENDER input

This is the main output of compilation. It contains: - Resolved definitions (variables, queries, charts) - Unified layout structure - Calculated dimensions - Applied defaults and metadata

Guarantees

• id: Always set
• title: Always set (empty string if not provided)
• layout: Always present (unified structure)
• All charts resolved to CompiledChart objects
• All queries resolved to query objects

ATTRIBUTE	DESCRIPTION
id	Unique identifier for this face TYPE: str
title	Display title TYPE: str
description	Description text TYPE: str
variables	Variable definitions (Dict[str, Variable]) TYPE: dict[str, Variable]
queries	Compiled queries (Dict[str, CompiledQuery]) TYPE: dict[str, CompiledQuery]
charts	Compiled charts (Dict[str, CompiledChart]) TYPE: dict[str, CompiledChart]
layout	Unified layout structure TYPE: Layout
variable_defaults	Resolved default values for variables TYPE: VariableValues
style	Face styling TYPE: FaceStyle

Example: >>> result = compile(yaml_content) >>> face = result.face >>> print(face.id) # "sales-dataface" >>> print(face.title) # "Sales Dataface" >>> print(face.layout.type) # "rows" >>> for item in face.layout.items: ... chart = item.chart ... print(f"Chart: {chart.id}, Query: {chart.query_name}")

visible_variables property

visible_variables: dict[str, Variable]

Return variables that are not hidden (available for UI controls).

parse_style_dict classmethod

parse_style_dict(data: Any) -> Any

Convert style dict to FaceStyle.

Source code in dataface/core/compile/compiled_types.py

@model_validator(mode="before")
@classmethod
def parse_style_dict(cls, data: Any) -> Any:
    """Convert style dict to FaceStyle."""
    if isinstance(data, dict):
        style_value = data.get("style")
        if isinstance(style_value, dict):
            data["style"] = FaceStyle.from_dict(style_value)
    return data

CompiledChart

CompiledChart

Bases: ChartFields

Compiled chart ready for execution and rendering.

Stage: COMPILE output / EXECUTE and RENDER input

Inherits shared data-mapping, geo, and interaction fields from ChartFields. Adds compiled-specific fields (id, resolved query, variable_dependencies, etc.) with guaranteed structure.

Guarantees vs ChartPatch (input type): | Field | ChartPatch (input) | CompiledChart (compiled) | |-------------|-----------------------|----------------------------| | id | Optional[str] | str (always present) | | title | Optional[str] | str (empty string default) | | subtitle | Optional[str] | str (empty string default) | | description | Optional[str] | str (empty string default) | | query | str (reference) | Query object (resolved) |

Downstream code can access fields directly without checking for None.

ATTRIBUTE	DESCRIPTION
id	Unique identifier within the dashboard. TYPE: str
query	Resolved query object (SqlQuery, CsvQuery, etc.) TYPE: CompiledQuery | None
query_name	String name for executor lookup. TYPE: str | None
type	Chart type (line, bar, table, etc.) TYPE: str
title	Display title. Empty string if not provided. TYPE: str
subtitle	Secondary title line. Empty string if not provided. TYPE: str
description	Description. Empty string if not provided. TYPE: str

convert_dicts_to_typed classmethod

convert_dicts_to_typed(data: Any) -> Any

Auto-convert dict to typed models for style field.

Compiled charts are expected to come from normalized Chart input, which already validates the Vega-Lite passthrough contract. Keep this hook limited to internal wrapper conversions needed by downstream code.

Source code in dataface/core/compile/compiled_types.py

@model_validator(mode="before")
@classmethod
def convert_dicts_to_typed(cls, data: Any) -> Any:
    """Auto-convert dict to typed models for style field.

    Compiled charts are expected to come from normalized ``Chart`` input,
    which already validates the Vega-Lite passthrough contract. Keep this
    hook limited to internal wrapper conversions needed by downstream code.
    """
    if isinstance(data, dict):
        if "style" in data and isinstance(data["style"], dict):
            from dataface.core.compile.style_model import (
                ChartStylePatch,
            )
            from dataface.core.compile.style_normalize import (
                normalize_chart_local_style_dict,
            )

            data["style"] = ChartStylePatch.model_validate(
                normalize_chart_local_style_dict(data.get("type"), data["style"])
            )
    return data

validate_kpi

validate_kpi() -> CompiledChart

Validate KPI charts have a value (column reference or literal).

Note: This only validates when type is explicitly "kpi". When type is "auto", validation is deferred to render time.

Source code in dataface/core/compile/compiled_types.py

@model_validator(mode="after")
def validate_kpi(self) -> "CompiledChart":
    """Validate KPI charts have a `value` (column reference or literal).

    Note: This only validates when type is explicitly "kpi".
    When type is "auto", validation is deferred to render time.
    """
    if self.type == "kpi" and self.value is None:
        raise ValueError(
            "KPI charts must specify a 'value' field "
            "(column reference or literal scalar)."
        )
    return self

validate_error

validate_error() -> CompiledChart

Validate error charts have message field.

Source code in dataface/core/compile/compiled_types.py

@model_validator(mode="after")
def validate_error(self) -> "CompiledChart":
    """Validate error charts have message field."""
    if self.type == "error" and not self.message:
        raise ValueError("Error charts must specify a 'message' field")
    return self

validate_explicit_chart_surface

validate_explicit_chart_surface() -> CompiledChart

Validate line and pie charts against explicit allowed terms.

Source code in dataface/core/compile/compiled_types.py

@model_validator(mode="after")
def validate_explicit_chart_surface(self) -> "CompiledChart":
    """Validate line and pie charts against explicit allowed terms."""
    if self.type == "donut":
        raise ValueError(
            "CompiledChart should not have type='donut'. "
            "Use type='pie' with inner_radius instead — "
            "the normalizer converts donut to pie before compilation."
        )
    _validate_chart_surface(self)
    return self

to_dict

to_dict() -> dict[str, Any]

Convert chart to YAML-compatible dict.

Returns a minimal dict suitable for YAML serialization, excluding internal/computed fields like variable_dependencies.

RETURNS	DESCRIPTION
dict[str, Any]	Dict representation suitable for YAML export

Source code in dataface/core/compile/compiled_types.py

def to_dict(self) -> dict[str, Any]:
    """Convert chart to YAML-compatible dict.

    Returns a minimal dict suitable for YAML serialization,
    excluding internal/computed fields like variable_dependencies.

    Returns:
        Dict representation suitable for YAML export
    """
    from dataface.core.render.chart.presentation import to_plain_dict

    result: dict[str, Any] = {}

    # Basic fields
    if self.title:
        result["title"] = self.title
    if self.label:
        result["label"] = self.label
    if self.type:
        result["type"] = self.type

    # Query - convert to inline format
    if self.query:
        query_dict: dict[str, Any] = {}
        if hasattr(self.query, "sql") and self.query.sql:
            query_dict["sql"] = self.query.sql
        # Only include source if it's a string reference
        if (
            hasattr(self.query, "source")
            and self.query.source
            and isinstance(self.query.source, str)
        ):
            query_dict["source"] = self.query.source
        if hasattr(self.query, "file") and self.query.file:
            query_dict["file"] = self.query.file
        if query_dict:
            result["query"] = query_dict

    # Data mappings
    if self.x:
        result["x"] = self.x
    if self.y:
        result["y"] = self.y
    if self.color:
        result["color"] = self.color
    if self.size:
        result["size"] = self.size
    if self.shape:
        result["shape"] = self.shape
    if self.theta:
        result["theta"] = self.theta
    if self.inner_radius is not None:
        result["inner_radius"] = self.inner_radius

    # KPI / map shared `value` is serialized below in the geo block;
    # KPI's structured fields (glyph/tone/support) follow.
    if self.format:
        if hasattr(self.format, "model_dump"):
            result["format"] = self.format.model_dump(exclude_none=True)
        else:
            result["format"] = self.format
    if self.message:
        result["message"] = self.message

    # Map-specific (`value` is shared with KPI as the column-or-literal binding)
    if self.geo:
        result["geo"] = self.geo
    if self.geo_source:
        result["geo_source"] = self.geo_source
    if self.lookup:
        result["lookup"] = self.lookup
    if self.value is not None:
        result["value"] = self.value
    if self.glyph:
        result["glyph"] = self.glyph
    if self.tone:
        result["tone"] = self.tone
    if self.value_color:
        result["value_color"] = self.value_color
    if self.glyph_color:
        result["glyph_color"] = self.glyph_color
    if self.support is not None:
        result["support"] = self.support.model_dump(exclude_none=True)
    if self.projection:
        result["projection"] = (
            self.projection
            if isinstance(self.projection, str)
            else to_plain_dict(self.projection)
        )
    if self.latitude:
        result["latitude"] = self.latitude
    if self.longitude:
        result["longitude"] = self.longitude
    if self.background:
        result["background"] = self.background
    if self.sort:
        result["sort"] = self.sort.model_dump(exclude_none=True)

    # Styling
    if self.style:
        result["style"] = self.style.model_dump(exclude_none=True)

    # Click interactivity
    if self.href:
        result["href"] = self.href

    if self.filters:
        result["filters"] = self.filters

    return result

get_dependencies

get_dependencies() -> ChartDependencies

Get all dependencies required to render this chart.

Collects sources, variables, and queries that this chart needs. Use this to extract minimal preview dashboards.

RETURNS	DESCRIPTION
ChartDependencies	ChartDependencies with sources, variables, and queries needed

Source code in dataface/core/compile/compiled_types.py

def get_dependencies(self) -> "ChartDependencies":
    """Get all dependencies required to render this chart.

    Collects sources, variables, and queries that this chart needs.
    Use this to extract minimal preview dashboards.

    Returns:
        ChartDependencies with sources, variables, and queries needed
    """
    deps = ChartDependencies()

    # Add variable dependencies (from chart title, filters, query SQL, etc.)
    deps.variables = self.variable_dependencies.copy()

    # Add query variable dependencies
    if self.query and hasattr(self.query, "variable_dependencies"):
        deps.variables |= self.query.variable_dependencies

    # Add source from query
    if self.query:
        source = getattr(self.query, "source", None)
        if isinstance(source, str):
            deps.sources.add(source)

    return deps

LayoutItem

LayoutItem

Bases: BaseModel

A single item in a layout.

Represents either a chart or a nested face in the layout. The unified structure makes iteration simple:

for item in layout.items:
    if item.type == "chart":
        render_chart(item.chart)
    else:
        render_face(item.face)

ATTRIBUTE	DESCRIPTION
type	Either "chart" or "face" TYPE: Literal['chart', 'face']
chart	CompiledChart if type == "chart" TYPE: CompiledChart | None
face	CompiledFace if type == "face" TYPE: CompiledFace | None

Grid-specific (optional): row, col: Grid position (0-based) row_span, col_span: Grid span (in grid units)

Calculated dimensions (set by sizing module): width_fraction: What fraction of parent width (0.0-1.0) width: Pixel width height: Pixel height x: X position in pixels y: Y position in pixels

---

Query Types

Dataface supports multiple query types through a unified interface.

SqlQuery

SqlQuery

Bases: Query

SQL query against a database.

Executes raw SQL against the configured database connection. Supports Jinja templating for variable substitution.

Required Fields

sql: SQL query string (may contain Jinja templates)

Connection Fields (one required): source: Source name or inline config

Optional Fields

target: dbt target name (defaults to 'dev' if not specified)

Example

query = SqlQuery( ... sql="SELECT * FROM users WHERE id = {{ user_id }}", ... source="my_postgres" ... ) query.query_type # "sql" query.source_description # "SQL: SELECT * FROM users WHERE id = {{ user_..."

query_type property

query_type: str

Return 'sql' as query type.

source_description property

source_description: str

Return truncated SQL for description.

CsvQuery

CsvQuery

Bases: Query

Query data from a CSV file.

Loads and queries data from CSV files. Supports column selection, filtering, and limiting results.

Fields (one required): file: Path to CSV file (relative to project root or absolute) source: Source reference or inline CSV source config

Optional Fields

columns: List of columns to select (default: all) filter: Dict of column->value for exact match filtering

Example

query = CsvQuery(file="data/sales.csv", columns=["date", "amount"]) query.query_type # "csv" query.source_description # "CSV: data/sales.csv"

query_type property

query_type: str

Return 'csv' as query type.

source_description property

source_description: str

Return file path for description.

effective_file property

effective_file: str | None

Get effective file path from file or source config.

HttpQuery

HttpQuery

Bases: Query

Query data from an HTTP API.

Fetches data from REST API endpoints. Supports various HTTP methods, headers, query parameters, and request bodies.

Fields

url: Full URL of the API endpoint (legacy) source: Source reference or inline HTTP source config (new) path: API path (appended to base URL from source)

Optional Fields

method: HTTP method (default: GET) headers: Request headers (merged with source headers) params: Query parameters body: Request body (for POST/PUT/PATCH) json_path: JSONPath expression to extract data from response

Example

query = HttpQuery( ... source="model_api", ... path="/predict", ... method="POST", ... body={"input": "data"} ... ) query.query_type # "http" query.source_description # "HTTP: POST model_api/predict"

query_type property

query_type: str

Return 'http' as query type.

source_description property

source_description: str

Return method and URL for description.

MetricFlowQuery

MetricFlowQuery

Bases: Query

Query the dbt Semantic Layer.

Executes queries against dbt's Semantic Layer using MetricFlow. Supports metrics, dimensions, filters, and time grains.

Required Fields

metrics: List of metric names to query

Optional Fields

dimensions: List of dimension names to group by time_grain: Time grain for time-based dimensions (day, week, month, etc.)

Example

query = MetricFlowQuery( ... metrics=["revenue", "orders"], ... dimensions=["date_day", "region"] ... ) query.query_type # "metricflow" query.source_description # "MetricFlow: revenue, orders"

query_type property

query_type: str

Return 'metricflow' as query type.

source_description property

source_description: str

Return metrics list for description.

---

Input Types

These types represent the raw YAML structure before normalization.

Face

Face

Bases: BaseModel

Face (dataface) definition from YAML.

This is the top-level input type representing a complete dataface. A face contains definitions (variables, queries, charts) and a layout.

Example YAML

title: Sales Dataface description: Overview of sales metrics

sources: default: my_postgres # Default source for all queries

variables: date_range: input: daterange default: ["2024-01-01", "2024-12-31"]

queries: sales: SELECT * FROM sales WHERE date BETWEEN ...

charts: revenue: query: sales type: line x: date y: amount

rows: - revenue

Layout

Exactly one layout type should be present (rows, cols, grid, or tabs). Layout items can be: - Chart name (string reference) - Inline chart definition (dict with query and type) - Nested face (dict with layout keys)

Sources

Optional sources section with: - default: Default source name for all queries in this face - Inline source definitions (source_name: {...config...})

reject_face_key classmethod

reject_face_key(data: Any) -> Any

Reject 'face' as a top-level key.

Source code in dataface/core/compile/types.py

@model_validator(mode="before")
@classmethod
def reject_face_key(cls, data: Any) -> Any:
    """Reject 'face' as a top-level key."""
    if isinstance(data, dict) and "face" in data:
        raise ValueError(
            "'face:' is not valid. Face properties (title, rows, queries, etc.) "
            "should be at the top level of the YAML file, not nested under 'face:'."
        )
    return data

validate_layout

validate_layout() -> Face

Ensure at least one layout type or content is defined.

Source code in dataface/core/compile/types.py

@model_validator(mode="after")
def validate_layout(self) -> "Face":
    """Ensure at least one layout type or content is defined."""
    layouts = [self.rows, self.cols, self.grid, self.tabs]
    defined = [layout for layout in layouts if layout is not None]
    if len(defined) > 1:
        raise ValueError(
            "Face can only have one layout type (rows, cols, grid, or tabs)"
        )
    if len(defined) == 0 and not self.text:
        raise ValueError("Face must have at least one layout type or text")
    return self

get_default_source

get_default_source() -> str | None

Get the default source for this face.

RETURNS	DESCRIPTION
str | None	Default source name, or None if not set

Source code in dataface/core/compile/types.py

def get_default_source(self) -> str | None:
    """Get the default source for this face.

    Returns:
        Default source name, or None if not set
    """
    # Single source shorthand takes precedence
    if self.source:
        return self.source
    # Then check sources.default
    if self.sources:
        if isinstance(self.sources, SourcesSection):
            return self.sources.default
        elif isinstance(self.sources, dict):
            return self.sources.get("default")
    return None

Chart

Chart

Bases: ChartFields

Sparse authored chart input from board YAML.

All fields optional. Validated during YAML parsing, then normalized into CompiledChart during compilation.

ChartPatch → CompiledChart

Chart-local style uses ChartStylePatch for typed, closed-contract overlay.

Example YAML::

charts:
  revenue_trend:
    query: sales_by_date
    type: line
    title: "Revenue Trend"
    x: date
    y: amount
    color: category
    style:
      background: "#f8f8f8"

reject_removed_vl_passthrough_fields classmethod

reject_removed_vl_passthrough_fields(data: Any) -> Any

Reject removed chart-level VL passthrough fields with a clear error.

The normalizer rejects these first for standard compilation paths; this validator is a fallback for direct ChartPatch construction.

Source code in dataface/core/compile/chart.py

@model_validator(mode="before")
@classmethod
def reject_removed_vl_passthrough_fields(cls, data: Any) -> Any:
    """Reject removed chart-level VL passthrough fields with a clear error.

    The normalizer rejects these first for standard compilation paths; this
    validator is a fallback for direct ChartPatch construction.
    """
    if isinstance(data, dict):
        if "style" in data and isinstance(data["style"], dict):
            data["style"] = ChartStylePatch.model_validate(
                normalize_chart_local_style_dict(data.get("type"), data["style"])
            )
        removed = [
            field
            for field in (
                "mark",
                "encoding",
                "spec",
                "config",
                "transform",
                "params",
                "resolve",
                "hconcat",
                "vconcat",
                "concat",
                "repeat",
            )
            if field in data
        ]
        if removed:
            fields = ", ".join(f"`{field}`" for field in removed)
            raise ValueError(
                f"{fields} are not part of the authored Dataface chart surface. "
                "Use top-level channels and typed `style` instead."
            )
        if "metric" in data:
            # KPI's column reference was renamed `metric` → `value` to align
            # with the rest of the chart family (and avoid the dbt MetricFlow
            # `metric:` collision). See
            # tasks/workstreams/graph-library/tasks/redefine-kpi-as-dft-quantitative-text-object.md.
            raise ValueError(
                "`metric:` was renamed to `value:` for KPI charts. "
                "Replace `metric: <column>` with `value: <column>`."
            )
        # Reject `subtitle:` only when the author explicitly typed the
        # chart as KPI. ``type: auto`` may resolve to bar/line/etc. at
        # render time — those legitimately still accept ``subtitle:`` —
        # so we don't pre-emptively reject on auto. Shared truthy-only
        # predicate with the YAML compile-path gate; see
        # normalize_charts._kpi_subtitle_error for the canonical message.
        if data.get("type") == "kpi" and data.get("subtitle"):
            from dataface.core.compile.normalize_charts import (  # noqa: PLC0415
                _kpi_subtitle_error,
            )

            raise ValueError(_kpi_subtitle_error(data.get("id")))
    return data

validate_kpi

validate_kpi() -> ChartPatch

KPI charts must specify a value (column reference or literal).

Source code in dataface/core/compile/chart.py

@model_validator(mode="after")
def validate_kpi(self) -> ChartPatch:
    """KPI charts must specify a `value` (column reference or literal)."""
    if self.type == "kpi" and self.value is None:
        raise ValueError(
            "KPI charts must specify a 'value' field "
            "(column reference or literal scalar)."
        )
    return self

validate_error

validate_error() -> ChartPatch

Error charts must specify a message.

Source code in dataface/core/compile/chart.py

@model_validator(mode="after")
def validate_error(self) -> ChartPatch:
    """Error charts must specify a message."""
    if self.type == "error" and not self.message:
        raise ValueError("Error charts must specify a 'message' field")
    return self

validate_layered

validate_layered() -> ChartPatch

Layered charts require non-empty layers; layers require type: layered.

Source code in dataface/core/compile/chart.py

@model_validator(mode="after")
def validate_layered(self) -> ChartPatch:
    """Layered charts require non-empty layers; layers require type: layered."""
    if self.type == "layered":
        if not self.layers:
            raise ValueError(
                "Layered charts require a non-empty `layers` list. "
                "Each layer must specify a `type` (e.g. bar, line)."
            )
    elif self.layers:
        raise ValueError(
            "`layers` is only valid on `type: layered` charts. "
            "Set `type: layered` or remove the `layers` field."
        )
    return self

validate_explicit_chart_surface

validate_explicit_chart_surface() -> ChartPatch

Validate line and pie charts against explicit allowed terms.

Source code in dataface/core/compile/chart.py

@model_validator(mode="after")
def validate_explicit_chart_surface(self) -> ChartPatch:
    """Validate line and pie charts against explicit allowed terms."""
    _validate_chart_surface(self)
    return self

validate_data_table

validate_data_table() -> ChartPatch

Validate the data_table block at the ChartPatch layer.

Covers the data-free portion of spec §3: - Chart-type eligibility (bar, line, area; everything else rejects with a single unified error per ADR-006). - Multi-y / layered rejection (spec §1 single-unambiguous-x). - Duplicate-entry rejection (spec §3.2).

Data-aware checks (source-column existence, multi-row-per-x ambiguity, x-axis cardinality > 40) live in the render pipeline where query output is known.

Source code in dataface/core/compile/chart.py

@model_validator(mode="after")
def validate_data_table(self) -> ChartPatch:
    """Validate the data_table block at the ChartPatch layer.

    Covers the data-free portion of spec §3:
    - Chart-type eligibility (bar, line, area; everything else rejects
      with a single unified error per ADR-006).
    - Multi-y / layered rejection (spec §1 single-unambiguous-x).
    - Duplicate-entry rejection (spec §3.2).

    Data-aware checks (source-column existence, multi-row-per-x
    ambiguity, x-axis cardinality > 40) live in the render pipeline
    where query output is known.
    """
    if self.data_table is None:
        return self

    # Chart-type eligibility (spec §1, ADR-006).
    if self.type is not None and self.type not in CHART_DATA_TABLE_SUPPORTED_TYPES:
        supported = ", ".join(sorted(CHART_DATA_TABLE_SUPPORTED_TYPES))
        raise ValueError(
            f"chart.data_table is not supported for chart type "
            f"{self.type!r} in v1. Supported chart types: {supported}."
        )

    # Multi-y list breaks the single-unambiguous-x guarantee the
    # primitive requires (spec §1, review CRITICAL 5). Fail fast at
    # authoring rather than silently dropping the block in the renderer.
    if isinstance(self.y, list) and len(self.y) > 1:
        raise ValueError(
            "chart.data_table is not supported on charts with a "
            "multi-field `y:` list. The attached strip needs a single "
            "unambiguous x-encoding. Collapse `y:` to one field, or "
            "move the extra fields into separate `data_table:` rows."
        )

    # Layered charts are supported when they share a single top-level
    # x-encoding and a single chart-level query. Per-layer `query:` or
    # per-layer `x:` that differs from the chart-level x breaks one of
    # the two preconditions cell alignment requires.
    if self.layers:
        for i, layer in enumerate(self.layers):
            if layer.query is not None:
                raise ValueError(
                    f"chart.data_table is not supported on layered "
                    f"charts with per-layer `query:` (layer {i} sets "
                    f"query={layer.query!r}). The strip reads "
                    f"`source:` columns from a single resolved "
                    f"dataset; move the query to the chart level."
                )
            if layer.x is not None and layer.x != self.x:
                if self.x is None:
                    raise ValueError(
                        f"chart.data_table requires a chart-level `x:` "
                        f"on layered charts (layer {i} sets x={layer.x!r} "
                        f"but the chart itself has no x). Lift the "
                        f"shared x to the chart level so the strip "
                        f"cells have ONE x-scale to position against."
                    )
                raise ValueError(
                    f"chart.data_table is not supported on layered "
                    f"charts with per-layer `x:` that differs from the "
                    f"chart-level x (layer {i} sets x={layer.x!r}, "
                    f"chart.x={self.x!r}). The strip cells need ONE "
                    f"x-scale to position against."
                )

    # Validate per_series entries require a color channel.
    has_per_series = any(
        isinstance(e, ChartDataTablePerSeries) for e in self.data_table.entries
    )
    if has_per_series:
        color = self.color
        has_color = color is not None and color != ""
        if not has_color:
            raise ValueError(
                "chart.data_table per_series: entries require the chart to have "
                "a color: channel (the series to expand). Add `color: <field>` "
                "to the chart, or replace per_series: with aggregate: or source:."
            )

    # Data-free entry validation (duplicates).
    validate_data_table_shape(self.data_table.entries)
    return self

Query

Query

Bases: BaseModel

Query definition from YAML.

Queries fetch data from various sources. The type field determines which adapter handles execution.

Supported types: - sql: Raw SQL query (default) - metricflow: dbt Semantic Layer query - dbt_model: Query against a dbt model - http: REST API query - csv: CSV file query

Example YAML

queries: sales_by_date: sql: SELECT date, SUM(amount) FROM sales GROUP BY date source: my_postgres # Source reference

metrics_query: type: metricflow metrics: [revenue, orders] dimensions: [date_day]

api_data: type: http url: https://api.example.com/data

---

Errors

errors

Compilation error types.

Stage: COMPILE Purpose: Define error types for all compilation failures.

These errors are raised during: - YAML parsing (ParseError, YAMLError) - Schema validation (ValidationError) - Reference resolution (ReferenceError) - Jinja template rendering (JinjaError)

All errors inherit from CompilationError for easy catching.

Enhanced error messages include: - Line numbers where errors occur - YAML context showing the problematic snippet - Helpful suggestions ("Did you mean 'bar'?")

Refs #94

CompilationError

CompilationError(message: str, location: str | None = None, line: int | None = None, column: int | None = None, context: str | None = None, suggestion: str | None = None)

Bases: DatafaceError

Base error for all compilation failures.

This is the parent class for all compilation-related errors. Catch this to handle any compilation error.

ATTRIBUTE	DESCRIPTION
message	Human-readable error description
location	Optional location in source (line number, path, etc.) TYPE: str | None
line	Optional line number in the YAML file TYPE: int | None
column	Optional column number in the YAML file TYPE: int | None
context	Optional YAML snippet showing the error location TYPE: str | None
suggestion	Optional helpful suggestion for fixing the error TYPE: str | None

Source code in dataface/core/compile/errors.py

def __init__(
    self,
    message: str,
    location: str | None = None,
    line: int | None = None,
    column: int | None = None,
    context: str | None = None,
    suggestion: str | None = None,
):
    self.message = message
    self.location = location
    self.line = line
    self.column = column
    self.context = context
    self.suggestion = suggestion
    self.fields: dict[str, Any] = {}
    super().__init__(self._format_message())
    if self.code is None:
        from dataface.core.errors.codes_unknown import DF_UNKNOWN_INTERNAL

        self.code = DF_UNKNOWN_INTERNAL

ParseError

ParseError(message: str, line: int | None = None, context: str | None = None, suggestion: str | None = None)

Bases: CompilationError

Error during YAML parsing.

Raised when: - YAML syntax is invalid - YAML structure cannot be parsed

ATTRIBUTE	DESCRIPTION
line	Line number where the error occurred TYPE: int | None
context	YAML snippet showing the error location TYPE: str | None
suggestion	Helpful fix suggestion TYPE: str | None

Example

try: ... compile("invalid: yaml: content") ... except ParseError as e: ... print(f"Parse failed at line {e.line}: {e}")

Source code in dataface/core/compile/errors.py

def __init__(
    self,
    message: str,
    line: int | None = None,
    context: str | None = None,
    suggestion: str | None = None,
):
    # Don't double-prefix if message already has "YAML parse error"
    if not message.startswith("YAML parse error"):
        message = f"YAML parse error: {message}"
    super().__init__(
        message,
        location=f"line {line}" if line and not context else None,
        line=line,
        context=context,
        suggestion=suggestion,
    )

ValidationError

ValidationError(message: str, location: str | None = None, line: int | None = None, context: str | None = None, suggestion: str | None = None, field_path: str | None = None, invalid_value: str | None = None, valid_values: list | None = None)

Bases: CompilationError

Error during schema validation.

Raised when: - Required fields are missing - Field values are invalid type - Enum values are not recognized - Schema constraints are violated

ATTRIBUTE	DESCRIPTION
field_path	Path to the field that failed validation TYPE: str | None
invalid_value	The value that caused the error TYPE: str | None
valid_values	List of valid values (if applicable) TYPE: list | None
line	Line number where the error occurred TYPE: int | None
context	YAML snippet showing the error location TYPE: str | None
suggestion	Helpful fix suggestion TYPE: str | None

Example

try: ... compile("charts:\n my_chart:\n type: invalid_type") ... except ValidationError as e: ... print(f"Validation failed at line {e.line}: {e}")

Source code in dataface/core/compile/errors.py

def __init__(
    self,
    message: str,
    location: str | None = None,
    line: int | None = None,
    context: str | None = None,
    suggestion: str | None = None,
    field_path: str | None = None,
    invalid_value: str | None = None,
    valid_values: list | None = None,
):
    self.field_path = field_path
    self.invalid_value = invalid_value
    self.valid_values = valid_values

    # Don't double-prefix if message already has "Validation error"
    if not message.startswith("Validation error"):
        message = f"Validation error: {message}"

    super().__init__(
        message,
        location=location if not context else None,
        line=line,
        context=context,
        suggestion=suggestion,
    )

ReferenceError

ReferenceError(ref: str, context: str | None = None)

Bases: CompilationError

Error resolving a reference.

Raised when: - Chart references unknown query - Layout references unknown chart - Remote reference cannot be resolved - Partial file not found

ATTRIBUTE	DESCRIPTION
ref	The reference that could not be resolved TYPE: str | None
context	Where the reference was used TYPE: str | None

Example

try: ... compile("charts:\n my_chart:\n query: unknown_query") ... except ReferenceError as e: ... print(f"Reference '{e.ref}' not found")

Source code in dataface/core/compile/errors.py

def __init__(self, ref: str, context: str | None = None):
    self.ref = ref
    message = f"Reference '{ref}' not found"
    location = f"in {context}" if context else None
    super().__init__(message, location)

JinjaError

JinjaError(message: str, template: str | None = None)

Bases: CompilationError

Error during Jinja template resolution.

Raised when: - Jinja syntax is invalid - Variable not found in template context - Filter not found

ATTRIBUTE	DESCRIPTION
template	The template that caused the error (if available) TYPE: str | None

Example

try: ... compile("queries:\n q: SELECT * FROM {{ undefined_var }}") ... except JinjaError as e: ... print(f"Template error: {e}")

Source code in dataface/core/compile/errors.py

def __init__(self, message: str, template: str | None = None):
    self.template = template
    location = (
        f"template: {template[:50]}..."
        if template and len(template) > 50
        else template
    )
    super().__init__(f"Jinja error: {message}", location)

---

Internal Modules

These are used internally by the compiler. Most users won't need to use them directly.

Parser

parse_yaml

parse_yaml(content: str) -> Face

Parse YAML content into a Face object.

Stage: COMPILE (Step 1 of 4: Parsing)

This is the first step of compilation. It converts a raw YAML string into a structured Face object. Only basic syntax validation happens here - schema validation is the next step.

Enhanced error messages include: - Line numbers where errors occur - YAML context showing the problematic snippet - Helpful suggestions ("Did you mean?")

PARAMETER	DESCRIPTION
content	Raw YAML string to parse TYPE: str

RETURNS	DESCRIPTION
Face	Face object with parsed structure

RAISES	DESCRIPTION
ParseError	If YAML syntax is invalid or parsing fails

Example

yaml_content = ''' ... title: My Dataface ... queries: ... sales: SELECT * FROM sales ... charts: ... revenue: ... query: sales ... type: line ... rows: ... - revenue ... ''' face = parse_yaml(yaml_content) face.title 'My Dataface'

Source code in dataface/core/compile/parser.py

def parse_yaml(content: str) -> Face:
    """Parse YAML content into a Face object.

    Stage: COMPILE (Step 1 of 4: Parsing)

    This is the first step of compilation. It converts a raw YAML string
    into a structured Face object. Only basic syntax validation happens
    here - schema validation is the next step.

    Enhanced error messages include:
    - Line numbers where errors occur
    - YAML context showing the problematic snippet
    - Helpful suggestions ("Did you mean?")

    Args:
        content: Raw YAML string to parse

    Returns:
        Face object with parsed structure

    Raises:
        ParseError: If YAML syntax is invalid or parsing fails

    Example:
        >>> yaml_content = '''
        ... title: My Dataface
        ... queries:
        ...   sales: SELECT * FROM sales
        ... charts:
        ...   revenue:
        ...     query: sales
        ...     type: line
        ... rows:
        ...   - revenue
        ... '''
        >>> face = parse_yaml(yaml_content)
        >>> face.title
        'My Dataface'
    """
    # Step 1a: Parse YAML to dict
    try:
        parsed_data = yaml.safe_load(content)
    except yaml.YAMLError as e:
        # Extract line number from YAML error and provide context
        line_num = _extract_line_from_yaml_error(str(e))
        context = _get_yaml_context_for_error(content, line_num) if line_num else None
        suggestion = _get_yaml_parse_suggestion(str(e))
        raise ParseError(
            f"Invalid YAML syntax: {e}",
            line=line_num,
            context=context,
            suggestion=suggestion,
        ) from e

    # Step 1b: Handle empty content
    if parsed_data is None:
        raise ParseError("Empty YAML document")

    if not isinstance(parsed_data, dict):
        raise ParseError(f"YAML must be a mapping, got {type(parsed_data).__name__}")

    # Step 1c: Normalize queries (infer types)
    if "queries" in parsed_data and isinstance(parsed_data["queries"], dict):
        parsed_data["queries"] = _normalize_query_definitions(parsed_data["queries"])

    # Step 1d: Convert to Face with enhanced error messages
    from pydantic import ValidationError as PydanticValidationError

    try:
        return Face(**parsed_data)
    except PydanticValidationError as e:
        # Try to enhance Pydantic validation errors with context and suggestions
        try:
            from dataface.core.compile.yaml_error_formatter import (
                format_validation_error,
            )

            enhanced_msg = format_validation_error(e, content)
            raise ParseError(enhanced_msg) from e
        except ParseError:
            # Re-raise ParseError from format_validation_error
            raise
        except ImportError:
            # Fallback if yaml_error_formatter not available
            raise ParseError(f"Failed to parse face structure: {e}") from e
    except (TypeError, ValueError) as e:
        # Other parsing errors (wrong types, invalid values)
        raise ParseError(f"Failed to parse face structure: {e}") from e

Validator

validate_face

validate_face(face: Face) -> list[ValidationError]

Validate a Face structure and cross-references.

Stage: COMPILE (Step 2 of 4: Validation)

Performs semantic validation beyond what Pydantic provides: - Chart → Query references exist - Layout items reference existing charts

Note: Pydantic already validates types, required fields, and nested structures during parsing. This function adds cross-reference validation.

PARAMETER	DESCRIPTION
face	Parsed Face to validate TYPE: Face

RETURNS	DESCRIPTION
list[ValidationError]	List of ValidationError objects (empty if valid)

Example

face = parse_yaml(yaml_content) errors = validate_face(face) if errors: ... for e in errors: ... print(f"Error: {e}")

Source code in dataface/core/compile/validator.py

def validate_face(face: Face) -> list[ValidationError]:
    """Validate a Face structure and cross-references.

    Stage: COMPILE (Step 2 of 4: Validation)

    Performs semantic validation beyond what Pydantic provides:
    - Chart → Query references exist
    - Layout items reference existing charts

    Note: Pydantic already validates types, required fields, and nested
    structures during parsing. This function adds cross-reference validation.

    Args:
        face: Parsed Face to validate

    Returns:
        List of ValidationError objects (empty if valid)

    Example:
        >>> face = parse_yaml(yaml_content)
        >>> errors = validate_face(face)
        >>> if errors:
        ...     for e in errors:
        ...         print(f"Error: {e}")
    """
    errors: list[ValidationError] = []

    # Collect available names
    query_names = set((face.queries or {}).keys())
    chart_names = set((face.charts or {}).keys())

    # Validate chart → query references
    errors.extend(_validate_chart_query_references(face.charts or {}, query_names))

    # Validate layout → chart references
    errors.extend(_validate_layout_references(face, chart_names, query_names))

    return errors

Normalizer

normalize_face

normalize_face(face: Face, face_id: str | None = None, parent_context: dict[str, Any] | None = None, query_registry: dict[str, CompiledQuery] | None = None, chart_registry: dict[str, Any] | None = None, depth: int = 0, base_path: Path | None = None) -> CompiledFace

Normalize a Face into a CompiledFace with guaranteed structure.

Stage: COMPILE (Step 3 of 4: Normalization)

This is the core transformation from user-provided YAML structure to the internal compiled representation. After this step, all references are resolved, IDs are assigned, and downstream code can rely on guaranteed field presence.

Normalization performs: - Resolve all chart references (queries, extends, partials) - Generate unique IDs for all entities - Apply defaults (title from ID, empty description) - Transform input types to compiled types - Create unified Layout structure - Propagate default source to queries without explicit source

PARAMETER	DESCRIPTION
face	Input Face from parsing/validation step. TYPE: Face
face_id	Optional explicit ID for this face TYPE: str | None DEFAULT: None
parent_context	Context from parent face (for nested faces) TYPE: dict[str, Any] | None DEFAULT: None
query_registry	Complete query registry for reference resolution TYPE: dict[str, CompiledQuery] | None DEFAULT: None
chart_registry	Complete chart registry for reference resolution TYPE: dict[str, Any] | None DEFAULT: None
depth	Current nesting depth (for cycle detection) TYPE: int DEFAULT: 0
base_path	Base path for resolving external file references TYPE: Path | None DEFAULT: None

RETURNS	DESCRIPTION
CompiledFace	CompiledFace with guarantees: - All fields required by compiled types are present - All references resolved to actual objects - All IDs are unique and deterministic - Layout is unified (rows/cols/grid/tabs → Layout type)

RAISES	DESCRIPTION
ReferenceError	When a chart references an undefined query
CompilationError	When normalization fails

Example

face = parse_yaml(yaml_content) errors = validate_face(face) if not errors: ... compiled = normalize_face(face) ... print(compiled.charts['revenue'].id) # Guaranteed to exist 'revenue'

Source code in dataface/core/compile/normalizer.py

def normalize_face(
    face: Face,
    face_id: str | None = None,
    parent_context: dict[str, Any] | None = None,
    query_registry: dict[str, CompiledQuery] | None = None,
    chart_registry: dict[str, Any] | None = None,
    depth: int = 0,
    base_path: Path | None = None,
) -> CompiledFace:
    """Normalize a Face into a CompiledFace with guaranteed structure.

    Stage: COMPILE (Step 3 of 4: Normalization)

    This is the core transformation from user-provided YAML structure to the
    internal compiled representation. After this step, all references are resolved,
    IDs are assigned, and downstream code can rely on guaranteed field presence.

    Normalization performs:
    - Resolve all chart references (queries, extends, partials)
    - Generate unique IDs for all entities
    - Apply defaults (title from ID, empty description)
    - Transform input types to compiled types
    - Create unified Layout structure
    - Propagate default source to queries without explicit source

    Args:
        face: Input Face from parsing/validation step.
        face_id: Optional explicit ID for this face
        parent_context: Context from parent face (for nested faces)
        query_registry: Complete query registry for reference resolution
        chart_registry: Complete chart registry for reference resolution
        depth: Current nesting depth (for cycle detection)
        base_path: Base path for resolving external file references

    Returns:
        CompiledFace with guarantees:
            - All fields required by compiled types are present
            - All references resolved to actual objects
            - All IDs are unique and deterministic
            - Layout is unified (rows/cols/grid/tabs → Layout type)

    Raises:
        ReferenceError: When a chart references an undefined query
        CompilationError: When normalization fails

    Example:
        >>> face = parse_yaml(yaml_content)
        >>> errors = validate_face(face)
        >>> if not errors:
        ...     compiled = normalize_face(face)
        ...     print(compiled.charts['revenue'].id)  # Guaranteed to exist
        'revenue'
    """
    # Prevent infinite recursion
    MAX_DEPTH = 50
    if depth > MAX_DEPTH:
        raise CompilationError(f"Maximum nesting depth ({MAX_DEPTH}) exceeded")

    if depth > 0 and face.card_gap:
        raise CompilationError(
            "card_gap can only be set on the root face, not on nested faces"
        )

    parent_context = parent_context or {}
    if base_path is None:
        base_path = parent_context.get("base_path")

    # ════════════════════════════════════════════════════════════════════
    # STEP 1: Setup — default source, registries, face ID
    # ════════════════════════════════════════════════════════════════════
    default_source = face.get_default_source() or parent_context.get("default_source")

    # Build registries if not provided (allows direct normalize_face() calls in tests)
    if query_registry is None:
        from dataface.core.compile.compiler import build_query_registry

        query_registry = build_query_registry(
            face, base_dir=base_path, default_source=default_source
        )

    if chart_registry is None:
        from dataface.core.compile.compiler import build_chart_registry

        chart_registry = build_chart_registry(face, base_dir=base_path)

    if not face_id:
        face_id = _generate_face_id(face, depth, parent_context.get("parent_id"))

    # ════════════════════════════════════════════════════════════════════
    # STEP 2: Variables
    # ════════════════════════════════════════════════════════════════════
    # Variable names are globally unique across the face tree; the renderer
    # builds the global registry at render time. Here we collect local defs only.
    local_variables: dict[str, Variable] = {}
    if face.variables:
        for var_name, var_def in face.variables.items():
            if isinstance(var_def, Variable):
                local_variables[var_name] = var_def
            elif isinstance(var_def, dict):
                local_variables[var_name] = Variable(**var_def)
            elif ".variables." in var_def:
                # Handle cross-file variable reference (e.g., "file.variables.var_name")
                from dataface.core.compile.compiler import load_from_reference

                local_variables[var_name] = load_from_reference(
                    var_def, "variables", base_path
                )

    # Auto-detect input type when set to "auto" (the default)
    for var in local_variables.values():
        was_auto = var.input == "auto"
        var.input = _detect_variable_input_type(var)
        # Only flag select as refinable — multiselect has multi-value semantics
        # that can't map to datepicker/checkbox/slider, and strong structural
        # signals (bool → checkbox, min/max → slider) shouldn't be overridden.
        if was_auto and var.input == "select":
            var.input_auto_detected = True

    # Promote inline SQL in variable options.query to synthetic named queries
    _promote_inline_option_queries(local_variables, query_registry, default_source)

    # Compute cascading dropdown dependencies from Jinja variable references
    _compute_variable_dependencies(local_variables, query_registry)

    # Validate and collect local defaults (global defaults built by renderer)
    variable_defaults: VariableValues = {}
    for var_name, var in local_variables.items():
        if var.default is not None:
            _validate_variable_value(var_name, var, var.default)
            variable_defaults[var_name] = var.default

    # ════════════════════════════════════════════════════════════════════
    # STEP 3: Queries
    # ════════════════════════════════════════════════════════════════════
    # Extract locally defined queries from the global registry (for CompiledFace.queries).
    local_queries: dict[str, CompiledQuery] = {}
    if face.queries:
        for query_name in face.queries:
            if query_name in query_registry:
                local_queries[query_name] = query_registry[query_name]
            else:
                raise CompilationError(
                    f"Query '{query_name}' not found in registry. "
                    "This may indicate a compilation error."
                )

    # ════════════════════════════════════════════════════════════════════
    # STEP 4: Charts
    # ════════════════════════════════════════════════════════════════════
    # Normalize all charts from the global registry — layout resolution needs
    # all of them by name. Then extract locally defined ones for CompiledFace.charts.
    normalized_charts: dict[str, CompiledChart] = {}
    for chart_name, chart_def in chart_registry.items():
        normalized_charts[chart_name] = _normalize_chart(
            chart_name,
            chart_def,
            query_registry,
            base_path,
            default_source,
            source_path=f"charts.{chart_name}",
        )

    local_charts: dict[str, CompiledChart] = {}
    if face.charts:
        for chart_name in face.charts:
            if chart_name in normalized_charts:
                local_charts[chart_name] = normalized_charts[chart_name]
            else:
                raise CompilationError(
                    f"Chart '{chart_name}' not found in registry. "
                    "Charts must be defined in the face tree or imported."
                )

    charts = local_charts

    # Expand transitive variable dependencies (A→B→C means chart depends on A, B, C)
    _expand_chart_variable_dependencies(charts, local_variables)

    # ════════════════════════════════════════════════════════════════════
    # STEP 5: Style & theme
    # ════════════════════════════════════════════════════════════════════
    # Faces should inherit the same effective theme choice as their charts so
    # nested boards resolve typography/palette consistently. The face canvas
    # background itself is intentionally not copied from chart themes: board
    # chrome follows face/style defaults (white in Playground review mode),
    # while chart surfaces keep the theme-owned canvas/background colors.
    # If YAML does not specify a theme explicitly, inherit the parent theme or
    # fall back to the configured default theme.
    from dataface.core.compile.config import get_default_theme_name

    theme = face.theme or parent_context.get("theme") or get_default_theme_name()

    # Theme style is the base; face's explicit style overrides it
    merged_style = face.style or {}

    # Compile board-scoped resolved style before layout so nested faces can inherit
    resolved_style = compile_board_resolved_style(
        face.style,
        parent_context.get("resolved_style"),
        theme_name=theme,
    )

    # ════════════════════════════════════════════════════════════════════
    # STEP 6: Layout
    # ════════════════════════════════════════════════════════════════════
    # parent_variables: inherited compile-time variables (foreach loop vars) from
    # parent + local variable defaults. These are needed by foreach to generate
    # static per-iteration content at compile time. Interactive variable defaults
    # are included here so foreach items get them baked in (correct, since foreach
    # produces static faces). For regular nested boards, _resolve_dict_templates is
    # only called when _resolve_jinja=True, so interactive defaults don't get baked
    # into regular board content at compile time.
    parent_variables: dict[str, Any] = {}
    if parent_context.get("variables"):
        parent_variables.update(parent_context["variables"])
    for var_name, var in local_variables.items():
        if var.default is not None:
            parent_variables[var_name] = var.default

    _resolve_jinja = parent_context.get("_resolve_jinja", False)
    layout = build_unified_layout(
        face,
        normalized_charts,
        query_registry,
        face_id,
        depth,
        base_path,
        default_source,
        chart_registry,
        theme,
        parent_variables,
        _resolve_jinja=_resolve_jinja,
    )

    _propagate_resolved_style(layout, resolved_style)

    # Auto-generate hidden variables for tabs/details widgets
    auto_variables = _generate_layout_variables(layout)
    local_variables.update(auto_variables)
    for var_name, var in auto_variables.items():
        if var.default is not None:
            variable_defaults[var_name] = var.default

    # Collect inline charts from layout so all charts are accessible via face.charts
    # without traversing the layout tree.
    all_charts = dict(charts)
    _collect_charts_from_layout(layout, all_charts)
    charts = all_charts

    # ════════════════════════════════════════════════════════════════════
    # STEP 7: Assemble CompiledFace
    # ════════════════════════════════════════════════════════════════════

    compiled_face = CompiledFace(
        id=face_id,
        title=face.title or "",
        description=face.description or "",
        tags=face.tags or [],
        text=face.text or "",
        variables=local_variables,  # Local variables for UI controls
        queries=local_queries,
        charts=charts,
        layout=layout,
        variable_defaults=variable_defaults,  # Local variable defaults
        card_gap=face.card_gap,
        style=FaceStyle.from_dict(merged_style),
        inherited_style=face.style or {},
        theme=theme,
        resolved_style=resolved_style,
        meta={
            "compiled_at": datetime.now(timezone.utc).isoformat(),
            "version": "0.1.0",
        },
    )

    # ════════════════════════════════════════════════════════════════════
    # STEP 8: Variable registry (root face only)
    # ════════════════════════════════════════════════════════════════════
    if depth == 0:
        compiled_face.variable_registry = _build_variable_registry(compiled_face)

        # Pre-compute global defaults to avoid repeated comprehension at render time
        compiled_face.variable_defaults = {
            name: var.default
            for name, var in compiled_face.variable_registry.items()
            if var.default is not None
        }

        # Validate that all referenced variables are defined
        warnings = _validate_variable_references(compiled_face)
        if warnings:
            compiled_face.meta["variable_warnings"] = warnings

    # ════════════════════════════════════════════════════════════════════
    # STEP 9: Chart focus (root face only)
    # ════════════════════════════════════════════════════════════════════
    # Narrows the face to a single chart and its dependent variables.
    if depth == 0 and face.chart_focus:
        from dataface.core.compile.chart_focus import focus_on_chart

        compiled_face = focus_on_chart(compiled_face, face.chart_focus)

    return compiled_face

Sizing

calculate_layout

calculate_layout(face: CompiledFace) -> CompiledFace

Calculate dimensions for all layout items.

Stage: COMPILE (Step 4 of 4: Layout Calculation)

This is the final compilation step. It calculates pixel dimensions for all charts and nested faces based on layout type and nesting.

The sizing is content-aware: - KPIs get smaller heights (~100px) - Charts get standard heights (~300px) - Titles are measured for text wrapping - Nested faces accumulate their content heights

PARAMETER	DESCRIPTION
face	CompiledFace with layout structure TYPE: CompiledFace

RETURNS	DESCRIPTION
CompiledFace	CompiledFace with calculated dimensions on layout items

Example

face = normalize_face(parsed_face) face = calculate_layout(face) print(face.layout.width, face.layout.height) 1200.0 800.0

Source code in dataface/core/compile/sizing.py

def calculate_layout(face: CompiledFace) -> CompiledFace:
    """Calculate dimensions for all layout items.

    Stage: COMPILE (Step 4 of 4: Layout Calculation)

    This is the final compilation step. It calculates pixel dimensions
    for all charts and nested faces based on layout type and nesting.

    The sizing is content-aware:
    - KPIs get smaller heights (~100px)
    - Charts get standard heights (~300px)
    - Titles are measured for text wrapping
    - Nested faces accumulate their content heights

    Args:
        face: CompiledFace with layout structure

    Returns:
        CompiledFace with calculated dimensions on layout items

    Example:
        >>> face = normalize_face(parsed_face)
        >>> face = calculate_layout(face)
        >>> print(face.layout.width, face.layout.height)
        1200.0 800.0
    """
    config = get_config()

    container_width = float(config.style.board.width)
    content_width = _get_root_content_width(config)
    min_height = float(config.style.board.min_height)

    card_gap = float(config.style.board.card_gap) if face.card_gap else 0.0
    gap = get_face_gap(face)
    effective_gap = gap + card_gap

    # Use pre-computed variable defaults for Jinja resolution
    # This allows markdown content with {{ variable }} to size correctly
    variable_defaults = face.variable_defaults

    # Calculate required height based on content (content-aware)
    container_height = calculate_layout_height(
        face.layout,
        card_gap,
        gap,
        min_height,
        available_width=content_width,
        variable_defaults=variable_defaults,
    )

    # Add height for root face title if present. title renders at
    # content_width - 2*card_padding (matching the card_padding inset applied in render).
    if face.title:
        card_pad = float(config.style.board.card_padding)
        title_measure_width = max(content_width - 2 * card_pad, 0.0)
        title_height = get_title_height(
            face.title, title_measure_width, variable_defaults
        )
        container_height += title_height + effective_gap

    # Set root layout dimensions
    face.layout.width = container_width
    face.layout.height = container_height

    # Root layout items should be sized against the root content box, not the
    # full outer board width.
    face.layout.content_width = content_width
    # Vertical spacing is finalized during render after title/content/control
    # placement, so root sizing preserves the outer height contract here.
    face.layout.content_height = container_height

    # Calculate all item dimensions in a single pass
    calculate_layout_items(
        face.layout,
        content_width,
        container_height,
        card_gap,
        gap,
        variable_defaults,
    )

    return face