Skip to content
AggregaAggrega
Select language: English

Aggrega Catalog (MappingLibrary) schema

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

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

A reusable collection of Go template fragments that Recipes and FeatureRecipes consume at render time via valuesMapping: { $import: ... }. Tier 3 — opt-in for catalogs that need cross-Recipe mapping reuse. Single authoring mode: Go templates only.

See the MappingLibrary authoring reference for prose guidance on authoring MappingLibrary 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 “MappingLibrary”yesConstant: "MappingLibrary"
metadataobjectyes
specobjectyesThe MappingLibrary’s content. spec.mappings is required and must declare at least one entry. spec carries additionalProperties: false — no parallel authoring modes are accepted at the envelope level. The single-authoring-mode posture keeps Recipe rendering uniform (Go template throughout) and avoids forcing authors to switch evaluation models mid-render when consuming imported fragments.

Additional properties are not permitted.

mappinglibrary.metadata

PropertyTypeRequiredDescription
namestringyesPascalCase identifier for the library. It is the name in the bare-name identity reference #/mappings/; the version is supplied by the per-Release lockfile and no registry host enters the reference or any derived identifier. Pattern: ^[A-Z][A-Za-z0-9]*$.
versionstringyesStrict Semantic Versioning of the library (e.g., 1.0.0). A consumer may assert this as an optional :<version> minimum-version floor in a bare-name reference (:#/mappings/); the per-Release lockfile owns the resolved version. 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-]+)*))?$.
descriptionstringnoA concise summary of what the library covers.
labelsmap of stringnoAuthor-declared labels. The compiler is content-neutral and does not interpret label values: they are opaque metadata, carried for whatever reads the library to match on.
annotationsmap of stringnoAuthor-declared annotations. Same opaque-metadata posture as labels.

Additional properties are not permitted.

mappinglibrary.spec

The MappingLibrary’s content. spec.mappings is required and must declare at least one entry. spec carries additionalProperties: false — no parallel authoring modes are accepted at the envelope level. The single-authoring-mode posture keeps Recipe rendering uniform (Go template throughout) and avoids forcing authors to switch evaluation models mid-render when consuming imported fragments.

PropertyTypeRequiredDescription
mappingsmap of stringyesNamed map of reusable Go template fragments. Each entry’s body is opaque to the envelope validation — content semantics are handled by the Go template parser at consumption time. Keys: PascalCase identifier. Entry keys appear in canonical reference URLs (#/mappings/<name>); the envelope-level constraint prevents non-PascalCase keys from propagating through the catalog ecosystem. Pattern: ^[A-Z][A-Za-z0-9]*$. At least 1 entry.

Additional properties are not permitted.