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
| Property | Type | Required | Description |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | yes | Constant: "aggrega.ai/v1beta1" |
kind | const “Component” | yes | Constant: "Component" |
metadata | object | yes | |
spec | object | yes | Validation and schema definitions governing the developer’s opaque values payload. |
Additional properties are not permitted.
component.metadata
| Property | Type | Required | Description |
|---|---|---|---|
name | string | yes | At least 1 character long. |
version | string | yes | Strict 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-]+)*))?$. |
description | string | no | What 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. |
maintainers | object[] | no | List of maintainers who own this entity. |
license | string | no | SPDX 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. |
repository | string | no | The URL to the Git repository where the source files live. |
home | string | no | The URL of this entity’s home page, wiki, or documentation. |
keywords | string[] | no | A list of descriptive keywords for UI discoverability. |
labels | object | yes | Duck-typing labels to declare characteristics. Must include the reserved ‘component.aggrega.ai/type’ key. |
annotations | map of string | no | Immutable, 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[]
| Property | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
email | string | no | |
url | string | no |
Additional properties are not permitted.
component.metadata.labels
Duck-typing labels to declare characteristics. Must include the reserved ‘component.aggrega.ai/type’ key.
| Property | Type | Required | Description |
|---|---|---|---|
component.aggrega.ai/type | string (enum) | yes | The 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.
| Property | Type | Required | Description |
|---|---|---|---|
extends | string | no | URI 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. |
featuresSchema | map of object | no | Declarative 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. |
inject | string[] | no | Allowlisted 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. |
usesSchema | map of object | no | The 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_-]+$. |
schema | any | no | JSON 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: |
assertions | map of string | no | Build-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.
| Property | Type | Required | Description |
|---|---|---|---|
schema | const “inherited” | yes | The 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.
| Property | Type | Required | Description |
|---|---|---|---|
schema | object | no | Authored pillar content — a map, in any of the three content-authoring modes spec.schema documents. |