Shared schema and mapping libraries: a MariaDB Component
This page explains one idea, keeping the bulk of a Component’s schema and a Recipe’s mapping in libraries that several entities share, and is not a runnable workspace. MariaDB + Adminer — a runnable dual-target example composes its database’s storage settings from a schema library; write it into a folder of your own with:
aggrega scaffold --example mariadb-adminerIt then prints the commands to run next:
cd mariadb-admineraggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlThe entities on this page are a catalog of your own, in the namespace my-org; the shape of each is what a
production-grade MariaDB Component, its Recipe and the two libraries behind them take.
A schema library holds the shape
A SchemaLibrary declares named schemas, written in the compact form — one line per field, with its type, constraints and default — which the build compiles to JSON Schema 2020-12 before any value is checked against it. An excerpt:
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: Datastores version: 1.0.0spec: schemas: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" } NodePool: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: { $ref: "Datastores#/schemas/PodResources" } MariaDBPayload: architecture: { type: string, enum: [standalone, replication], default: standalone } image: tag: { type: string, validate: '{{ ne . "latest" }}', validateMessage: "image.tag must name a version: latest moves with every chart release" } primary: { $ref: "Datastores#/schemas/NodePool", required: true } secondary: when: '{{ eq $.architecture "replication" }}' required: true properties: replicaCount: { type: integer, min: 2, max: 8, default: 2 }A reference names the library by its metadata.name — Datastores#/schemas/<entry> — never by where the library is
stored, inside the library as well, so the same reference resolves whether the library sits in the workspace’s catalog
or is published to a registry. validate: and validateMessage: add a check of a field’s own; when: makes a whole
object conditional, so the secondary pool’s constraints bind only where the architecture resolves to replication. A
cross-document $ref: takes only properties, required and description beside it, which is why the secondary pool
is written out rather than referencing NodePool.
The Component references it
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-org/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-server component.aggrega.ai/category: datastorespec: schema: values: $ref: Datastores#/schemas/MariaDBPayload infra: cpu_arch: { type: string, enum: [amd64, arm64], default: amd64 } provides: host: { type: string, format: hostname } port: { type: integer, min: 1024, max: 65535 } featuresSchema: root_credentials: required: true inject: [] replication_credentials: required: false inject: [] assertions: replication-needs-credentials: | {{- if eq .values.architecture "replication" -}} {{- if not (hasKey .features "replication_credentials") -}} {{- fail "architecture=replication requires replication_credentials secret to be supplied" -}} {{- end -}} {{- end -}}The values pillar is one $ref: line; the small, Component-specific infra and provides stay inline. The
assertions hold rules of the Component’s contract that no schema keyword expresses, whichever Recipe realizes it.
A mapping library holds the translation
A MappingLibrary holds template fragments a Recipe imports. One entry renders a chart’s values, and declares a helper
with define that it invokes with template for each node pool:
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BitnamiHelpers version: 1.0.0spec: mappings: MariaDBBitnamiCore: | {{- define "BitnamiNodePool" }} resources: requests: cpu: {{ .pool.resources.requests.cpu | quote }} memory: {{ .pool.resources.requests.memory | quote }} {{- end }} {{- with .values -}} fullnameOverride: {{ $.context.rendered_name | quote }} architecture: {{ .architecture }} primary: name: primary {{- template "BitnamiNodePool" (dict "pool" .primary) }} {{- end }}The helper is declared inside the entry that uses it, because a Recipe imports one entry and a definition travels with
the entry holding it. The fragment is evaluated by Aggrega’s renderer, so it uses Sprig’s functions and Aggrega’s
optional for a key that may be absent (see sprig-functions.md);
Helm’s include is not one of them, and template writes its output exactly where it stands.
The Recipe imports it
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-bitnami version: 1.0.0spec: capability: helm implements: my-org/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "25.0.8" valuesMapping: $import: BitnamiHelpers#/mappings/MariaDBBitnamiCore provides: host: "{{ .context.rendered_name }}{{ if eq .values.architecture `replication` }}-primary{{ end }}" port: "3306"The Recipe is small: the mapping lives in the library, and the Recipe keeps what is its own — the chart it renders and
the address it publishes. Because the mapping pins the chart’s fullnameOverride to .context.rendered_name, the
Recipe can compute the primary’s Service name rather than assume it.
What the libraries buy
Written as JSON Schema, each field’s one-line map becomes a nested block and every object adds type: object,
properties: and a required: list; when: and validate: have no JSON Schema keyword of their own. The compact form
covers everything this Component needs, with no $jsonschema: escape hatch. The saving grows with sharing: the
library is written once, and each further Component’s values pillar is a single $ref: line.
The references: compact-form authoring,
cross-document $ref:, the assertions block,
SchemaLibrary and MappingLibrary.