Skip to content
AggregaAggrega
Select language: English

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_raw pair and the enriched .context.uses JOIN projection.
  • Naming a rendered resource — which of the two identity keys names what, the difference between a uses target 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.