Skip to content
AggregaAggrega
Select language: English

Aggrega Release schema

Generated reference. Do not edit by hand — regenerate from the published JSON Schema.

Schema id: https://aggrega.ai/schemas/release-v1beta1.schema.json

See the Release authoring reference for prose guidance on authoring Release entities; this page documents the structural schema that reference describes.

Top-level type: object

Properties

PropertyTypeRequiredDescription
apiVersionconst “aggrega.ai/v1beta1”yesConstant: "aggrega.ai/v1beta1"
kindconst “Release”yesConstant: "Release"
metadataobjectyes
specobjectyesWhat the Release binds and routes: the Aggregate and Manifest it deploys (or an extends base), the environment-specific parameter fulfillment, and the boundaries its components are routed into.

Additional properties are not permitted.

release.metadata

PropertyTypeRequiredDescription
namestringyesAt least 1 character long.
environmentstringyes
versionstringyesStrict Semantic Versioning of the release (e.g., 1.0.0). Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$.
descriptionstringnoWhat this entity is and what it is for, written for someone deciding whether to use it. Open with a sentence naming the thing, then add what a reader needs in order to choose it and use it correctly — what it expects from the platform it deploys to, and anything surprising about how it behaves. A short paragraph is the usual length.
maintainersobject[]noList of maintainers who own this entity.
licensestringnoSPDX identifier for the license of the software this entity describes, such as MIT or AGPL-3.0. It records the terms of that software, not the terms of this file.
repositorystringnoThe URL to the Git repository where the source files live.
homestringnoThe URL of this entity’s home page, wiki, or documentation.
keywordsstring[]noA list of descriptive keywords for UI discoverability.

Additional properties are not permitted.

release.metadata.maintainers[]
PropertyTypeRequiredDescription
namestringyes
emailstringno
urlstringno

Additional properties are not permitted.

release.spec

What the Release binds and routes: the Aggregate and Manifest it deploys (or an extends base), the environment-specific parameter fulfillment, and the boundaries its components are routed into.

PropertyTypeRequiredDescription
aggregatestringnoReference to the Aggregate (Developer Intent) this release deploys. A bare token resolves by identity — the referenced Aggregate’s metadata.name, searched in the Release’s own directory and then the catalog. A value beginning with ’./’ or ’../’ is an explicit local file resolved relative to the Release (e.g. ’../shared/app.yaml’ to share one Aggregate across release variants in a subdirectory).
manifeststringnoReference to the Manifest resolving the abstract interfaces this release deploys against. A bare token resolves by identity — the referenced Manifest’s metadata.name, searched in the Release’s own directory. A value beginning with ’./’ or ’../’ is an explicit local file resolved relative to the Release. A Manifest is deployment-side and is not catalog-indexed, so it resolves only from the Release directory or an explicit path.
extendsstringnoReference to a base Release whose authoring surface this Release inherits — its boundary tree with the per-component infra and Feature attachments under it, its parameters, its annotations and its Manifest pointer. The value is a path to a file beside this Release, beginning ’./’ or ’../’; a bare name and a registry coordinate are both refused, because a Release is deployment-side and is not catalog-indexed. What is inherited may be replaced key by key, down to the first indivisible value — a scalar, a list, a template — which replaces whole; a key written as null removes what was inherited. No metadata field travels, so a child carries its own name, version and environment. Declaring ‘aggregate’ alongside ‘extends’ is rejected by this schema, so a child deploys the same Developer Intent as its base; ‘manifest’ stays optional and may be overridden to swap the dependency lockfile.
parametersobjectnoEnvironment-specific variable fulfillment contract with two authoring modes via content-shape dispatch. Mode 1 (inline): a YAML map carrying structured nested parameter values directly. Mode 2 (file import): a YAML map of exactly one key, $import: ./relative/path.yaml, pointing at a single local file that supplies the parameter values. Single-source-only at this site — multi-file layering is the province of Release extends: chains (the parent Release supplies base parameters; the child extends + overrides).
boundariesmap of boundarynoThe root logical boxes into which the Aggregate’s components are routed. Keys: one or more letters, digits, underscores or hyphens. A dot is not permitted. Pattern: ^[a-zA-Z0-9_-]+$.
componentsmap of boundary_componentnoTop-level component instances carrying per-component operator infra, for a single-scope Release with no named boundaries. Mutually exclusive with boundaries: declare components for a flat Release or boundaries for multi-target routing, never both. When components is used, the compiler synthesizes a default boundary holding them and emits their artifacts to dist/ flat. Keys: one or more letters, digits, underscores or hyphens. A dot is not permitted. Pattern: ^[a-zA-Z0-9_-]+$.

Additional properties are not permitted.

Definitions

boundary_component

A component instance routed into a boundary, with optional physical sizing and feature attachments.

