Skip to content
AggregaAggrega
Select language: English

Aggrega Wasm Importer Socket schema

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

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

The wire shapes an importer plugin socket consumes (ImportInput) and emits (ImportOutput). An importer turns a foreign infrastructure description into Aggrega entities: it reads the source bytes for a named format, maps each source node to a catalog entity, and returns the entities it emitted, the mapping decisions it made, any diagnostics it raised, and any scaffold files it produced. An importer declares the formats it handles as import: capabilities in its descriptor. The importer maps meaning from the source to entities; the compiler pipes the emitted entities through opaquely.

One of the following shapes

  • ImportInput
  • ImportOutput

Definitions

ImportInput

The payload an importer guest receives: the source format that selects how to read the bytes, the primary source bytes and the name of the file they were read from, any named sources for a multi-file import, an optional opaque options document the consumer supplies for importer-specific behavior, a view of the Components the workspace’s catalog holds, and the target the import drafts for.

PropertyTypeRequiredDescription
formatstringyesThe name of the source format to import, matching one of the importer’s advertised import: capabilities. The importer reads the sources as this format.
bytesstringyesThe primary source bytes to import, which the importer reads as the named format: the whole file where the import’s source is one file, and empty where it is a directory, whose files arrive as named sources instead. Each kit carries them in its own field type — raw where that type is a byte type, base64-encoded where it is a string the importer decodes to recover them — and the generated encoder converts between the field and the form the wire carries bytes in.
namestringnoThe name of the import’s source, with no directory before it, so an importer can name the source in what it reports and in what it drafts. Where the source is one file, it is the file’s base name: the primary bytes arrive as no named source, so this is the one name they carry. Where the source is a directory, it is the directory’s base name, and the directory’s files still arrive as named sources, each under its own name, with the primary bytes empty. Absent where the source has no name to give.
sourcesImportSource[]noNamed sources, each carrying its own bytes, in one list sorted by name. Where the import’s source is a directory, there is one per file of it that the importer’s declared file patterns select, named by its slash-separated path inside the directory. The files the attachment configuring the importer declares under with.sources are carried here too, each under its base name, and the host refuses an import in which a file read from the directory and one of these carry the same name. Absent where neither supplies any.
settingsanynoAn opaque import-options document the consumer supplies for importer-specific behavior. The host pipes it through without interpreting it; the importer reads whatever shape it documents. Absent when the consumer supplies no options.
catalogCatalogProjectionnoA view of the Components the workspace’s own catalog holds — the catalog the importer itself was selected from — so the importer can weigh them as candidates when it maps a source node to a catalog entity. The host builds it from that local catalog alone, and it carries names, versions, labels and declared structure only: never a value, a default or a secret. Its order is fixed, so one catalog yields one byte sequence. Absent when the catalog holds no Component.
targetstringnoThe provider capability the import drafts for, such as compose or helm: the target the import was given, or, for an import refreshing an earlier one that names none, the target that earlier import recorded. An importer writes what only that target needs into the drafts as declarations, and leaves out what only another target needs. The host pipes it through as given, once it has checked that a Recipe of the workspace’s catalog binds to it. Absent where the import names no target.

Additional properties are not permitted.

CatalogProjection

The workspace’s catalog as an importer sees it: one entry per Component the catalog holds, each carrying the metadata an importer weighs when it scores a candidate.

PropertyTypeRequiredDescription
componentsCatalogComponent[]yesOne entry per Component name the catalog holds, sorted by name. Where the catalog holds several versions of one Component, its entry describes the version a reference naming the Component without a version resolves to.

Additional properties are not permitted.

CatalogComponent

One Component of the workspace’s catalog: its name and version, its labels, the key names its values and provides declare, and the sockets it declares for its dependencies. A Component that extends another carries what it inherits as well as what it declares itself.

PropertyTypeRequiredDescription
namestringyesThe Component’s name, as its metadata.name declares it — the name an Aggregate references it by.
versionstringyesThe Component’s version, as its metadata.version declares it.
labelsmap of stringnoThe Component’s labels, as a string-to-string map. Absent when it carries none.
valuesstring[]noThe top-level key names the Component’s values declares, sorted. A list of names only: it never carries a value or a default. Absent when its values declares no key.
providesstring[]noThe top-level key names the Component’s provides declares, sorted. A list of names only: it never carries a value. Absent when its provides declares no key.
socketsCatalogSocket[]noThe sockets the Component declares for its dependencies, in declaration order: for a Component that extends another, the sockets it inherits come first, in the order the extended Component declares them, followed by those it adds. Absent when it declares none.

Additional properties are not permitted.

CatalogSocket

One socket a catalog Component declares for its dependencies: the socket’s name and the label selector a dependency wired through it must satisfy.

PropertyTypeRequiredDescription
namestringyesThe socket’s name, as the Component’s usesSchema declares it.
selectorstringyesThe socket’s label selector, verbatim, in the Kubernetes-style grammar the Component writes it in: the labels a dependency wired through this socket must carry.

Additional properties are not permitted.

ImportSource

One named source within a multi-file or directory import: a name locating the source and its own bytes.

PropertyTypeRequiredDescription
namestringyesThe name of this source within the import, such as a relative file path.
bytesstringyesThis source’s bytes. Each kit carries them in its own field type — raw where that type is a byte type, base64-encoded where it is a string the importer decodes to recover them — and the generated encoder converts between the field and the form the wire carries bytes in.

