How It Works
The compilation pipeline
ARB follows a fixed, deterministic pipeline. There are no shortcuts and no conditional paths:
schema.yaml
↓
data.yaml
↓
schema validation
↓
template expansion
↓
output files
Every step must succeed before the next one begins.
If any step fails, the entire compile stops.
This guarantees that output is either correct or does not exist at all.
Schema validation comes first
Before a single template is rendered, ARB validates the provided data against schema.yaml.
Validation checks include:
- Required fields are present
- Types match exactly (string, number, boolean, list, object)
- Lists contain the expected item structure
- No unknown or undeclared fields are present
If validation fails, rendering does not begin.
There is no partial success and no fallback behavior.
Template expansion
Once data is validated, templates are expanded using a small, explicit set of directives.
Templates are plain text files.
ARB does not execute code, call functions, or evaluate expressions.
During expansion:
- {var} replaces values from validated data
- {rep} repeats blocks for list items
- {if} conditionally includes blocks
- {inc} inserts partial templates
The same inputs always produce the same outputs.
No hidden logic
ARB intentionally keeps logic out of templates.
Templates should:
- Substitute values
- Repeat lists
- Gate optional content
Templates should NOT:
- Contain business rules
- Encode decision trees
- Compensate for missing or malformed data
If a template feels complex, the schema or data model should be redesigned.
Failure model (why ARB fails loudly)
ARB treats failure as a feature, not an inconvenience.
Common failure points:
- YAML parse errors
- Schema validation errors
- Missing template value paths
- Invalid include paths
- Recursive or excessive includes
When a failure occurs:
- No output files are produced
- The error message points to the exact location
- The compile must be fixed before continuing
Silent failure and partial output are considered bugs.
Determinism as a design constraint
Determinism is not a side effect of ARB — it is the core constraint.
ARB does not:
- Guess defaults
- Infer schema
- Mutate data
- Reorder lists
- Depend on external state
Given the same schema, data, and templates,
ARB will always produce the same output.
This makes ARB suitable for documentation generation,
code generation, configuration rendering, and other
workflows where reproducibility matters.