Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Esquema del catálogo de Aggrega (Component)

Referencia generada. No la edites a mano — regenérala a partir del JSON Schema publicado.

ID del esquema: https://aggrega.ai/schemas/component-v1beta1.schema.json

La definición abstracta de un bloque de construcción atómico.

Consulta la referencia de autoría del Component para obtener orientación en prosa sobre cómo escribir entidades Component; esta página documenta el esquema estructural que describe esa referencia.

Tipo de nivel superior: object

Propiedades

PropiedadTipoObligatoriaDescripción
apiVersionconst “aggrega.ai/v1beta1”síConstante: "aggrega.ai/v1beta1"
kindconst “Component”síConstante: "Component"
metadataobjectsí
specobjectsíDefiniciones de validación y de esquema que rigen la carga útil opaca de valores del desarrollador.

No se permiten propiedades adicionales.

component.metadata

PropiedadTipoObligatoriaDescripción
namestringsíAl menos 1 carácter de longitud.
versionstringsíVersionado semántico estricto de la interfaz (p. ej., 1.0.0). Patrón: ^(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-]+)*))?$.
descriptionstringnoQué es esta entidad y para qué sirve, escrito para quien está decidiendo si usarla. Empieza con una frase que nombre la cosa y luego añade lo que un lector necesita para elegirla y usarla correctamente — qué espera de la Release que la despliega, y cualquier cosa sorprendente sobre su comportamiento. Un párrafo corto es la extensión habitual.
maintainersobject[]noLista de mantenedores responsables de esta entidad.
licensestringnoIdentificador SPDX de la licencia del software que describe esta entidad, como MIT o AGPL-3.0. Registra las condiciones de ese software, no las de este archivo.
repositorystringnoLa URL del repositorio Git donde se encuentran los archivos fuente.
homestringnoLa URL de la página de inicio, la wiki o la documentación de esta entidad.
keywordsstring[]noUna lista de palabras clave descriptivas para facilitar el descubrimiento en la interfaz de usuario.
labelsobjectsíEtiquetas de duck typing para declarar características. Deben incluir la clave reservada ‘component.aggrega.ai/type’.
annotationsmapa de stringnoCaracterísticas intrínsecas e inmutables del componente, escritas por el arquitecto de plataforma en el Dominio 2. Se propagan en cascada hasta el contenedor .context.annotations.catalog.

No se permiten propiedades adicionales.

component.metadata.maintainers[]
PropiedadTipoObligatoriaDescripción
namestringsí
emailstringno
urlstringno

No se permiten propiedades adicionales.

component.metadata.labels

Etiquetas de duck typing para declarar características. Deben incluir la clave reservada ‘component.aggrega.ai/type’.

PropiedadTipoObligatoriaDescripción
component.aggrega.ai/typestring (enum)síEl eje reservado que nombra qué tipo de cosa es este componente. Aggrega define esta clave y los valores que acepta, por lo que el conjunto es cerrado; para clasificar componentes según un eje propio, añade tu propia clave de etiqueta junto a esta. Valores permitidos: "server", "worker", "task", "function", "stateful-server", "resource"

component.spec

Definiciones de validación y de esquema que rigen la carga útil opaca de valores del desarrollador.

