Validation surface
Aggrega validates authored content across four distinct schema layers. Each layer covers a different scope, runs at a different point in the compilation pipeline, and produces errors with a different shape. Authors who hit a validation error benefit from knowing which layer rejected the input — the same field can be governed by more than one layer, and the layer that fired determines what to fix and where.
This page documents the four layers, their pipeline placement, the error-shape convention each layer follows, and how layers interact when more than one applies to the same field.
The four layers
Layer 1 — JSON Schema envelope
Scope. The structural shape of every catalog YAML: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, the top-level spec: block, and the per-entity required fields the schema declares. Each entity kind (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) has its own JSON Schema, documented in the schema reference. Workload has one there as well, and it is the one kind in that set an author writes inside another entity — a Recipe’s or FeatureRecipe’s workload: block, or a WorkloadLibrary entry — rather than as a catalog file of its own; the same envelope check governs it wherever it is written, and aggrega validate accepts a Workload file directly as a single-entity target.
Validation runs. At resolution (resolver / load), per file. Each document is checked against its kind’s JSON Schema when it loads; a key outside the fields the schema declares is refused there, before any further validation runs.
Error shape. A schema mismatch is reported as a document envelope failure. Its head carries the category of the document at fault — [CATALOG_ERROR E0215] for a catalog entity, [DEVELOPER_ERROR E0215] for an Aggregate, [OPS_ERROR E0215] for a Release — and the message names the kind, the file, the line and column, the field path and the constraint violated:
[CATALOG_ERROR E0215] <path> document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schemaRequired-field omissions and type mismatches surface in the same shape — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".
Layer 2 — Pillar schemas (schema: / featuresSchema / usesSchema)
Scope. The data pillars an entity carries — values, infra, parameters, plus the features: attachment block whose slots featuresSchema declares and the uses: block governed by usesSchema. Domain 2 entities (Component, Feature) embed JSON Schema 2020-12 declarations in their YAML envelope (spec.schema inline — compact or full form — or a $ref: to a shared SchemaLibrary entry); Domain 3 entities (Recipe, FeatureRecipe) consume the resolved schemas during their own validation pass.
Validation runs. At resolution, after the JSON Schema envelope passes. The compiler composes the entity’s authored schema: with auto-generated bases derived from usesSchema and featuresSchema declarations; the composed schema validates the developer-supplied values: / infra: / features: / uses: blocks on every component instance in the Aggregate.
Error shape. Constraint violations surface as messages naming the entity, the path inside the pillar, and the rule that rejected the value — for example a developer setting a port to 80 against a schema rule requiring >=1024.
A redeclared usesSchema or featuresSchema entry produces no composition failure. Those two surfaces overlay by name: a child’s entry replaces the base’s outright, schema and selector together, so there is no conflict between a base and a child entry to report.
Layer 3 — Provider synthesized-mode capability
Scope. Governed by the bound provider’s synthesized-mode capability gate:
- Synthesized-mode (
workload:) support is gated on the bound provider’s capability, not onworkloadSchemapresence: aworkload:Recipe bound to a provider that cannot synthesize is rejected here. The standard-library catalog declaresworkloadSchemaon synthesis-capable providers by convention — on the provider-rendering Plugin’sspec.provider.workloadSchema— as the documented translation contract. ThatworkloadSchemabody is itself compiled to JSON Schema 2020-12 when the Plugin loads, a structural acceptance gate that rejects a malformed schema at load rather than at render.
Validation runs. At base rendering, after the Recipe’s own valuesMapping has resolved. Layer 3 gates synthesized-mode dispatch on provider capability.
Error shape. A capability decline is attributed to the catalog-authoring domain, so its report opens with a bracketed head carrying that category and the instance at fault. The message opens with the fixed sentence stating the condition, then names the node, the provider, and the kinds that provider does support:
[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesizedThe [CATALOG_ERROR] head signals the catalog entity is at fault, not the developer’s Aggregate. On a terminal the head also carries the condition’s short code — E0265 for this one, which the table of every condition resolves — and the message moves to its own indented line; the one-line form above is what reaches a log. The opening sentence is fixed per condition, so it is the part to match on when you are working from text; everything after it varies with the node at fault.
A related guardrail protects provider dispatch itself: when more than one provider-rendering Plugin serves the same target, the workspace resolves the ambiguity via a provider binding in .aggrega-config.yaml, chosen at aggrega pull and recorded in the lockfile. With no binding and exactly one candidate Plugin, that candidate is used; with no binding and more than one candidate, the build halts loudly, naming the candidate plugins. Ambiguity is resolved per workspace at the point of use, not by a catalog-wide uniqueness rule.
Per-provider Workload-content validation. A provider-rendering Plugin’s
spec.provider.workloadSchemadocuments how the provider translates a Workload and marks the provider as able to synthesize one; it validates nothing. Every Workload body is validated against the platform’s Workload schema, whatever the provider.
Layer 4 — Annotation-binding value validation
Scope. Annotation values authored on Release boundaries / boundary components or Aggregate subsystems / component instances, when a Manifest binding under mappings.features.annotations.<key> declares routing through maps.infra and/or maps.values dotted-path lists. Each declared path navigates the target Feature’s spec.schema.<pillar> to a leaf property; the annotation value’s contribution at that leaf is validated against the Feature schema’s declared type. Validation flows through the Feature’s own JSON Schema 2020-12 declaration — bindings declare routing only, not validation fragments.
Validation runs. The annotation-expansion sub-phase of resolution, after Manifest binding-target validation (the catalog-load check confirming each declared path exists in the referenced Feature schema) and alongside Layer 2 schema validation on explicit attachments. For each effective per-component annotation: parse the value as a scalar, a structured map, or an explicit null; route per-subkey through the binding’s pillar-grouped maps declaration with side-vs-pillar enforcement (Aggregate-side fires maps.values; Release-side fires maps.infra); validate the per-leaf runtime value against the Feature schema’s declared type at the routed pillar. Multiple subkey errors collect-and-emit-all before halting.
Error shape. Schema-validation errors at this layer follow the Layer 2 shape — entity, path (annotation key plus subkey route), constraint detail. Side-vs-pillar partition violations and ambiguous-routing failures are attributed to the document the annotation value was authored in, so a fault carried by an Aggregate opens a [DEVELOPER_ERROR] head and one carried by a Release opens an [OPS_ERROR] head, and both name the annotation key, the routed pillar, the authoring side, and the source location.
One error-formatting convention across layers
The four layers share one observable convention: every Aggrega-attributable validation failure carries a path-plus-rationale shape that names the offending field and the constraint that rejected it.
- Layer 1 (envelope) and Layer 2 (pillar schemas) errors open with the same bracketed head — the category of the document at fault and the condition’s short code, such as
[CATALOG_ERROR E0215]for an envelope mismatch in a catalog entity and[DEVELOPER_ERROR E0168]for an Aggregate value a pillar schema refuses — followed by the field path and the schema rule violated. - Layer 3 (Provider source / Workload) errors are catalog-entity-attributable by definition — the Recipe + Provider pair authored the schema that rejected the developer’s input. These are attributed to the catalog-authoring domain, and the attribution reaches you in the diagnostic’s bracketed head rather than as a word typed into the message: a halting report opens
[CATALOG_ERROR E0nnn], where the category names the domain and the short code names the condition. Match on the short code, which is fixed once issued. - Layer 4 (annotation-binding value validation) errors follow the Layer 2 shape — the validating Feature schema lives in the referenced Feature’s
spec.schema, and runtime values flow through the Manifest binding’smapsrouting into that schema for per-leaf type checking.
For the full inventory of Aggrega-prefixed sentinels and the surfaces that produce them, see errors/error-translation.md. For the per-error catalog (the [CATALOG_ERROR] Recipe shape rules, condition by condition), see errors/fatal-halts.md.
Layer interaction when fields overlap
The same authored field can be governed by more than one layer. A Workload’s containers.<name>.ports.<port> is checked by Layer 1 as part of the Workload schema’s structural shape; Layer 2 does not reach it, Workload content being a Recipe-internal structure rather than a Component pillar; and a provider’s workloadSchema checks nothing — so a constraint such as refusing a port below 1024 belongs in the Component’s schema or in an assertion, where the layer that fires names it.
Pipeline placement summary
| Layer | Scope | Runs at | Error prefix |
|---|---|---|---|
| 1 — JSON Schema envelope | Structural shape (apiVersion, kind, metadata, top-level spec) | Resolution (load) | the document’s category with E0215 — [CATALOG_ERROR E0215] for a catalog entity |
2 — Pillar schemas (schema: / featuresSchema / usesSchema) | Per-pillar data validation (values, infra, secrets, uses) | Resolution (after envelope) | the authoring document’s category with the condition’s short code — [DEVELOPER_ERROR E0168] for an Aggregate value |
| 3 — Provider-capability gate | Synthesized-mode support (provider capability) | Base rendering | [CATALOG_ERROR] |
| 4 — Annotation-binding value validation | Annotation-value contributions routed into the target Feature’s spec.schema via the Manifest binding’s maps paths | The annotation-expansion sub-phase of resolution, alongside Layer 2 | schema-validation error; side-vs-pillar / ambiguous-routing surfaces open the authoring document’s own domain — [DEVELOPER_ERROR] from an Aggregate, [OPS_ERROR] from a Release |
Cross-references
errors/error-translation.md— Aggrega-prefixed sentinel inventory and the surfaces that produce them.errors/fatal-halts.md— per-error catalog of every fatal halt the compiler emits.vocabulary/data-pillars.md— the data pillars (values,infra,parameters,locals,features:,uses:andprovides) Layer 2 validates.entities/component.md— Component authoring surface forschema:/featuresSchema/usesSchema.entities/plugin.md— provider-rendering Plugin authoring surface forspec.provider.workloadSchema.entities/manifest.md— Manifest’sfeatures.annotationsbinding surface (Layer 4).providers/well-known-annotations.md— annotation-value parsing, structured-value subkey routing, per-subkey null opt-out, and cross-side composition that Layer 4 validates.