PropertyTypeRequiredDescription
descriptionstringnoOptional documentation describing this component’s role in this boundary of the Release.
subDirectorystringnoComponent-level sub-path override appended to the parent boundary’s directory. If omitted or empty on both boundary and component, defaults to ’{{ .capability }}’; an empty string written here reads as omitted. Set to ’.’, or to a template that evaluates to an empty string, to disable sub-directory generation.
annotationsmap of string or object or nullnoComponent-specific Operator annotations that override boundary-level annotations for this component. Deep-merged over boundary annotations (component wins on key collision; structured values per-subkey-merge with structured parents). Values are strings, structured objects, or null. Used for per-component provider well-known annotation overrides (e.g., aggrega.ai/namespace on the helm provider). Explicit null on a key inherited from the parent boundary removes the inherited binding from this component (annotation-driven Feature opt-out); sibling components retain the inherited binding.
infraobjectnoPhysical sizing strictly local to this component (e.g., replicas, disk IOPS).
featuresmap of objectnoFeatures attached to this component via the Release. For features also declared in the Aggregate, only infra is provided (values come from the Aggregate). For Release-only features (Operator-injected), type is required. Keys are feature instance names and may carry the full feature type URI (dots and slashes permitted). The Release MUST NOT provide values for features — this is the Developer’s domain. Keys: one or more letters, digits, underscores, dots, slashes or hyphens. Pattern: ^[a-zA-Z0-9_./-]+$.
usesrelease_uses_blocknoOperator edge surface. Within Architect-declared sockets the Release may wire a declared-but-unbound socket to an existing component (target) and/or supply per-edge infra. No values (the Release values: ban holds) and no compute creation; retargeting a developer-declared edge halts at build.

Additional properties are not permitted.

release_uses_block

Release-authored per-edge uses surface, socket-keyed then alias-keyed (mirroring the Aggregate uses topology shape). Each connection may set target (to create an edge into a declared-but-unbound socket, pointing at an existing component), infra (per-edge operator config, validated against the socket’s infraSchema when the Release is resolved) and features (attachments filling the slots the socket declares), in any combination. values is forbidden (the Release values: ban); retargeting a developer-declared edge is a loud guardrail at build.

Keys: one or more letters, digits, underscores or hyphens. A dot is not permitted. Pattern: ^[a-zA-Z0-9_-]+$.

Values are map of object.

Any other key is not permitted.

release_connection_attachment

One attachment a Release connection entry carries: the Feature filling a slot the connection’s socket declares, with the operator’s sizing for it.

PropertyTypeRequiredDescription
typestringnoThe URI of the Feature. Required for an attachment only the Release makes. Must match the Aggregate’s type if both declare it.
descriptionstringnoOptional documentation explaining why the Operator attached this feature to the connection.
infraobjectnoOperational sizing for this attachment, validated by the Feature’s schema declaration.

Additional properties are not permitted.

aggregate_routing

Routes a nested Aggregate sub-module’s internal components into this boundary. Mirrors the boundary’s component/aggregate structure for recursive composition.

PropertyTypeRequiredDescription
componentsmap of boundary_componentnoComponent instances within the nested aggregate to route into this boundary. Keys are the local name each component carries inside that sub-module — ‘main-db’ for the component a boundary’s own components map addresses as ‘data.main-db’ — because that is the only name it has there. Keys: one or more letters, digits, underscores or hyphens. A dot is not permitted. Pattern: ^[a-zA-Z0-9_-]+$.
aggregatesmap of aggregate_routingnoFurther nested aggregates within this sub-aggregate (for deeply nested module composition). Keys: one or more letters, digits, underscores or hyphens. A dot is not permitted. Pattern: ^[a-zA-Z0-9_-]+$.

Additional properties are not permitted.

boundary

