Skip to content
AggregaAggrega
Select language: English

Aggrega Catalog (Component) schema

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

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

The abstract definition of an atomic building block.

See the Component authoring reference for prose guidance on authoring Component 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 “Component”yesConstant: "Component"
metadataobjectyes
specobjectyesValidation and schema definitions governing the developer’s opaque values payload.

Additional properties are not permitted.

component.metadata

PropertyTypeRequiredDescription
namestringyesAt least 1 character long.
versionstringyesStrict Semantic Versioning of the interface (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 Release that deploys it, 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.
labelsobjectyesDuck-typing labels to declare characteristics. Must include the reserved ‘component.aggrega.ai/type’ key.
annotationsmap of stringnoImmutable, intrinsic component characteristics authored by the Platform Architect in Domain 2. Cascades down to the .context.annotations.catalog bucket.

Additional properties are not permitted.

component.metadata.maintainers[]
PropertyTypeRequiredDescription
namestringyes
emailstringno
urlstringno

Additional properties are not permitted.

component.metadata.labels

Duck-typing labels to declare characteristics. Must include the reserved ‘component.aggrega.ai/type’ key.

PropertyTypeRequiredDescription
component.aggrega.ai/typestring (enum)yesThe reserved axis naming what kind of thing this component is. Aggrega defines this key and the values it accepts, so the set is closed; to classify components on an axis of your own, add your own label key alongside this one. Allowed values: "server", "worker", "task", "function", "stateful-server", "resource"

component.spec

Validation and schema definitions governing the developer’s opaque values payload.

PropertyTypeRequiredDescription
extendsstringnoURI of a base Component this Component extends. Extending composes structure: the base’s metadata labels and annotations, its attachment slots (featuresSchema), its self-inject allowlist (inject) and its topology sockets (usesSchema) are inherited, and this Component may add to them or replace an inherited entry key by key. The base’s data pillars are NOT composed — the base’s schema block is inherited exactly as the base authored it, so an extending Component writes schema: inherited and authors no pillar content of its own.
featuresSchemamap of objectnoDeclarative attachment slot definitions: the named binding points at which this entity expects a Feature to be attached. A slot constrains which fill may bind it (selector) and how the fill’s material may be delivered (inject); the fill’s own Feature owns its values and infra contract. Declaring a slot never closes the attachment block — an author may attach a Feature under a name no slot declares, so one entity serves both a slot-filled attachment and a credential shared at a broader scope. A slot is a binding point, not a dependency socket: usesSchema declares the separate topology surface.
injectstring[]noAllowlisted self-inject delivery mechanisms (e.g., [‘env’, ‘file’, ‘arg’]). When present, developers may use the inject: block at the component level in the Aggregate to inject their own values or provides keys directly into the delivery pipe. If omitted, component-level self-inject is forbidden (Black-Box pattern — the Recipe handles all internal wiring). Same semantics as usesSchema[].inject but governs the component’s own values rather than cross-component topology. Any mechanism name may be listed except all, which no inject block can name.
usesSchemamap of objectnoThe dependency sockets this entity declares, keyed by socket name; each connection drawn through a socket is checked against that socket’s declaration — its selector, the inject mechanisms it allows and its per-connection contracts. Keys: one or more letters, digits, underscores or hyphens. A dot is not permitted. Pattern: ^[a-zA-Z0-9_-]+$.
schemaanynoJSON Schema 2020-12 content covering the free-form pillars: values (the Developer’s domain — application-shape parameters the Developer configures per Component instance in the Aggregate); infra (the Operator’s domain — physical sizing knobs supplied by the Release); and provides (downstream context keys this Component exposes to consumers via the topology pipe). Accepts four authoring modes via content-shape dispatch: (1) inline content (a YAML map carrying compact form, JSON Schema YAML, or mixed); (2) file replacement via {$import: }, written at spec.schema to supply the whole contract from one file or at a single pillar to supply that pillar alone, with a relative path read against the directory holding the entity that declared it; (3) cross-document reference via {$ref: #/schemas/} into a SchemaLibrary entry by bare-name identity (the version is supplied by the per-Release lockfile; no registry host appears in the reference); (4) the bare string inherited, which is the only form a Component declaring extends may write — it states that the three pillars come from the base Component exactly as the base authored them. Modes 1 to 3 author content and are available only to a Component that declares no extends; mode 4 authors none and is required of every Component that does. The companion fields usesSchema and featuresSchema cover the fixed-shape pillars (dependency sockets, attachment slots); the compiler composes the three into the one schema an instance is validated against.
assertionsmap of stringnoBuild-time cross-field validation. Each entry is a named assertion: the key is a stable rule identifier surfaced in error messages; the value is a Go template string with {{ fail "message" }} halt semantics. Multiple named assertions per entity evaluate per-instance in author-declared order; the first failing assertion halts the build. Component assertions evaluate after resolution and static analysis, before render, and express architectural invariants of the contract that hold regardless of which Recipe binds. Template context: .values / .infra / .uses / .features / .metadata. The evaluator uses missingkey=error: references to undefined keys halt with a no-such-key diagnostic. Because the bare reference halts before any fallback can run, a plain default does not supply an optional-field fallback on this surface — gate the reference with hasKey, or use the optional helper, which performs the presence check directly. Reading the key through index does not supply one either: index halts on a map key the map does not hold, naming the key. Inheritance is additive: a Component declaring extends is evaluated against the assertions it inherits as well as its own, with the inherited rules first, and a chain of any depth accumulates from the chain root downward — so when more than one rule would fail, the one declared furthest up the chain is the one reported. Reusing an inherited name to declare a different rule is rejected when the extends chain is resolved against the catalog, naming both Components and the shared name — so it surfaces once the base Component is present, not from the extending document alone; an extending Component adds rules and never replaces one. Restating an inherited rule byte-for-byte under its own name is accepted as the no-op it is. Nothing checks whether two rules can both hold: a mutually unsatisfiable pair is an authoring error that surfaces as an ordinary assertion failure when an instance trips whichever fires first, never as a warning up front.

Additional properties are not permitted.

Definitions

extending-component-must-declare-schema-inherited

Applies when spec.extends is present. An extending Component receives its base’s values / infra / provides exactly as the base authored them, so it declares spec.schema: inherited and authors no pillar content. Both other outcomes are errors, and they are different mistakes: omitting spec.schema entirely, which would leave a reader unable to tell an inherited pillar block from a forgotten one; and authoring pillar content under spec.schema, which would ask for a second, divergent contract on a Component whose contract is its base’s.

PropertyTypeRequiredDescription
schemaconst “inherited”yesThe inheritance marker, and the only value spec.schema takes on a Component that declares extends. It names where the pillars come from; the pillar content itself is the base Component’s. Constant: "inherited"

non-extending-component-authors-its-own-schema

Applies when spec.extends is absent. A Component that extends no base authors its own values / infra / provides content under spec.schema, so the field carries authored content rather than the inherited marker: the marker states that pillars come from a base, and this Component has none.

PropertyTypeRequiredDescription
schemaobjectnoAuthored pillar content — a map, in any of the three content-authoring modes spec.schema documents.