Additional properties are not permitted.

ImportOutput

The payload an importer guest returns: the entities the import produced, the mapping decisions behind them, any diagnostics the import raised, and any scaffold files it produced. Every field is optional, so an import that resolved nothing may return diagnostics alone.

PropertyTypeRequiredDescription
entitiesEmittedEntity[]noThe entities the import produced, each either a reference to an existing catalog entity or a drafted entity body. Absent when the import emitted no entities.
decisionsImportDecision[]noThe mapping decisions the import made, one per source node it resolved, recording the candidates it weighed and the choice it made. Absent when the import recorded no decisions.
diagnosticsDiagnostic[]noDiagnostics the import raised — for example an unresolved source node or an ambiguous mapping. Absent when the import produced none.
filesScaffoldFile[]noScaffold files the import produced alongside the entities, such as a starter aggregate or a readme. Absent when the import produced no files.
errorstringnoA failure message set when the guest ran but could not complete the operation; absent on success. It is distinct from any diagnostics the output carries: diagnostics report issues found during a run that still produced a result, while error reports that the operation itself did not complete. The host surfaces a present error as a failed plugin invocation.

Additional properties are not permitted.

EmittedEntity

One entity the import produced: its kind, its name, and how it is emitted — a reference to an existing catalog entity or a newly drafted entity body.

PropertyTypeRequiredDescription
kindstringyesThe kind of entity emitted. The core importers emit Component, Aggregate and Release; a reader tolerates any other kind.
namestringyesThe name of the emitted entity.
modestring (enum)yesHow the entity is emitted: reference points at an existing catalog entity by name, and draft carries a newly drafted entity body. Allowed values: "reference", "draft"
bodystringnoThe raw YAML body of a drafted entity. Empty for a pure reference, which names an existing entity rather than drafting one.
labelsmap of stringnoLabels to attach to the emitted entity, as a string-to-string map. The core importers leave it empty.
annotationsmap of stringnoAnnotations to attach to the emitted entity, as a string-to-string map. The core importers leave it empty.
sourceRefstringnoA reference to the source node this entity was emitted from, so a reader can trace the entity back to its origin in the imported source.
decisionRefstringnoA reference to the mapping decision that produced this entity, linking it to the candidates weighed and the choice made.

Additional properties are not permitted.

ImportDecision

One mapping decision: the source node the importer resolved, the candidate catalog entities it weighed, the candidate it chose, and the reasoning behind the choice.

PropertyTypeRequiredDescription
sourceNodeDecisionSourceNodeyesThe source node this decision resolved: the node the importer read from the source and mapped to a catalog entity.
candidatesImportCandidate[]noThe candidate catalog entities the importer weighed for this source node, each with its score and the per-signal breakdown behind that score. Absent when the importer weighed no candidates.
chosenDecisionChoicenoThe candidate the importer chose for this source node, and how it emitted it. Absent when the importer made no choice.
rationalestringnoA human-readable explanation of why the importer made this choice.
swapHintstringnoA hint describing how to swap the chosen mapping for an alternative, so a reader can revise the decision.

Additional properties are not permitted.

DecisionSourceNode

The source node a mapping decision resolved: an identifier, the type the source names it, and a human-readable summary of its parameters.

PropertyTypeRequiredDescription
idstringyesThe identifier of the source node within the imported source.
typestringyesThe type of the source node as the source names it.
paramsSummarystringyesA human-readable summary of the source node’s parameters, for display alongside the decision.

Additional properties are not permitted.

ImportCandidate

One candidate catalog entity the importer weighed for a source node: the candidate component, its overall score, the match tier the score falls into, and the per-signal breakdown behind the score.

PropertyTypeRequiredDescription
componentNamestringyesThe name of the candidate catalog component.
scorenumberyesThe candidate’s overall match score, aggregated from the per-signal breakdown.
tierstringyesThe match tier the candidate falls into, a coarse band over the score.
signalsCandidateSignalsyesThe per-signal breakdown behind the candidate’s score.

Additional properties are not permitted.

CandidateSignals

The per-signal breakdown behind a candidate’s score: one contribution per matching signal. A fixed-field object, so the set of signals is stable and the wire is deterministic.

PropertyTypeRequiredDescription
tablenumberyesThe score contribution from the mapping-table signal.
categorynumberyesThe score contribution from the category signal.
domainLabelsnumberyesThe score contribution from the domain-labels signal.
shapenumberyesThe score contribution from the shape signal.
namenumberyesThe score contribution from the name signal.

Additional properties are not permitted.

DecisionChoice

The candidate a mapping decision chose: the target catalog entity, how it is emitted, and the match tier of the choice.

PropertyTypeRequiredDescription
targetstringyesThe name of the chosen target catalog entity.
modestringyesHow the chosen target is emitted, mirroring an emitted entity’s mode: a reference to an existing entity or a newly drafted body.
tierstringyesThe match tier of the chosen target.

Additional properties are not permitted.

ScaffoldFile

One scaffold file the import produced: a path relative to the import output root and the file’s content.

PropertyTypeRequiredDescription
pathstringyesThe path of the scaffold file, relative to the import output root.
contentstringyesThe scaffold file’s content.

Additional properties are not permitted.