Esquema do socket Wasm de importador do Aggrega
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/wasm-import-v1beta1.schema.json
As formas de transmissão que um socket de plugin de importador consome (ImportInput) e emite (ImportOutput). Um importador transforma uma descrição de infraestrutura externa em entidades do Aggrega: lê os bytes da fonte para um formato nomeado, mapeia cada nó da fonte para uma entidade do catálogo e devolve as entidades que emitiu, as decisões de mapeamento que tomou, os diagnósticos que levantou e os ficheiros de scaffold que produziu. Um importador declara os formatos que trata como capacidades import:
Uma das seguintes formas
ImportInputImportOutput
Definições
ImportInput
O payload que um guest importador recebe: o formato de origem que seleciona como ler os bytes, os bytes da fonte primária e o nome do ficheiro a partir do qual foram lidos, quaisquer fontes nomeadas para uma importação de vários ficheiros, um documento de opções opaco opcional que o consumidor fornece para um comportamento específico do importador, uma vista dos Components que o catálogo do espaço de trabalho contém, e o destino para o qual a importação redige rascunhos.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
format | string | sim | O nome do formato de origem a importar, correspondente a uma das capacidades import: |
bytes | string | sim | Os bytes da fonte primária a importar, que o importador lê no formato nomeado: o ficheiro inteiro quando a fonte da importação é um ficheiro, e vazio quando é um diretório, cujos ficheiros chegam em vez disso como fontes nomeadas. Cada kit contém-nos no seu próprio tipo de campo — em bruto quando esse tipo é um tipo de bytes, codificados em base64 quando é uma cadeia que o importador descodifica para os recuperar — e o codificador gerado converte entre o campo e a forma em que o formato de transmissão transporta bytes. |
name | string | não | O nome da fonte da importação, sem diretório antes dele, para que um importador possa nomear a fonte naquilo que reporta e naquilo que gera como rascunho. Quando a fonte é um único ficheiro, é o nome base do ficheiro: os bytes primários não chegam como nenhuma fonte nomeada, pelo que este é o único nome que têm. Quando a fonte é um diretório, é o nome base do diretório, e os ficheiros do diretório continuam a chegar como fontes nomeadas, cada um sob o seu próprio nome, com os bytes primários vazios. Ausente quando a fonte não tem nome a dar. |
sources | ImportSource[] | não | Fontes nomeadas, cada uma com os seus próprios bytes, numa única lista ordenada por nome. Quando a fonte da importação é um diretório, existe uma por cada ficheiro dele que os padrões de ficheiro declarados pelo importador selecionam, nomeada pelo seu caminho separado por barras dentro do diretório. Os ficheiros que o anexo que configura o importador declara sob with.sources também são transportados aqui, cada um sob o seu nome base, e o host recusa uma importação em que um ficheiro lido do diretório e um destes tenham o mesmo nome. Ausente quando nenhum dos dois fornece alguma. |
settings | any | não | Um documento opaco de opções de importação que o consumidor fornece para um comportamento específico do importador. O host transmite-o sem o interpretar; o importador lê qualquer forma que ele documente. Ausente quando o consumidor não fornece opções. |
catalog | CatalogProjection | não | Uma vista dos Components que o próprio catálogo do espaço de trabalho contém — o catálogo a partir do qual o próprio importador foi selecionado — para que o importador os possa ponderar como candidatos quando mapeia um nó da fonte para uma entidade do catálogo. O host constrói-a apenas a partir desse catálogo local, e contém só nomes, versões, etiquetas e estrutura declarada: nunca um valor, um valor predefinido ou um segredo. A sua ordem é fixa, pelo que um catálogo produz uma única sequência de bytes. Ausente quando o catálogo não contém nenhum Component. |
target | string | não | A capacidade de fornecedor para a qual a importação redige rascunhos, como compose ou helm: o destino dado à importação ou, para uma importação que atualiza uma anterior e não indica nenhum, o destino que essa importação anterior registou. Um importador escreve nos rascunhos, como declarações, aquilo de que só esse destino precisa, e omite aquilo de que só outro destino precisa. O host transmite-o tal como foi dado, depois de verificar que uma Recipe do catálogo do espaço de trabalho se vincula a ele. Ausente quando a importação não indica nenhum destino. |
Não são permitidas propriedades adicionais.
CatalogProjection
O catálogo do espaço de trabalho tal como um importador o vê: uma entrada por cada Component que o catálogo contém, cada uma com os metadados que um importador pondera quando pontua um candidato.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
components | CatalogComponent[] | sim | Uma entrada por cada nome de Component que o catálogo contém, ordenada por nome. Quando o catálogo contém várias versões de um Component, a sua entrada descreve a versão para a qual se resolve uma referência que nomeia o Component sem versão. |
Não são permitidas propriedades adicionais.
CatalogComponent
Um Component do catálogo do espaço de trabalho: o seu nome e a sua versão, as suas etiquetas, os nomes de chave que os seus values e provides declaram, e os sockets que declara para as suas dependências. Um Component que estende outro contém o que herda, além do que ele próprio declara.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O nome do Component, tal como o seu metadata.name o declara — o nome pelo qual um Aggregate o referencia. |
version | string | sim | A versão do Component, tal como o seu metadata.version a declara. |
labels | mapa de string | não | As etiquetas do Component, como um mapa de cadeia para cadeia. Ausente quando não tem nenhuma. |
values | string[] | não | Os nomes de chave de nível superior que os values do Component declaram, ordenados. Apenas uma lista de nomes: nunca contém um valor nem um valor predefinido. Ausente quando os seus values não declaram nenhuma chave. |
provides | string[] | não | Os nomes de chave de nível superior que os provides do Component declaram, ordenados. Apenas uma lista de nomes: nunca contém um valor. Ausente quando os seus provides não declaram nenhuma chave. |
sockets | CatalogSocket[] | não | Os sockets que o Component declara para as suas dependências, por ordem de declaração: para um Component que estende outro, os sockets que herda vêm primeiro, pela ordem em que o Component estendido os declara, seguidos dos que acrescenta. Ausente quando não declara nenhum. |
Não são permitidas propriedades adicionais.
CatalogSocket
Um socket que um Component do catálogo declara para as suas dependências: o nome do socket e o seletor de etiquetas que uma dependência cablada através dele tem de satisfazer.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O nome do socket, tal como o usesSchema do Component o declara. |
selector | string | sim | O seletor de etiquetas do socket, literalmente, na gramática ao estilo do Kubernetes em que o Component o escreve: as etiquetas que uma dependência cablada através deste socket tem de ter. |
Não são permitidas propriedades adicionais.
ImportSource
Uma fonte nomeada dentro de uma importação de vários ficheiros ou de um diretório: um nome que localiza a fonte e os seus próprios bytes.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O nome desta fonte dentro da importação, como um caminho de ficheiro relativo. |
bytes | string | sim | Os bytes desta fonte. Cada kit contém-nos no seu próprio tipo de campo — em bruto quando esse tipo é um tipo de bytes, codificados em base64 quando é uma cadeia que o importador descodifica para os recuperar — e o codificador gerado converte entre o campo e a forma em que o formato de transmissão transporta bytes. |
Não são permitidas propriedades adicionais.
ImportOutput
O payload que um guest importador devolve: as entidades que a importação produziu, as decisões de mapeamento por trás delas, quaisquer diagnósticos que a importação levantou e quaisquer ficheiros de scaffold que produziu. Todos os campos são opcionais, pelo que uma importação que não resolveu nada pode devolver apenas diagnósticos.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
entities | EmittedEntity[] | não | As entidades que a importação produziu, cada uma sendo uma referência a uma entidade existente do catálogo ou um corpo de entidade redigido. Ausente quando a importação não emitiu entidades. |
decisions | ImportDecision[] | não | As decisões de mapeamento que a importação tomou, uma por cada nó da fonte que resolveu, registando os candidatos que ponderou e a escolha que fez. Ausente quando a importação não registou decisões. |
diagnostics | Diagnostic[] | não | Diagnósticos que a importação levantou — por exemplo, um nó da fonte não resolvido ou um mapeamento ambíguo. Ausente quando a importação não produziu nenhum. |
files | ScaffoldFile[] | não | Ficheiros de scaffold que a importação produziu juntamente com as entidades, como um agregado inicial ou um readme. Ausente quando a importação não produziu ficheiros. |
error | string | não | Uma mensagem de falha definida quando o guest foi executado, mas não conseguiu concluir a operação; ausente em caso de sucesso. É distinta de quaisquer diagnósticos que a saída transporte: os diagnósticos reportam problemas encontrados durante uma execução que ainda assim produziu um resultado, enquanto error reporta que a própria operação não foi concluída. O host apresenta um erro presente como uma invocação de plugin falhada. |
Não são permitidas propriedades adicionais.
EmittedEntity
Uma entidade que a importação produziu: o seu tipo, o seu nome e a forma como é emitida — uma referência a uma entidade existente do catálogo ou um corpo de entidade acabado de redigir.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
kind | string | sim | O tipo de entidade emitida. Os importadores do núcleo emitem Component, Aggregate e Release; um leitor tolera qualquer outro tipo. |
name | string | sim | O nome da entidade emitida. |
mode | string (enum) | sim | Como a entidade é emitida: reference aponta para uma entidade existente do catálogo pelo nome, e draft contém um corpo de entidade acabado de redigir. Valores permitidos: "reference", "draft" |
body | string | não | O corpo YAML em bruto de uma entidade redigida. Vazio para uma referência pura, que nomeia uma entidade existente em vez de redigir uma. |
labels | mapa de string | não | Etiquetas a anexar à entidade emitida, como um mapa de cadeia para cadeia. Os importadores do núcleo deixam-no vazio. |
annotations | mapa de string | não | Anotações a anexar à entidade emitida, como um mapa de cadeia para cadeia. Os importadores do núcleo deixam-no vazio. |
sourceRef | string | não | Uma referência ao nó da fonte a partir do qual esta entidade foi emitida, para que um leitor possa seguir a entidade até à sua origem na fonte importada. |
decisionRef | string | não | Uma referência à decisão de mapeamento que produziu esta entidade, ligando-a aos candidatos ponderados e à escolha feita. |
Não são permitidas propriedades adicionais.
ImportDecision
Uma decisão de mapeamento: o nó da fonte que o importador resolveu, as entidades candidatas do catálogo que ponderou, o candidato que escolheu e o raciocínio por trás da escolha.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
sourceNode | DecisionSourceNode | sim | O nó da fonte que esta decisão resolveu: o nó que o importador leu da fonte e mapeou para uma entidade do catálogo. |
candidates | ImportCandidate[] | não | As entidades candidatas do catálogo que o importador ponderou para este nó da fonte, cada uma com a sua pontuação e a decomposição por sinal por trás dessa pontuação. Ausente quando o importador não ponderou candidatos. |
chosen | DecisionChoice | não | O candidato que o importador escolheu para este nó da fonte, e como o emitiu. Ausente quando o importador não fez nenhuma escolha. |
rationale | string | não | Uma explicação legível por pessoas da razão pela qual o importador fez esta escolha. |
swapHint | string | não | Uma sugestão que descreve como substituir o mapeamento escolhido por uma alternativa, para que um leitor possa rever a decisão. |
Não são permitidas propriedades adicionais.
DecisionSourceNode
O nó da fonte que uma decisão de mapeamento resolveu: um identificador, o tipo pelo qual a fonte o nomeia e um resumo legível por pessoas dos seus parâmetros.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
id | string | sim | O identificador do nó da fonte dentro da fonte importada. |
type | string | sim | O tipo do nó da fonte tal como a fonte o nomeia. |
paramsSummary | string | sim | Um resumo legível por pessoas dos parâmetros do nó da fonte, para apresentação ao lado da decisão. |
Não são permitidas propriedades adicionais.
ImportCandidate
Uma entidade candidata do catálogo que o importador ponderou para um nó da fonte: o componente candidato, a sua pontuação global, o nível de correspondência em que a pontuação se enquadra e a decomposição por sinal por trás da pontuação.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
componentName | string | sim | O nome do componente candidato do catálogo. |
score | number | sim | A pontuação global de correspondência do candidato, agregada a partir da decomposição por sinal. |
tier | string | sim | O nível de correspondência em que o candidato se enquadra, uma faixa aproximada sobre a pontuação. |
signals | CandidateSignals | sim | A decomposição por sinal por trás da pontuação do candidato. |
Não são permitidas propriedades adicionais.
CandidateSignals
A decomposição por sinal por trás da pontuação de um candidato: uma contribuição por cada sinal correspondente. Um objeto de campos fixos, pelo que o conjunto de sinais é estável e o formato de transmissão é determinístico.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
table | number | sim | A contribuição para a pontuação do sinal da tabela de mapeamento. |
category | number | sim | A contribuição para a pontuação do sinal de categoria. |
domainLabels | number | sim | A contribuição para a pontuação do sinal de etiquetas de domínio. |
shape | number | sim | A contribuição para a pontuação do sinal de forma. |
name | number | sim | A contribuição para a pontuação do sinal de nome. |
Não são permitidas propriedades adicionais.
DecisionChoice
O candidato que uma decisão de mapeamento escolheu: a entidade de destino do catálogo, a forma como é emitida e o nível de correspondência da escolha.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
target | string | sim | O nome da entidade de destino do catálogo escolhida. |
mode | string | sim | A forma como o destino escolhido é emitido, espelhando o modo de uma entidade emitida: uma referência a uma entidade existente ou um corpo acabado de redigir. |
tier | string | sim | O nível de correspondência do destino escolhido. |
Não são permitidas propriedades adicionais.
ScaffoldFile
Um ficheiro de scaffold que a importação produziu: um caminho relativo à raiz de saída da importação e o conteúdo do ficheiro.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
path | string | sim | O caminho do ficheiro de scaffold, relativo à raiz de saída da importação. |
content | string | sim | O conteúdo do ficheiro de scaffold. |
Não são permitidas propriedades adicionais.