Esquema de la intención del desarrollador de Aggrega (Aggregate)
Referencia generada. No la edites a mano — regenérala a partir del JSON Schema publicado.
ID del esquema: https://aggrega.ai/schemas/aggregate-v1beta1.schema.json
La arquitectura AI recursiva y parametrizada. Actúa a la vez como raíz de una compilación y como módulo reutilizable.
Consulta la referencia de autoría del Aggregate para obtener orientación en prosa sobre cómo escribir entidades Aggregate; esta página documenta el esquema estructural que describe esa referencia.
Tipo de nivel superior: object
Propiedades
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | sí | Constante: "aggrega.ai/v1beta1" |
kind | const “Aggregate” | sí | Constante: "Aggregate" |
metadata | object | sí | |
defs | string[] | no | Bloque opcional para anclas YAML estándar (& y *) que mantiene el Aggregate DRY a la vez que conserva un diccionario plano O(1) para el compilador. Refleja el bloque equivalente del Manifest. |
spec | object | sí | La superficie de la intención del desarrollador: el contrato global de parámetros, las importaciones de agregados anidados, la API pública de los componentes exportados, las agrupaciones en subsistemas y las instancias de componente que forman el módulo. |
No se permiten propiedades adicionales.
aggregate.metadata
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | sí | Al menos 1 carácter de longitud. |
version | string | sí | Versionado semántico estricto del módulo agregado. 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-]+)*))?$. |
description | string | no | |
maintainers | object[] | no | Lista de mantenedores responsables de esta entidad. |
license | string | no | Identificador 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. |
repository | string | no | La URL del repositorio Git donde se encuentran los archivos fuente. |
home | string | no | La URL de la página de inicio, la wiki o la documentación de esta entidad. |
keywords | string[] | no | Una lista de palabras clave descriptivas para facilitar el descubrimiento en la interfaz de usuario. |
labels | mapa de string | no | Etiquetas de duck typing a nivel de módulo para el descubrimiento en el catálogo, la evaluación de políticas y el filtrado en Studio/IDE. Estas etiquetas describen la identidad del Aggregate como módulo reutilizable (p. ej., aggregate.aggrega.ai/tier: infrastructure, aggregate.aggrega.ai/compliance: pci-dss). NO se propagan en cascada a los nodos de componentes hijos — las etiquetas de los componentes provienen exclusivamente de la entidad de catálogo Component en el Dominio 2. |
No se permiten propiedades adicionales.
aggregate.metadata.maintainers[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | sí | |
email | string | no | |
url | string | no |
No se permiten propiedades adicionales.
aggregate.spec
La superficie de la intención del desarrollador: el contrato global de parámetros, las importaciones de agregados anidados, la API pública de los componentes exportados, las agrupaciones en subsistemas y las instancias de componente que forman el módulo.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
parameters | mapa de object | no | Contrato global del entorno. Cada entrada es un objeto de contrato tipado que usa el subconjunto del vocabulario en forma compacta (type, description, default, enum, min/max, minLength/maxLength, pattern, format, validate, validateMessage, required, items, valuesType, properties). La estructura anidada se expresa mediante el subcampo properties: de la forma tipada. La Release puede cumplirlo en línea (parameters: {…}) o mediante la importación de un único archivo fuente (parameters: {$import: |
aggregates | mapa de object | no | Agregados anidados que actúan como módulos importados. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
exportedComponents | mapa de string | no | La interfaz de la API pública. Asigna un nombre público expuesto a un ID de componente interno. Los Aggregates padre que importan este módulo hacen referencia a los componentes mediante estos nombres públicos. |
subsystems | mapa de subsystem | no | Agrupaciones lógicas con nombre de los componentes de un Aggregate en subsistemas. Mutuamente excluyentes con los componentes de nivel superior — declarar ambos se rechaza. Un subsistema que el autor llama default es un subsistema declarado ordinario, distinto del default sintetizado que el compilador crea para un Aggregate con solo componentes. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
components | mapa de component_instance | no | El mapa de los componentes lógicos atómicos que forman este Aggregate, escritos directamente en el nivel superior. Los componentes de nivel superior y los subsistemas son mutuamente excluyentes — declarar ambos se rechaza. Cuando los componentes se escriben aquí (sin subsistemas), el compilador los agrupa al cargar en un subsistema default sintetizado, y la IR marca ese subsistema como sintetizado. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
No se permiten propiedades adicionales.
Definiciones
inject_delivery
Un único mecanismo de entrega, escrito como un array de entradas. Cada entrada lleva un ‘in’ (identificador local — nombre de variable de entorno, ruta de archivo, flag de argumento o clave personalizada específica del mecanismo) más exactamente uno de ‘from’ (una clave provides que resolver) o ‘value’ (una cadena literal, que puede contener expresiones de plantilla Go evaluadas en la resolución de la autoinyección). ‘from’ se resuelve frente a los provides del destino en el contexto uses[].inject, frente a los provides que publica la FeatureRecipe de la vinculación en el contexto features.
Tipo: object[]
inject_block
Enrutamiento agnóstico de la inyección. Asigna variables locales a claves provides del destino (uses[].inject), a las claves provides que publica la FeatureRecipe de una vinculación (features.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
env | inject_delivery | no | Un único mecanismo de entrega, escrito como un array de entradas. Cada entrada lleva un ‘in’ (identificador local — nombre de variable de entorno, ruta de archivo, flag de argumento o clave personalizada específica del mecanismo) más exactamente uno de ‘from’ (una clave provides que resolver) o ‘value’ (una cadena literal, que puede contener expresiones de plantilla Go evaluadas en la resolución de la autoinyección). ‘from’ se resuelve frente a los provides del destino en el contexto uses[].inject, frente a los provides que publica la FeatureRecipe de la vinculación en el contexto features. |
file | inject_delivery | no | Un único mecanismo de entrega, escrito como un array de entradas. Cada entrada lleva un ‘in’ (identificador local — nombre de variable de entorno, ruta de archivo, flag de argumento o clave personalizada específica del mecanismo) más exactamente uno de ‘from’ (una clave provides que resolver) o ‘value’ (una cadena literal, que puede contener expresiones de plantilla Go evaluadas en la resolución de la autoinyección). ‘from’ se resuelve frente a los provides del destino en el contexto uses[].inject, frente a los provides que publica la FeatureRecipe de la vinculación en el contexto features. |
arg | inject_delivery | no | Un único mecanismo de entrega, escrito como un array de entradas. Cada entrada lleva un ‘in’ (identificador local — nombre de variable de entorno, ruta de archivo, flag de argumento o clave personalizada específica del mecanismo) más exactamente uno de ‘from’ (una clave provides que resolver) o ‘value’ (una cadena literal, que puede contener expresiones de plantilla Go evaluadas en la resolución de la autoinyección). ‘from’ se resuelve frente a los provides del destino en el contexto uses[].inject, frente a los provides que publica la FeatureRecipe de la vinculación en el contexto features. |
component_uses_block
Las conexiones que un componente traza hacia los componentes de los que depende, indexadas por socket. Cada socket enumera sus destinos, o nombra cada conexión bajo un alias. Una conexión nombrada bajo un alias puede llevar los valores por conexión del desarrollador y las vinculaciones que llenan las ranuras que declara el socket.
Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$.
Los valores son string[] or map of object.
No se permite ninguna otra clave.
feature_uses_block
Las conexiones que traza una Feature vinculada, indexadas por un socket que la Feature declara en su usesSchema. Cada socket enumera sus destinos, o nombra cada conexión bajo un alias. Una conexión que traza una Feature no lleva vinculaciones propias: una credencial que necesite llena una ranura que la Feature declara en su propio featuresSchema y se vincula junto a la Feature.
Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$.
Los valores son string[] or map of object.
No se permite ninguna otra clave.
connection_attachment
Una vinculación que lleva una conexión: la Feature que llena una ranura que declara el socket de la conexión, con la configuración del desarrollador para ella.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
type | string | sí | La URI de la interfaz de Feature que solicita esta vinculación (p. ej., core/referenced-secret:1.0.0). |
description | string | no | Documentación opcional que explica por qué esta conexión lleva la vinculación. |
values | object | no | Configuración proporcionada por el desarrollador para la Feature, validada por su declaración de esquema. |
No se permiten propiedades adicionales.
subsystem
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
description | string | no | Documentación opcional que describe el propósito de este subsistema y la agrupación lógica que representa. |
annotations | mapa de string u object o null | no | Anotaciones escritas por el desarrollador sobre este subsistema. Los valores son cadenas, objetos estructurados (un mapa de subclave a valor, combinado por subclave con un valor estructurado heredado) o null; un null explícito en una clave heredada de un subsistema padre elimina de este subsistema el enlace heredado (renuncia a una Feature guiada por anotaciones). Las anotaciones declaradas aquí las heredan los subsistemas anidados y los componentes contenidos; el nivel más cercano prevalece por clave. Se propagan en cascada hasta el contenedor .context.annotations.aggregate de cada nodo IR derivado. |
features | mapa de object | no | Funcionalidades transversales vinculadas a todos los componentes de este subsistema. El mismo esquema que las funcionalidades a nivel de componente (type, values, uses, inject). Se aplanan en cada componente al finalizar el grafo, situadas después de las funcionalidades a nivel de componente en el orden de ejecución. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
subsystems | mapa de subsystem | no | Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
components | mapa de component_instance | no | Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
No se permiten propiedades adicionales.
component_instance
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
type | string | sí | El Component abstracto solicitado, como referencia: su metadata.name más un :version opcional (p. ej., core/api-server:1.0.0), nunca una ruta de archivo. Se resuelve mediante el modelo de resolución de entidades en tres niveles (directorios de catálogo del espacio de trabajo → caché → registry): un Component escrito localmente se coloca bajo catalog/ en la raíz del espacio de trabajo o en un directorio listado en workspace.catalog_dirs, y un type escrito como ruta de archivo relativa detiene la compilación como una entidad que ningún catálogo contiene. |
active | boolean o string | no | Si este componente está presente en la topología compilada. Un boolean, o una plantilla de cadena sobre .parameters que debe resolverse en un boolean. Cuando se resuelve en false, el componente se elimina de la topología, en cascada a sus aristas uses y sus vinculaciones. Derivar el valor de un parámetro permite a una Release activar o desactivar la presencia del componente cumpliendo ese parámetro. Vale true si se omite. Valor predeterminado: true |
description | string | no | Documentación opcional que describe el papel de esta instancia de componente en la aplicación. Se transmite hasta el grafo IR. |
annotations | mapa de string u object o null | no | Anotaciones escritas por el desarrollador sobre este componente. Los valores son cadenas, objetos estructurados (un mapa de subclave a valor, combinado por subclave con un valor estructurado heredado) o null; un null explícito en una clave heredada de un subsistema padre elimina de este componente el enlace heredado (renuncia a una Feature guiada por anotaciones). Las anotaciones a nivel de Component sobrescriben por clave las anotaciones heredadas a nivel de subsistema; los componentes hermanos del mismo subsistema conservan de forma independiente sus propios mapas de anotaciones. |
values | object | no | Propiedades cognitivas opacas que se pasan al Component, validadas por su esquema. |
uses | component_uses_block | no | Las conexiones que un componente traza hacia los componentes de los que depende, indexadas por socket. Cada socket enumera sus destinos, o nombra cada conexión bajo un alias. Una conexión nombrada bajo un alias puede llevar los valores por conexión del desarrollador y las vinculaciones que llenan las ranuras que declara el socket. |
inject | inject_block | no | Autoinyección a nivel de Component. Inyecta los valores propios del componente (mediante ‘value:’) o sus propias claves provides (mediante ‘from:’) directamente en el pipe de entrega (.context.inject). Solo se permite si la entidad de catálogo Component declara ‘spec.inject’ con los mecanismos correspondientes. Una clave inject que colisiona con una clave declarada en uses[].inject detiene la compilación como clave de entrega duplicada entre fuentes de inject. |
features | mapa de object | no | Las Features vinculadas a este componente, indexadas por el nombre de instancia que el autor da a cada vinculación. Esta es la única superficie de vinculación: una Feature operativa, una Feature de credenciales (una con la etiqueta feature.aggrega.ai/kind: secret) y una Feature de identidad se vinculan todas aquí, con la misma palabra clave y la misma forma. Lo que las distingue es lo que produce la vinculación, no cómo se declara. Una vinculación cuyo nombre de instancia coincide con una ranura que el Component declara en featuresSchema llena esa ranura; cualquier otro nombre de instancia es una vinculación libre. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
No se permiten propiedades adicionales.