Esquema do socket Wasm de importador do Aggrega
Referência gerada. Não edite à mão — gere 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: ele lê os bytes da fonte para um formato nomeado, mapeia cada nó da fonte para uma entidade do catálogo e retorna as entidades que emitiu, as decisões de mapeamento que tomou, os diagnósticos que levantou e os arquivos 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 arquivo do qual foram lidos, quaisquer fontes nomeadas para uma importação de vários arquivos, um documento de opções opaco opcional que o consumidor fornece para um comportamento específico do importador, uma visão 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 arquivo inteiro onde a fonte da importação é um arquivo, e vazio onde ela é um diretório, cujos arquivos chegam em vez disso como fontes nomeadas. Cada kit os traz no seu próprio tipo de campo — brutos onde esse tipo é um tipo de bytes, codificados em base64 onde é uma string que o importador decodifica para recuperá-los — e o codificador gerado converte entre o campo e a forma em que o formato de transmissão traz os 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 informa e naquilo que gera como rascunho. Onde a fonte é um único arquivo, é o nome base do arquivo: os bytes primários não chegam como nenhuma fonte nomeada, então este é o único nome que eles trazem. Onde a fonte é um diretório, é o nome base do diretório, e os arquivos do diretório continuam chegando como fontes nomeadas, cada um sob o seu próprio nome, com os bytes primários vazios. Ausente onde a fonte não tem nome a dar. |
sources | ImportSource[] | não | Fontes nomeadas, cada uma trazendo os seus próprios bytes, em uma única lista ordenada por nome. Onde a fonte da importação é um diretório, há uma para cada arquivo dele que os padrões de arquivo declarados pelo importador selecionam, nomeada pelo seu caminho separado por barras dentro do diretório. Os arquivos que a vinculação que configura o importador declara sob with.sources também são trazidos aqui, cada um sob o seu nome base, e o host recusa uma importação em que um arquivo lido do diretório e um destes trazem o mesmo nome. Ausente onde nenhum dos dois fornece algum. |
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 o repassa sem interpretá-lo; o importador lê qualquer forma que ele documente. Ausente quando o consumidor não fornece opções. |
catalog | CatalogProjection | não | Uma visão dos Components que o próprio catálogo do espaço de trabalho contém — o catálogo do qual o próprio importador foi selecionado — para que o importador possa ponderá-los como candidatos quando mapeia um nó da fonte para uma entidade do catálogo. O host a constrói apenas a partir desse catálogo local, e ela traz somente nomes, versões, rótulos e estrutura declarada: nunca um valor, um valor padrão ou um segredo. A sua ordem é fixa, de modo 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 provedor 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 nomeia nenhum, o destino que essa importação anterior registrou. Um importador escreve nos rascunhos, como declarações, o que só esse destino precisa, e omite o que só outro destino precisa. O host o repassa 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 nomeia nenhum destino. |
Não são permitidas propriedades adicionais.
CatalogProjection
O catálogo do espaço de trabalho como um importador o vê: uma entrada por Component que o catálogo contém, cada uma trazendo os metadados que um importador pondera quando pontua um candidato.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
components | CatalogComponent[] | sim | Uma entrada por nome de Component que o catálogo contém, ordenada por nome. Onde 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, os seus rótulos, os nomes de chave que os seus values e provides declaram, e os sockets que ele declara para as suas dependências. Um Component que estende outro traz o que herda além do que ele próprio declara.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O nome do Component, como o seu metadata.name o declara — o nome pelo qual um Aggregate o referencia. |
version | string | sim | A versão do Component, como o seu metadata.version a declara. |
labels | mapa de string | não | Os rótulos do Component, como um mapa de string para string. Ausente quando ele não traz nenhum. |
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 traz um valor ou um valor padrão. 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 traz 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, em ordem de declaração: para um Component que estende outro, os sockets que ele herda vêm primeiro, na ordem em que o Component estendido os declara, seguidos pelos que ele adiciona. Ausente quando ele 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 rótulos que uma dependência cabeada por meio dele deve satisfazer.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O nome do socket, como o usesSchema do Component o declara. |
selector | string | sim | O seletor de rótulos do socket, literalmente, na gramática no estilo do Kubernetes em que o Component o escreve: os rótulos que uma dependência cabeada por meio deste socket deve trazer. |
Não são permitidas propriedades adicionais.
ImportSource
Uma fonte nomeada dentro de uma importação de vários arquivos ou de 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 arquivo relativo. |
bytes | string | sim | Os bytes desta fonte. Cada kit os traz no seu próprio tipo de campo — brutos onde esse tipo é um tipo de bytes, codificados em base64 onde é uma string que o importador decodifica para recuperá-los — e o codificador gerado converte entre o campo e a forma em que o formato de transmissão traz os bytes. |
Não são permitidas propriedades adicionais.
ImportOutput
O payload que um guest importador retorna: 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 arquivos de scaffold que produziu. Todo campo é opcional, de modo que uma importação que não resolveu nada pode retornar 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 nó da fonte que ela resolveu, registrando os candidatos que ponderou e a escolha que fez. Ausente quando a importação não registrou 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 | Arquivos de scaffold que a importação produziu junto com as entidades, como um agregado inicial ou um readme. Ausente quando a importação não produziu arquivos. |
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. Ela é distinta de quaisquer diagnósticos que a saída carregue: os diagnósticos informam problemas encontrados durante uma execução que ainda assim produziu um resultado, enquanto error informa que a própria operação não foi concluída. O host apresenta um erro presente como uma invocação de plugin com falha. |
Não são permitidas propriedades adicionais.
EmittedEntity
Uma entidade que a importação produziu: o seu tipo, o seu nome e como ela é emitida — uma referência a uma entidade existente do catálogo ou um corpo de entidade recém-redigido.
| 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 traz um corpo de entidade recém-redigido. Valores permitidos: "reference", "draft" |
body | string | não | O corpo YAML 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 | Rótulos a anexar à entidade emitida, como um mapa de string para string. Os importadores do núcleo o deixam vazio. |
annotations | mapa de string | não | Anotações a anexar à entidade emitida, como um mapa de string para string. Os importadores do núcleo o deixam 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 rastrear a entidade até a 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 ele 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 o detalhamento 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 ele o emitiu. Ausente quando o importador não fez nenhuma escolha. |
rationale | string | não | Uma explicação legível por pessoas de por que o importador fez esta escolha. |
swapHint | string | não | Uma dica que descreve como trocar o mapeamento escolhido por uma alternativa, para que um leitor possa revisar 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 como a fonte o nomeia. |
paramsSummary | string | sim | Um resumo legível por pessoas dos parâmetros do nó da fonte, para exibiçã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 geral, o nível de correspondência em que a pontuação se enquadra e o detalhamento 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 geral de correspondência do candidato, agregada a partir do detalhamento 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 | O detalhamento por sinal por trás da pontuação do candidato. |
Não são permitidas propriedades adicionais.
CandidateSignals
O detalhamento por sinal por trás da pontuação de um candidato: uma contribuição por sinal correspondente. Um objeto de campos fixos, de modo 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 rótulos 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, como ela é 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 | Como o destino escolhido é emitido, espelhando o modo de uma entidade emitida: uma referência a uma entidade existente ou um corpo recém-redigido. |
tier | string | sim | O nível de correspondência do destino escolhido. |
Não são permitidas propriedades adicionais.
ScaffoldFile
Um arquivo de scaffold que a importação produziu: um caminho relativo à raiz de saída da importação e o conteúdo do arquivo.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
path | string | sim | O caminho do arquivo de scaffold, relativo à raiz de saída da importação. |
content | string | sim | O conteúdo do arquivo de scaffold. |
Não são permitidas propriedades adicionais.