Validation¶

HBIA provides two levels of validation: DSL validation (YAML structure) and Graph validation (structural integrity).

DSL Validation¶

Validates the raw YAML dict before building a Graph. Catches syntax and structural issues in the flow definition.

hbia validate flows/payment.yaml

from honey_badgeria.back.dsl.validator import validate_dsl

errors = validate_dsl(yaml_dict)
# Returns list of error strings
if errors:
    raise DSLValidationError(errors)

What DSL Validation Checks¶

Check	Error
Missing `flow` key	Required top-level key
Duplicate vertex names	Names must be unique within a flow
Invalid atomic group references	All vertices in a group must exist
Missing required vertex fields	`handler` is required
Invalid field types	`next` must be a list, `inputs` must be a dict

Graph Validation¶

Validates the constructed Graph object for structural integrity. This catches issues that depend on the complete graph structure.

hbia graph-validate flows/payment.yaml

from honey_badgeria.back.graph.validator import validate_graph

errors = validate_graph(graph)
# Returns list of error strings
if errors:
    raise GraphValidationError(errors)

What Graph Validation Checks¶

Check	Error
Cycles	DAGs cannot have circular dependencies. Detected via topological sort (Kahn's algorithm). Raises `GraphCycleError`.
Edge endpoint existence	Both `source` and `target` of every edge must reference existing vertices.
Atomic group connectivity	Vertices in an atomic group must form a connected subgraph — no isolated members.

Cycle Detection¶

If your graph has a cycle, HBIA rejects it at validation time:

# This is INVALID — A → B → C → A creates a cycle
flow:
  bad_flow:
    a:
      next: [b]
    b:
      next: [c]
    c:
      next: [a]    # Creates cycle!

GraphCycleError: "Cycle detected in graph"

DAGs are acyclic by definition. Cycles make topological ordering impossible and execution order ambiguous.

Validation Order¶

The recommended validation pipeline:

YAML file → DSL Validation → Graph Building → Graph Validation → Linting → Execution

DSL Validation — "Is the YAML well-formed?"
Graph Building — "Can we construct a Graph from this?"
Graph Validation — "Is the graph structurally sound?"
Linting — "Does the graph follow best practices?"

Exceptions¶

Exception	Source	Description
`DSLValidationError`	DSL Validator	YAML structure issues. Has `.errors: list[str]`
`GraphValidationError`	Graph Validator	Structural issues. Has `.errors: list[str]`
`GraphCycleError`	Topological Sort	Cycle detected in graph

from honey_badgeria.core.exceptions import (
    DSLValidationError,
    GraphValidationError,
    GraphCycleError,
)

try:
    errors = validate_dsl(yaml_dict)
    if errors:
        raise DSLValidationError(errors)

    graph = GraphBuilder.from_dict(yaml_dict)

    errors = validate_graph(graph)
    if errors:
        raise GraphValidationError(errors)

except DSLValidationError as e:
    print(f"DSL errors: {e.errors}")
except GraphValidationError as e:
    print(f"Graph errors: {e.errors}")
except GraphCycleError:
    print("Graph has cycles!")