Contexto de plantilla de los parámetros
El pilar parameters: lleva los valores de parámetros aportados por la Release y validados con respecto al contrato. Dos modelos mentales paralelos rigen su accesibilidad:
- Las superficies de plantillas de valor (cadenas
values:de componente / feature / subaggregate dentro del Aggregate, además devaluesMappingde la Recipe,injectMappingyprovidesde la FeatureRecipe, cuerpos de Workload) consumen los valores de los parámetros como literales ya interpolados. La pasada de interpolación dentro de la resolución evalúa todo el texto del Aggregate como plantilla y sustituye cada referencia{{ .parameters.<slot> }}por el valor resuelto; las superficies de plantillas de valor posteriores nunca ven.parametersdirectamente en su contexto de plantilla. - Las superficies de plantillas de ruta (plantillas
directory:ysubDirectory:escritas por el operador en los límites de la Release) leen.parameters.<slot>directamente en la evaluación de las plantillas de ruta durante el renderizado. El mapa de parámetros fusionado sigue siendo legible hasta el final del renderizado para que una plantilla de ruta pueda leer.parameterscon respecto a la allowlist cerrada.
La concesión asimétrica — las plantillas de ruta leen .parameters directamente; las plantillas de valor no — hace que cada capa posea lo que necesita: los values: del lado del desarrollador llevan datos ya resueltos y específicos del entorno hacia las plantillas de valor; las plantillas de ruta del lado del operador hacen referencia a parámetros de región / entorno / id de cuenta sin dar la vuelta por el esquema values del Aggregate.
Esta página documenta la pasada de interpolación, las formas de valor por slot, los patrones de acceso dentro de las cadenas YAML del Aggregate, la excepción de las plantillas de ruta y cuánto tiempo sigue siendo legible el mapa fusionado. Para la forma más amplia del contexto de plantilla de Recipe / FeatureRecipe (.values, .infra, .uses, etc.), consulta template-context-contract.md. Para la disponibilidad por punto de plantilla a lo largo de la pipeline de compilación, consulta expansion-matrix.md. Para la forma de declaración de los contratos de parámetros tipados en el Aggregate, consulta entities/aggregate.md §«Typed parameter contracts (Contratos de parámetros tipados)». Para la allowlist de variables de plantillas de ruta que incluye .parameters.<slot> en la evaluación de directory: / subDirectory: de un límite, consulta path-template-variables.md.
Ciclo de vida de los parámetros
El compilador resuelve los parámetros en cuatro fases ordenadas:
- Lectura del contrato — el bloque
spec.parameters:del Aggregate se comprueba en sus propios términos antes de examinar cualquier valor de la Release, de modo que un slot que no podría restringir nada detiene la compilación incluso cuando ninguna Release lo aporta. UnminLengthomaxLengthnegativo en la propia declaración de un parámetro se rechaza cuando se carga el Aggregate, nombrando el parámetro y la clave. Cadapattern— en el propio slot y dentro de cualquier contrato anidado bajoitems,propertiesovaluesType— se compila como expresión regular, y uno que no compila se rechaza nombrando el parámetro, el patrón y el motivo. Una cota de longitud dentro de un contrato anidado no está sujeta a ese mínimo; consultaentities/aggregate.md. - Relleno de valores predeterminados — los slots con
default:definido y sin valor aportado por la Release reciben su valor predeterminado. El mapa.parametersestá en el ámbito en este punto. - Validación del contrato de parámetros — cada valor del mapa fusionado, tanto si lo aportó la Release como si lo rellenó un
default:, se valida con respecto a las restriccionestype/enum/min/max/pattern/ de estructura anidada declaradas enspec.parameters.<slot>del Aggregate; unpatternse compara con la expresión compilada cuando se leyó el contrato. El mapa.parametersexiste en el contexto en memoria del validador como la carga útil estructurada que se comprueba. - Interpolación — el compilador evalúa todo el texto del Aggregate como plantilla, antes de leerlo como YAML, y sustituye cada referencia
{{ .parameters.<slot> }}por el valor resuelto; cualquier otro{{del texto se lee también como sintaxis de plantilla, de modo que un valor que lleva sus propias llaves dobles escribe cada{{como{{"{{"}}(consulta Texto que contiene sus propias llaves dobles). La interpolación es la ruta de sustitución para las superficies de plantillas de valor — después de esta pasada, los contextos de plantillas de valor ya no llevan.parameters; consumen los valores resueltos escritos en las cadenasvalues:circundantes. El mapa fusionado sigue siendo legible después de la interpolación, durante todo el renderizado, específicamente para dar soporte a la evaluación de las plantillas de ruta. Su vida legible está acotada por la de la compilación: el compilador entrega la vista resuelta a la compilación que la consume en lugar de devolverla a un llamador, de modo que nada fuera de esa compilación puede alcanzar el mapa. La superficie de plantillas de ruta (directory:/subDirectory:de la Release) lee.parameters.<slot>durante el renderizado con respecto a la allowlist cerrada documentada enpath-template-variables.md.
Las plantillas dentro de las cadenas YAML del Aggregate (values: de componente, values: de feature, expresiones de paso parameters: de subaggregate) leen el mapa .parameters mediante la sintaxis estándar de plantillas Go durante la pasada de interpolación. Las plantillas dentro de los archivos de Recipe y FeatureRecipe NO reciben .parameters en su contexto de plantilla (consulta «Boundary with downstream template contexts (Límite con los contextos de plantilla posteriores)» más abajo para el contrato por superficie).
Texto que contiene sus propias llaves dobles
Como todo el texto es una plantilla, las llaves dobles que pertenecen a un valor y no a una plantilla también se leen como acciones de plantilla. La definición de una plataforma de flujos llevada en los values: de un componente es el caso habitual: n8n envuelve en llaves dobles cada expresión de los parámetros de un nodo, como en ={{ $json.body.message }}, un prompt de Flowise nombra una variable como {{question}} y un chatflow de Flowise escribe {{chatOpenAI_0.data.instance}} para cada conexión entre dos nodos, y una exportación de Langflow lleva el código fuente de sus componentes, donde las llaves también pueden aparecer. Escritas tal cual en un Aggregate, detienen la compilación en el Aggregate con E0158, descrito en «A {{ .parameters.* }} reference cannot be interpolated (No se puede interpolar una referencia a parámetros)» en Detenciones fatales; su motivo nombra la línea y el primer token que el motor de plantillas no pudo leer — undefined variable "$json" para una expresión de n8n. Un comentario YAML también es texto de plantilla, de modo que un {{ escrito en un comentario se detiene de la misma manera.
Escribe cada {{ de un valor así como {{"{{"}}. Es una acción de plantilla cuyo resultado es la cadena {{, de modo que la interpolación vuelve a poner las dos llaves. Un }} de cierre no necesita nada, porque fuera de una acción es texto simple. La interpolación se ejecuta una vez, sobre el texto del Aggregate, y una plantilla de Recipe escribe lo que lee de .values como datos, de modo que las llaves restauradas llegan a la salida renderizada tal como se exportaron.
# Aggregate fragment — an n8n workflow definition carried as exportedspec: components: automation: type: core/ai-agent/n8n values: workflow_id: support-reply flow_definition: | { "name": "Support reply", "nodes": [ { "name": "Set reply", "type": "n8n-nodes-base.set", "parameters": { "value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}" } } ], "connections": {} }La plataforma recibe "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".
Mantén una definición así en un escalar de bloque (|), como arriba, donde las comillas del escape son caracteres ordinarios. El texto del Aggregate también se lee como YAML antes de interpolarse, y dentro de una cadena YAML entre comillas dobles el " del escape cierra la cadena, de modo que el archivo ya no se analiza y la compilación se detiene con el error de YAML.
El patrón de acceso .parameters.<slot>
Cada slot de parámetro declarado es accesible como un campo del mapa .parameters. El acceso correcto en cuanto al tipo corresponde al type declarado:
# Aggregate fragment — parameter declarationsspec: parameters: region: { type: string, enum: [us-east-1, us-west-2] } cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 } enable_debug: { type: boolean, default: false }
components: web: type: core/web-server:1.0.0 values: region: "{{ .parameters.region }}" # string cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer debug: {{ .parameters.enable_debug }} # booleanLa pasada de interpolación produce una evaluación de plantilla Go sobre el mapa .parameters; el resultado sustituye in situ la expresión de plantilla en el documento. El esquema values: del Component / de la Feature valida después el valor resultante en la fase de validación de esquema posterior a la interpolación de la resolución.
Las comillas deciden el tipo elevado
Entrecomilla una referencia dirigida a una hoja de tipo cadena; déjala sin comillas para cualquier otro tipo declarado. La regla es la del propio YAML, no una que Aggrega añada encima: la interpolación sustituye el valor aportado en los bytes del documento y no hace nada más, de modo que el análisis que sigue lee el resultado exactamente como lee cualquier otro escalar. Un {{ .parameters.cache_ttl_seconds }} sin comillas lleva el tipo propio del valor aportado, que es lo que permite que un parámetro entero llegue a una hoja entera y que un parámetro booleano llegue a una hoja booleana. Un "{{ .parameters.cache_ttl_seconds }}" entre comillas lleva una cadena, y una hoja declarada integer o boolean la rechaza: el valor escrito no supera el esquema values: de su Component o de su Feature por el tipo, y el diagnóstico nombra la discrepancia de tipo en lugar de cualquier restricción del espacio de valores que la cadena también habría incumplido.
Una referencia que comparte su escalar con otro texto es una cadena se escriba como se escriba, porque el documento sustituido tiene un solo escalar que leer — image: app:{{ .parameters.tag }} produce app:1.4.0. Esa es la forma a la que recurrir cuando un parámetro que no es de tipo cadena tiene que llegar a una hoja de tipo cadena.
Acceso a slots de tipo objeto y de tipo array
Los slots de parámetro de tipo objeto exponen sus propiedades declaradas como campos anidados del mapa .parameters.<slot>. Los slots de tipo array exponen la semántica de slices de las plantillas Go (range, index, len).
# Aggregate fragment — object-typed parameterspec: parameters: database_config: type: object properties: host: { type: string, required: true } port: { type: integer, min: 1, max: 65535, default: 5432 } ssl_mode: { type: string, enum: [disable, require, verify-full] }
components: api: type: core/compute/api:1.0.0 values: db_host: "{{ .parameters.database_config.host }}" db_port: {{ .parameters.database_config.port }} db_ssl: "{{ .parameters.database_config.ssl_mode }}"Los slots de parámetro de tipo array admiten la iteración mediante range:
# Aggregate fragment — array-typed parameterspec: parameters: allowed_hosts: type: array items: { type: string, format: hostname } min: 1
components: ingress: type: core/ingress:1.0.0 values: # Compose a comma-separated list from the parameter array hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"Cada elemento que aporta la Release se comprueba con respecto al contrato items antes de la interpolación, de modo que un valor que no es un nombre de host — *, por ejemplo — detiene la compilación nombrando el parámetro, el elemento y el formato. Los nombres que format acepta, y lo que comprueba cada uno, se enumeran en vocabulary/compact-form-authoring.md.
La biblioteca de plantillas Sprig está disponible durante la interpolación y proporciona helpers como join para conversiones compactas de array a cadena:
hosts: "{{ join `,` .parameters.allowed_hosts }}"Semántica del relleno de valores predeterminados
Un slot de parámetro con una declaración default: recibe su valor predeterminado cuando la Release omite el slot. El valor predeterminado se aplica antes de que se ejecute la pasada de validación del contrato, de modo que la validación ve el valor resuelto (aportado por la Release o predeterminado):
# Aggregatespec: parameters: timeout_seconds: type: integer min: 1 max: 300 default: 30
components: api: type: core/compute/api:1.0.0 values: timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30# Release supplies timeout_seconds: 60 — interpolation uses 60# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)Un slot marcado con required: true sin default: provoca un error en tiempo de compilación cuando la Release lo omite (E0165). El error nombra el slot y su ubicación en el contrato para que el autor lo corrija. Un slot sin required: true ni default: es opcional: si se omite, cada referencia a él se interpola como vacía, y el esquema values: del Component juzga después el resultado.
Parámetros de objetos anidados
Cuando un parámetro declara type: object con properties: cuyos hijos llevan a su vez valores default:, tres casos de escritura producen resultados distintos. Entender la distinción importa cuando la declaración del parámetro es un objeto estructurado — una configuración de base de datos, un conjunto de feature flags, una política de timeout y reintentos — en lugar de un único escalar.
Caso 1 — la Release omite el slot padre. Se aplican los valores predeterminados de los hijos del contrato. El autor del Aggregate que declaró los valores predeterminados anidados obtiene el comportamiento que pretendía: cuando ops no aporta el slot, la configuración usa los valores predeterminados documentados.
# Aggregatespec: parameters: database: type: object properties: host: { type: string, default: "localhost" } port: { type: integer, default: 5432 }
# Release (parent omitted)spec: parameters: {}
# Resolved at template-interpolation timeparameters: database: host: "localhost" port: 5432Caso 2 — la Release escribe el padre como un mapa vacío explícito. El vacío explícito se respeta como un opt-out deliberado. Los valores predeterminados de los hijos NO se aplican; el slot permanece vacío. Usa esta forma cuando ops quiere suprimir los valores predeterminados anidados del contrato sin aportar sobrescrituras — por ejemplo, cuando un consumidor posterior espera el slot presente pero vacío.
# Release (parent explicit empty)spec: parameters: database: {}
# Resolved at template-interpolation timeparameters: database: {}La distinción con el Caso 1 es deliberada: ops puede expresar tanto «usa los valores predeterminados» (omitiendo el slot) como «suprime los valores predeterminados» (escribiendo el slot como {}). Esto refleja cómo Aggrega trata el null explícito en las anotaciones — una anotación escrita como aggrega.ai/<key>: null es un opt-out deliberado distinto de omitir la anotación por completo.
Caso 3 — la Release escribe parcialmente el padre. Los hijos que la Release aportó toman sus valores escritos; los hijos que la Release no aportó se rellenan con los valores predeterminados.
# Release (partial)spec: parameters: database: host: "db.prod.example.com"
# Resolved at template-interpolation timeparameters: database: host: "db.prod.example.com" # Release-supplied port: 5432 # filled from defaultEste es el caso habitual para los autores de Release que quieren sobrescribir campos seleccionados dejando el resto en los valores predeterminados del contrato.
Cuándo usar cada forma
- Omite el slot cuando quieras que se apliquen los valores predeterminados del contrato.
- Escribe
{}cuando quieras deliberadamente el slot presente pero vacío — cuando los valores predeterminados del contrato son incorrectos para tu entorno y no tienes sobrescrituras. - Escribe parcialmente cuando quieras algunas sobrescrituras y quieras que el resto use los valores predeterminados del contrato.
Un autor de Release que escribe database: {} esperando «dame los valores predeterminados» se llevará una sorpresa — el valor resuelto está vacío, no son los valores predeterminados rellenados. Para obtener los valores predeterminados, omite el slot por completo.
La gestión de los tres casos es por hermano a cada profundidad de anidamiento. Un padre escrito como { connection: {}, other_field: "x" } produce un árbol resuelto en el que connection está vacío (Caso 2 a profundidad 1) y other_field es el valor aportado por la Release (Caso 3 a profundidad 0) — los casos se resuelven de forma independiente para cada hermano, no como una única decisión para todo el subárbol.
Límite con los contextos de plantilla posteriores
La concesión asimétrica — las plantillas de ruta leen .parameters directamente; las plantillas de valor no — es la distinción fundamental en este límite. La semántica del límite por superficie:
- Una plantilla
values:de componente del Aggregate que escribe{{ .parameters.X }}se resuelve correctamente en la interpolación. El literal resuelto se escribe in situ en la cadena YAML. - Una plantilla
valuesMapping:de la Recipe que escribe{{ .parameters.X }}es una superficie de plantilla de valor; el contexto de plantilla no lleva.parameters. Los autores que necesitan variación por entorno envaluesMapping:la expresan a través de la ruta de consumo del.values.<key>resuelto — el Aggregate expone un parámetro, lo referencia desde losvalues:de un Component, la Release lo satisface, y el valor posterior a la interpolación fluye hasta la Recipe. - Una plantilla
injectMapping:,provides:opipeline.with:de la FeatureRecipe es una superficie de plantilla de valor; igual quevaluesMapping:de la Recipe..parametersno está en el contexto de plantilla. - Una plantilla de cuerpo de Workload (contenido
workload:dentro de una Recipe) es una superficie de plantilla de valor; lo mismo. - Una plantilla de ruta (
directory:/subDirectory:del límite de la Release) es la excepción. El contexto de plantilla de ruta incluye.parameters.<slot>con respecto a la allowlist cerrada; las referencias se resuelven cuando el renderizado coloca la salida de cada límite. Consultapath-template-variables.mdpara la matriz completa de variables de plantillas de ruta.
El límite de propiedad entre los cuatro dominios se preserva por qué superficie recibe los parámetros, no por si el mapa de parámetros existe en memoria en una fase dada de la pipeline. Las plantillas de ruta las escribe el operador y son del operador; concederles acceso directo a los parámetros mantiene las cuestiones del operador (la disposición de artefactos por entorno) dentro de la superficie del operador. Las plantillas de valor se escriben en el catálogo; negarles acceso directo a los parámetros mantiene la escritura del lado del catálogo débilmente acoplada al contrato del Aggregate como fuente única de verdad.
El mapa de parámetros fusionado sigue siendo legible hasta que se ha completado cada fase de renderizado, y no más allá: solo es accesible desde la compilación para la que se resolvió, de modo que su vida está acotada por la de la compilación.
Puente entre pilares
Los parámetros se interpolan en las cadenas de valores circundantes durante la resolución. Los valores interpolados pueden acabar en cualquier pilar que el Aggregate escriba en su ámbito: cadenas values: de componente, cadenas values: de feature, declaraciones de paso parameters: de subaggregate (donde el valor del parámetro del Aggregate padre se resuelve y luego se propaga al slot de parámetro del Aggregate hijo), y cadenas name: / labels: de los metadatos.
El puente es unidireccional: un valor de parámetro fluye desde el .parameters.<slot> aportado por la Release (o predeterminado) hacia la cadena YAML en el punto de la referencia. Los parámetros no fluyen en la otra dirección — un parámetro no puede leer un campo values:, un campo provides: ni el contenido de ningún otro pilar. La direccionalidad forma parte de la garantía del contrato de parámetros de valer solo en tiempo de compilación.
Referencias cruzadas
- Para la forma de declaración de los contratos de parámetros tipados en el Aggregate:
entities/aggregate.md§«Typed parameter contracts (Contratos de parámetros tipados)». - Para el contexto de plantilla más amplio que las Recipes consumen en el renderizado base (
.values,.infra,.uses,.context.*, etc.): template-context-contract.md. - Para la disponibilidad por punto de plantilla a lo largo de la pipeline de compilación (qué campos están presentes en qué punto de evaluación): expansion-matrix.md.
- Para la lista de comprobación de la elevación de parámetros (los cuatro puntos de contacto secuenciales de escritura — declaración en el Aggregate, referencia en values, satisfacción en la Release, consumo en la Recipe):
vocabulary/data-pillars.md§«The parameter-hoisting checklist (La lista de comprobación de la elevación de parámetros)». - Para el conjunto más amplio de pilares de datos (
values:,infra:,provides:,uses:,features:,locals:,parameters:):vocabulary/data-pillars.md.