PropiedadTipoObligatoriaDescripción
extendsstringnoURI de un Component base que este Component extiende. La extensión compone la estructura: las etiquetas y anotaciones de metadatos de la base, sus ranuras de vinculación (featuresSchema), su lista de permitidos de autoinyección (inject) y sus sockets de topología (usesSchema) se heredan, y este Component puede ampliarlos o reemplazar una entrada heredada clave por clave. Los pilares de datos de la base NO se componen — el bloque schema de la base se hereda exactamente como la base lo escribió, por lo que un Component que extiende escribe schema: inherited y no escribe contenido de pilar propio.
featuresSchemamapa de objectnoDefiniciones declarativas de ranuras de vinculación: los puntos de enlace con nombre en los que esta entidad espera que se vincule una Feature. Una ranura restringe qué relleno puede enlazarla (selector) y cómo puede entregarse el material del relleno (inject); la Feature propia del relleno es dueña de su contrato de values e infra. Declarar una ranura nunca cierra el bloque de vinculaciones — un autor puede vincular una Feature con un nombre que ninguna ranura declara, de modo que una misma entidad sirve tanto a una vinculación que llena una ranura como a una credencial compartida en un ámbito más amplio. Una ranura es un punto de enlace, no un socket de dependencia: usesSchema declara la superficie de topología independiente.
injectstring[]noMecanismos de entrega de autoinyección admitidos por la lista de permitidos (p. ej., [‘env’, ‘file’, ‘arg’]). Cuando está presente, los desarrolladores pueden usar el bloque inject: a nivel de componente en el Aggregate para inyectar sus propios values o claves provides directamente en el pipe de entrega. Si se omite, la autoinyección a nivel de componente está prohibida (patrón Black-Box — la Recipe se encarga de todo el cableado interno). Misma semántica que usesSchema[].inject, pero rige los values propios del componente en lugar de la topología entre componentes. Puede listarse cualquier nombre de mecanismo excepto all, que ningún bloque inject puede nombrar.
usesSchemamapa de objectnoLos sockets de dependencia que declara esta entidad, indexados por nombre de socket; cada conexión trazada a través de un socket se comprueba con la declaración de ese socket — su selector, los mecanismos de inyección que permite y sus contratos por conexión. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$.
schemaanynoContenido JSON Schema 2020-12 que cubre los pilares de forma libre: values (el dominio del Desarrollador — parámetros con la forma de la aplicación que el Desarrollador configura por cada instancia de Component en el Aggregate); infra (el dominio del Operador — controles de dimensionamiento físico que suministra la Release); y provides (claves de contexto aguas abajo que este Component expone a los consumidores a través del pipe de topología). Acepta cuatro modos de autoría mediante despacho según la forma del contenido: (1) contenido inline (un mapa YAML con forma compacta, JSON Schema YAML o una combinación); (2) sustitución por archivo mediante {$import: }, escrita en spec.schema para suministrar el contrato completo desde un archivo o en un solo pilar para suministrar solo ese pilar, con una ruta relativa leída respecto al directorio que contiene la entidad que la declaró; (3) referencia entre documentos mediante {$ref: #/schemas/} a una entrada de una SchemaLibrary por identidad de nombre simple (la versión la suministra el archivo de bloqueo de cada Release; ningún host de registro aparece en la referencia); (4) la cadena simple inherited, que es la única forma que puede escribir un Component que declara extends — indica que los tres pilares provienen del Component base exactamente como la base los escribió. Los modos 1 a 3 escriben contenido y solo están disponibles para un Component que no declara extends; el modo 4 no escribe ninguno y es obligatorio para todo Component que sí lo declara. Los campos complementarios usesSchema y featuresSchema cubren los pilares de forma fija (sockets de dependencia, ranuras de vinculación); el compilador compone los tres en el único esquema con el que se valida una instancia.
assertionsmapa de stringnoValidación entre campos en tiempo de compilación. Cada entrada es una aserción con nombre: la clave es un identificador de regla estable que aparece en los mensajes de error; el valor es una cadena de plantilla Go con semántica de detención {{ fail "message" }}. Varias aserciones con nombre por entidad se evalúan por instancia en el orden declarado por el autor; la primera aserción que falla detiene la compilación. Las aserciones de Component se evalúan después de la resolución y el análisis estático, antes del renderizado, y expresan invariantes arquitectónicos del contrato que se cumplen sea cual sea la Recipe que se enlace. Contexto de la plantilla: .values / .infra / .uses / .features / .metadata. El evaluador usa missingkey=error: las referencias a claves no definidas provocan una detención con un diagnóstico no-such-key. Como la referencia simple provoca la detención antes de que pueda ejecutarse cualquier valor alternativo, un default simple no proporciona un valor alternativo para un campo opcional en esta superficie — protege la referencia con hasKey, o usa la función auxiliar optional, que realiza directamente la comprobación de presencia. Leer la clave mediante index tampoco proporciona uno: index provoca una detención ante una clave de mapa que el mapa no contiene, nombrando la clave. La herencia es aditiva: un Component que declara extends se evalúa con las aserciones que hereda además de las propias, primero las reglas heredadas, y una cadena de cualquier profundidad se acumula desde la raíz de la cadena hacia abajo — así, cuando más de una regla fallaría, se informa la declarada más arriba en la cadena. Reutilizar un nombre heredado para declarar una regla distinta se rechaza cuando la cadena de extends se resuelve contra el catálogo, nombrando ambos Components y el nombre compartido — por lo que aparece en cuanto el Component base está presente, no a partir del documento que extiende por sí solo; un Component que extiende añade reglas y nunca reemplaza ninguna. Volver a declarar una regla heredada byte a byte con su propio nombre se acepta como la operación nula que es. Nada comprueba si dos reglas pueden cumplirse a la vez: un par mutuamente insatisfacible es un error de autoría que aparece como un fallo de aserción ordinario cuando una instancia activa la que se dispara primero, nunca como una advertencia anticipada.

No se permiten propiedades adicionales.

Definiciones

extending-component-must-declare-schema-inherited

Se aplica cuando spec.extends está presente. Un Component que extiende recibe los values / infra / provides de su base exactamente como la base los escribió, por lo que declara spec.schema: inherited y no escribe contenido de pilar. Los otros dos resultados son errores, y son equivocaciones distintas: omitir por completo spec.schema, lo que dejaría a un lector sin poder distinguir un bloque de pilares heredado de uno olvidado; y escribir contenido de pilar bajo spec.schema, lo que pediría un segundo contrato, divergente, en un Component cuyo contrato es el de su base.

PropiedadTipoObligatoriaDescripción
schemaconst “inherited”síEl marcador de herencia, y el único valor que toma spec.schema en un Component que declara extends. Indica de dónde provienen los pilares; el contenido de los pilares en sí es el del Component base. Constante: "inherited"

non-extending-component-authors-its-own-schema

Se aplica cuando spec.extends está ausente. Un Component que no extiende ninguna base escribe su propio contenido values / infra / provides bajo spec.schema, por lo que el campo lleva contenido escrito por el autor en lugar del marcador inherited: el marcador indica que los pilares provienen de una base, y este Component no tiene ninguna.

PropiedadTipoObligatoriaDescripción
schemaobjectnoContenido de pilar escrito por el autor — un mapa, en cualquiera de los tres modos de autoría de contenido que documenta spec.schema.