Templates Overview
Recipe and FeatureRecipe authors write Go text/template code at specific evaluation sites: provides entries, locals entries, valuesMapping (inline or $import:-loaded), workload: content (inline or $import:-loaded), artifacts: entries (inline or per-entry $import:-loaded), FeatureRecipe injectMapping, source:, assertions: entries, and each pipeline: step’s with: and when:. Each site runs at a defined phase of the compilation pipeline and receives a defined view of the pillar context. This chapter set documents the template surface: where templates run, what the context exposes at each site, and which helper functions are available.
Template context shape and evaluation ordering are load-bearing contracts — changes to either break every existing Recipe template. The template context is formally defined in a JSON Schema shipped with the compiler; the per-site evaluation matrix describes which pillars are readable at which site, and the Go template engine ships with the Sprig helper library plus Aggrega-specific extensions. The pipeline stages that anchor these evaluation sites are described at the architectural level in ../architecture/10-compilation-pipeline.md — inject mapping for FeatureRecipe injectMapping, the locals preamble and source resolution for Recipe .locals and .source, base rendering for base Recipe valuesMapping, and feature rendering for FeatureRecipe Resource Generation.
Per-topic reference
- Template expansion matrix — the authoritative per-site table covering every template evaluation point, which pillars the site reads, and how outputs flow into the IR graph or downstream sub-passes.
- Template context contract — the formal shape of the template context the compiler hands to templates, including the dual-state
.inject/.inject_rawpair and the enriched.context.usesJOIN projection. - Naming a rendered resource — which of the two identity keys names what, the difference between a
usestarget and the reference a producer publishes, which providers report a name for the resources they render and why the others report none, and the halt that refuses the key where no such name exists. - Sprig functions and helpers — the Sprig helpers available inside Go templates plus Aggrega-specific extensions and safety helpers, how an authored number reads, prints and compares in a value template, and which helpers ask whether a value was written and which whether it is empty.
- Parameters template context — where the Release-fulfilled
parameters:values reach a template: interpolated into value templates before they run, and read directly only by path templates. - The
assertions:block — the named cross-field rules a Component, Feature, Recipe or FeatureRecipe declares as templates, evaluated before rendering.