Language Reference
The “what” and “how to use” of Aggrega. Syntax, CLI invocation, error catalog, worked examples.
Read the chapters below in order for first-time understanding. Reference subdirectories are listed under their chapter — jump directly when looking up a specific entity, keyword, provider, CLI command, or error.
Before reading the chapter sequence, consult Status of the Language for the current state of readiness — which language surfaces are available today, which are accepted but not yet acted on by the compiler, and which are planned for future iterations. Compatibility states what a release promises for the schemas, the command line, the assistant tools, the error codes and the plugin kits.
Entity tier model
Aggrega’s authoring entity kinds are organised into three tiers reflecting adoption progression (below). Alongside them sits the platform-owned Workload, which is not an authoring kind of its own — it is the shape a Recipe’s synthesized input takes, expressing compute shape through the form: vocabulary (stateless, stateful, daemon, scheduled, task, reference). Tiering is a documentation and onboarding mechanism, not a runtime constraint: every entity kind is a first-class language citizen; the compiler treats them uniformly; the open-source Aggrega supports all tiers without licensing or feature gating. The tier markers signal “advanced; skip if not needed” for navigation, not capability.
| Tier | Entity kinds | When to adopt |
|---|---|---|
| Tier 1 — the minimum viable surface | Aggregate, Component, Recipe, Manifest, Release | Day 1 — solo founders and small teams ship working software with only Tier 1. The mental model: “I have an app; I want to deploy it; here’s how.” |
| Tier 2 — role separation | Feature, FeatureRecipe, Plugin | Day 30 — small teams where roles split (developer + Ops + sometimes Security). Tier 2 enters via provider-rendering Plugins (Ops choose among Helm, helm-chart, Compose, Terraform and CloudFormation), Features (Security manages credentials separately from app config), and FeatureRecipes (binding-time customisation per provider). |
| Tier 3 — cross-Component reuse | SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | Day 365 — mature catalogs where common shapes recur across many entities. The threshold is informal: when a shape (e.g., PodResources) appears in 5+ Components and coordinating updates is friction, a SchemaLibrary entry justifies itself. |
Each progression is opt-in. A solo founder is never forced to look at Tier 3; an enterprise catalog has full access to Tier 3 as needed. Tier 1 is complete for the solo-founder use case — a developer can ship working applications using only Tier 1 entities. This is a strong design property: Tier 1 is not a “subset that compiles”; it is a “subset that ships software.”
The five-entity Tier 1 surface carries an entry cost — Aggregate + Component + Recipe + Manifest + Release is more ceremony than “drop a YAML file, get a running service.” The cost is the price of the four-domain authoring separation (Developer Intent / Platform Catalog / Platform Ops / Routing) that makes Aggrega different from raw Helm or raw Terraform. The Tier 1 tutorials walk through the five-entity setup explicitly.
Within Tier 3, the spec.templates / $instantiate: mechanic (parametric helpers in SchemaLibrary) is documented as an even-more-advanced sub-feature. Most Tier 3 adopters do not reach for spec.templates initially; the threshold is “when your library has 6+ schemas sharing parameterised structure.”
Reading order
- How to use this reference
- Naming Conventions
- Entity Reference Overview
- Tier 1: aggregate, component, recipe, manifest, release
- Tier 2: feature, featurerecipe, plugin
- Tier 3: schemalibrary, mappinglibrary, workloadlibrary, artifactlibrary
- Cross-cutting: workload (platform-owned compiler kind consumed inside Recipe
workload:)
- Vocabulary Overview
- Vocabulary reference: topology-triad (provides, inject, uses), data-pillars (values, infra, parameters, locals), inheritance-and-interface (extends, implements), modifier-system (appliesTo, selectors), compact-form-authoring, cross-document-ref, labels-and-annotations, publishing-surface, social-contracts, validation-surface, output-composition, uri-grammar, version-resolution
- Templates Overview
- Templates reference: expansion-matrix, template-context-contract, sprig-functions, parameters-context, assertions-block, rendered-resource-names
- Providers Overview
- Providers reference: architecture, well-known-annotations, reference-matrix, helm, helm-chart, compose, terraform, cloudformation
- CLI Overview
- CLI reference: aggrega-build, aggrega-inspect, aggrega-pull, aggrega-lint, aggrega-auth, aggrega-cache, aggrega-config, aggrega-deprecate, aggrega-edit-document, aggrega-explain, aggrega-get-schema, aggrega-import and the import answers file, aggrega-login, aggrega-logout, aggrega-mcp, aggrega-pin, aggrega-plugin, aggrega-push, aggrega-push-artifact, aggrega-registry, aggrega-scaffold, aggrega-search, aggrega-serve, aggrega-sign, aggrega-skills, aggrega-validate, aggrega-version, global-flags, configuration, environment-variables, workspace-boundary
- Errors Overview
- Errors reference: fatal-halts, warnings, sentinels, error-translation
- Examples Overview
- Examples reference: 01-getting-started, 02-data-model, 03-features-and-policies, 04-secrets, 05-credential-features, 06-composition, 07-input-kinds, 08-advanced-patterns, 09-cross-boundary-routing; runnable workspaces: Runnable Examples
Plugin authoring reference
The Wasm plugin surface sits alongside the chapter sequence rather than inside it: a plugin author reads it independently of the entity-authoring path. The plugin entity page covers the catalog authoring surface; the pages below cover the sockets, the payloads, and the author workflow.
- plugin-contract — the sockets a plugin attaches to, their pipeline placement, and each socket’s input and output shapes.
- plugin-developer-guide — the end-to-end author workflow:
describe(), capability claims, runtime limits, the publish/pull/build lifecycle, signing, versioning. - policy-socket — the governance socket in depth: its four roles, the verdict severities, the operator input channel, and writing a policy for either engine that ships inside the compiler.
- governance-attachment-facts — the per-attachment facts a governance policy reads off the build graph, including the three units of the sensitivity marking and why an absent marking is not permission.
- when-to-use-a-pipeline-step — choosing between a pipeline step and a templated FeatureRecipe.
- embedded-plugins — the plugins that ship inside the compiler binary.
- tagging-plugins — the two built-in governance plugins that write labels without a policy,
governance/label-injectorandgovernance/selector-tagger: their settings and what each writes. - core-importers — the compiler’s ten importers, from Langflow, Flowise and n8n to Compose, MCP and the agent frameworks: what each reads and drafts, their settings, and their publication with each compiler release.
- authoring-a-provider-walkthrough — a worked walkthrough of authoring a provider guest, from an empty directory to a build that writes the files the provider rendered.
- writing-a-governance-plugin — writing a governance plugin of your own from the plugin kit’s adapter skeleton: one rule, each role’s export run by hand, a
Pluginentity in the workspace’s catalog, and a build it refuses. - compatibility — how the plugin kits version: what a patch and a minor release of a kit may change, and what keeps a built plugin loading.