PropertyTypeRequiredDescription
descriptionstringnoOptional documentation describing this boundary’s purpose and physical target (e.g., ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’).
directorystringnoPhysical output path for GitOps artifact generation. Supports Go template variables ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Combined with subDirectory as a path join to produce the final artifact path.
subDirectorystringnoBoundary-level sub-path appended to directory. If omitted or empty on both boundary and component, defaults to ’{{ .capability }}’ for CI/CD auto-partitioning; an empty string written here reads as omitted. Set to ’.’, or to a template that evaluates to an empty string, to disable.
syncWaveintegernoOptional per-boundary deployment wave (signed integer, default 0). Every component in this boundary inherits the boundary’s wave into its node. Negative values are permitted (run before everything else); larger values run after lower ones. On K8s and Helm the wave is what orders the deployment: it becomes an argocd.argoproj.io/sync-wave annotation, and on a resource the chart already marks as a Helm hook it also becomes that hook’s helm.sh/hook-weight. On compose the wave both is recorded as a service label and orders the services of the file it renders into, through depends_on between them — so it reaches every service in that one file and nothing outside it. On cloudformation the wave orders provisioning of the stack the boundary assembles into: every resource in a wave is declared to depend on the resources of the wave before it, which fixes the order they are created in and, in reverse, the order they are deleted in. That is creation and deletion order only — a stack template expresses no notion of a resource being ready, so nothing waits for one to become serviceable. On terraform the wave orders the module blocks of the root configuration the boundary assembles into: every module in a wave is declared to depend on the modules of the wave before it, which fixes the order the engine performs its actions in. That is action order only — a configuration expresses no notion of a resource being ready, so nothing waits for one to become serviceable — and the value is also recorded with the node’s build provenance. The compiler carries the same value onto every node in the boundary as that node’s sync_wave, where the per-target behaviour is described again from the node’s side. Nested boundaries do not implicitly inherit — each declares its own wave.
annotationsmap of string or object or nullnoBoundary-wide Operator annotations cascading down to the .context.annotations.release bucket. Values are strings, structured objects, or null. A structured value carries per-subkey configuration that deep-merges with structured parents (per-subkey, child wins) and flows through annotation-driven Feature expansion; only scalar values surface in the render context. Explicit null on a key inherited from a parent boundary removes the inherited binding from this boundary’s effective annotation set (annotation-driven Feature opt-out), propagating to every component routed into this boundary unless a deeper override re-introduces the binding.
featuresmap of objectnoBoundary-wide features applied to all nested components (e.g., default security mesh). A feature’s uses block projects to every component in the boundary, declaring a shared dependency once at the boundary rather than repeating it on each component. Keys are feature instance names and may carry the full feature type URI (dots and slashes permitted). Keys: one or more letters, digits, underscores, dots, slashes or hyphens. Pattern: ^[a-zA-Z0-9_./-]+$.
boundariesmap of boundarynoNested logical boundaries (e.g., namespaces within a cluster). Keys: one or more letters, digits, underscores or hyphens. A dot is not permitted. Pattern: ^[a-zA-Z0-9_-]+$.
componentsmap of boundary_componentnoWhich components from the Aggregate are placed in this boundary. Keys are component instance names; a sub-aggregate’s component is addressed by its qualified dotted path (e.g., ‘data.main-db’ — the aggregate instance name, a dot, the component name). Keys: one or more letters, digits, underscores, dots or hyphens. Pattern: ^[a-zA-Z0-9_.-]+$.
aggregatesmap of aggregate_routingnoRoutes nested Aggregate sub-module components into this boundary. Keys are aggregate instance names matching the Aggregate’s spec.aggregates map. All aggregate instances must be placed in exactly one boundary if boundaries are defined. Keys: one or more letters, digits, underscores or hyphens. A dot is not permitted. Pattern: ^[a-zA-Z0-9_-]+$.

Additional properties are not permitted.

uses_block

The Structural Topology - Developer Owned. Declares logical network edges and dependencies.

Keys: one or more letters, digits, underscores or hyphens. A dot is not permitted. Pattern: ^[a-zA-Z0-9_-]+$.

Values are string[] or map of object.

Any other key is not permitted.

inject_block

Agnostic injection routing on a connection. Maps local variables to the target’s provides keys. Each delivery mechanism (env, file, arg, or custom) is authored as an array of {in, from} entries — explicit ‘from’ for provides references. A custom mechanism may take any name except all: a template reads every mechanism merged into one view at .context.inject.all, so a mechanism of that name would be hidden by it, and naming one halts the build.

PropertyTypeRequiredDescription
envinject_deliverynoA single delivery mechanism, authored as an array of entries. Each entry carries an ‘in’ (local identifier — env var name, file path, arg flag, or custom mechanism-specific key) plus exactly one of ‘from’ (a provides key to resolve) or ‘value’. On a Release every entry sits on a connection, so ‘from’ resolves against the target’s provides and an entry carrying ‘value’ is refused.
fileinject_deliverynoA single delivery mechanism, authored as an array of entries. Each entry carries an ‘in’ (local identifier — env var name, file path, arg flag, or custom mechanism-specific key) plus exactly one of ‘from’ (a provides key to resolve) or ‘value’. On a Release every entry sits on a connection, so ‘from’ resolves against the target’s provides and an entry carrying ‘value’ is refused.
arginject_deliverynoA single delivery mechanism, authored as an array of entries. Each entry carries an ‘in’ (local identifier — env var name, file path, arg flag, or custom mechanism-specific key) plus exactly one of ‘from’ (a provides key to resolve) or ‘value’. On a Release every entry sits on a connection, so ‘from’ resolves against the target’s provides and an entry carrying ‘value’ is refused.

inject_delivery

A single delivery mechanism, authored as an array of entries. Each entry carries an ‘in’ (local identifier — env var name, file path, arg flag, or custom mechanism-specific key) plus exactly one of ‘from’ (a provides key to resolve) or ‘value’. On a Release every entry sits on a connection, so ‘from’ resolves against the target’s provides and an entry carrying ‘value’ is refused.

Type: object[]