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

SchemaLibrary

Una SchemaLibrary es una entidad de catálogo que contiene definiciones reutilizables de JSON Schema 2020-12 más helpers parametrizados opcionales. Los Components y las Features que comparten formas de esquema — URL, duraciones, estructuras de sondas comunes, límites de recursos recurrentes — declaran esas formas una sola vez en una biblioteca y las referencian mediante URI $ref canónicas. La entidad de biblioteca es de Nivel 3: opcional para los catálogos que necesitan reutilizar esquemas de un Component a otro. Los catálogos sin contenido de esquema repetido se distribuyen sin ninguna SchemaLibrary.

El rol de la SchemaLibrary

Los arquitectos de plataforma escriben SchemaLibraries para centralizar las formas de esquema que se repiten en todo el catálogo. Una biblioteca no es un bloque de construcción desplegable; es un espacio de nombres de definiciones. Los autores de Component / Feature referencian las entradas de biblioteca por su URI $ref canónica, tipada una vez y validada en todos los lugares donde se resuelve la referencia.

La separación entre «biblioteca» y «consumidor» es intencionada. Los Components declaran el contrato que completa una instancia (sus values, infra y provides, sus sockets, sus slots de credenciales). Las Features codifican vinculaciones de comportamiento. Las SchemaLibraries codifican solo contenido de esquema — las reglas estructurales que debe cumplir un valor. Mantener los tres roles diferenciados permite que cada tipo de entidad evolucione a su propio ritmo; los autores que no necesitan definiciones de esquema compartidas nunca se encuentran con la entidad de biblioteca.

Envoltorio de la entidad

Una entidad SchemaLibrary lleva el sobre estándar del catálogo. apiVersion: aggrega.ai/v1beta1 y kind: SchemaLibrary marcan el tipo de entidad; metadata.name es un identificador en PascalCase; metadata.version sigue estrictamente el versionado semántico. El contenido de la biblioteca se encuentra bajo spec: spec.schemas es obligatorio (la biblioteca debe declarar al menos una entrada), y spec.templates es opcional (presente solo cuando la biblioteca usa helpers parametrizados).

apiVersion: aggrega.ai/v1beta1
kind: SchemaLibrary
metadata:
name: WebPrimitives
version: 1.0.0
spec:
schemas:
URL:
type: string
pattern: "^https?://"
HTTPMethod:
type: string
enum: [GET, POST, PUT, PATCH, DELETE]

Escritura de entradas de esquema

Las entradas de esquema se escriben en una de tres formas. La forma compacta es la superficie predeterminada para formas breves y comunes — type, pattern, enum, min, max y restricciones similares de una línea. El YAML de JSON Schema 2020-12 es la opción de autoría de igual rango para entradas que necesitan toda la superficie de JSON Schema (palabras clave de composición, forma condicional, $defs complejos). Mezclar ambas dentro de una misma entrada se admite mediante el despacho por nodo según la forma del contenido del compilador de forma compacta; la vía de escape $jsonschema: incrusta contenido completo de JSON Schema en cualquier nodo cuando la forma compacta no puede expresar la intención.

Un format en una entrada comprueba lo que comprueba en cualquier esquema: nombra uno de email, uri, hostname, ipv4, ipv6, uuid, date-time y date, y un valor que un consumidor proporciona para el campo se rechaza a menos que tenga ese formato — consulta vocabulary/compact-form-authoring.md. Una entrada que nombra cualquier otro formato — password incluido — se rechaza cuando se carga la biblioteca, por lo que un aggrega validate de todo el catálogo la rechaza tanto si algo la referencia ya como si no, nombrando la biblioteca, la entrada y el nombre y enumerando los admitidos, y una compilación o un pull cuya Release alcanza la biblioteca se detiene en ella. Una entrada que referencia otra biblioteca se evalúa donde la consume un pilar de un Component o de una Feature. Un campo que contiene material secreto declara sensitive: true en lugar de un formato.

Plantillas y $instantiate:

Las bibliotecas con una estructura repetida considerable declaran helpers parametrizados bajo spec.templates. Una plantilla lleva un mapa $params: (declaraciones de parámetros tipados y con nombre) más un cuerpo (forma compacta o contenido de JSON Schema que referencia los parámetros como tokens escalares $<paramName>). Las entradas de esquema instancian plantillas mediante enlaces $instantiate: + $args:; el motor de sustitución reemplaza los marcadores de los parámetros por valores escalares literales y produce el cuerpo de la entrada resuelta.

spec:
schemas:
LivenessProbe:
$instantiate: ProbeTemplate
$args:
port: 8080
path: /healthz
ReadinessProbe:
$instantiate: ProbeTemplate
$args:
port: 8081
path: /ready
templates:
ProbeTemplate:
$params:
port:
type: integer
path:
type: string
type: object
properties:
port:
type: integer
const: $port
path:
type: string
const: $path

La sustitución es solo de escalares literales. El motor de sustitución no interpreta la sintaxis de plantillas de Go, no evalúa condicionales ni ejecuta bucles. Los autores que necesitan helpers más expresivos componen Components o Features que consumen las entradas de la biblioteca con su propia variación.

Convenciones de nomenclatura

Los nombres de biblioteca, las claves de las entradas de esquema y los nombres de plantilla siguen PascalCase. El JSON Schema del sobre de la entidad aplica la convención en tres posiciones mediante restricciones de patrón:

  • metadata.name coincide con ^[A-Z][A-Za-z0-9]*$.
  • Las claves del mapa spec.schemas coinciden con el mismo patrón mediante propertyNames.
  • Las claves del mapa spec.templates coinciden con el mismo patrón mediante propertyNames.

Una SchemaLibrary con una clave que no está en PascalCase en spec.schemas o spec.templates no supera la validación del sobre al cargar el workspace. La aplicación a nivel del sobre es esencial: las claves de las entradas de esquema aparecen en las URI $id canónicas (#/schemas/<name>); los nombres de plantilla hacen referencia a URI canónicas en el momento de la instanciación. Detectar las claves que no están en PascalCase al cargar impide que se propaguen por el ecosistema del catálogo.

Los nombres de los parámetros dentro del mapa $params: de una plantilla son locales a la plantilla — no aparecen en las URI $id canónicas y no están restringidos por patrón a nivel del sobre. Los autores siguen la convención de nomenclatura que mejor se adapte a los parámetros de la plantilla; port, path, intervalSec y nombres de parámetros similares en minúsculas son habituales.

La uniformidad de nombres en los niveles de biblioteca, esquema y plantilla hace que los identificadores de referencia se lean con facilidad: WebPrimitives#/schemas/URL se entiende de un vistazo.

Para la semántica de resolución de $ref: entre documentos — cómo se resuelve $ref: a través de los límites de SchemaLibrary, la distinción de sintaxis de required: para los consumidores que llevan $ref:, la expansión de cadenas de biblioteca a biblioteca y el comportamiento en el que el consumidor restringe la biblioteca — consulta vocabulary/cross-document-ref.md.

Referenciar entradas de biblioteca

Los autores de Component / Feature referencian una entrada de biblioteca por su identidad — la forma de nombre simple <Library>#/schemas/<name>:

# Inside a Component schema:
spec:
schema:
values:
healthCheck:
$ref: "WebPrimitives#/schemas/URL"

El nombre de la biblioteca se resuelve respecto al catálogo resuelto; el fragmento #/schemas/<name> selecciona la entrada. Una referencia no lleva ningún host de registro; un autor puede indicar una versión mínima opcional como <Library>:<version>#/schemas/<name> (el separador de versión es :, igual que en las asignaciones recipe/feature y en el pin del lockfile), pero la versión resuelta la proporciona el lockfile de cada Release, que fija cada biblioteca consumida por nombre + versión + digest del contenido. Una referencia que lleva un host de registro — una forma oci://<host>/… — se rechaza en la compilación con un diagnóstico que orienta al autor hacia la forma de identidad, de modo que una ubicación física de registro nunca entra en el código fuente escrito. Desde dónde se sirven los bytes de la biblioteca (un directorio de catálogo local, la caché de contenido o un registro remoto) es asunto del resolver, enlazado en el momento de la resolución; trasladar un registro es un cambio de configuración del resolver, no un cambio del código fuente.

Palabras clave de JSON Schema prohibidas

Las palabras clave $dynamicAnchor y $dynamicRef de JSON Schema 2020-12 están prohibidas en las entradas de SchemaLibrary. El parser de SchemaLibrary analiza tanto las entradas de esquema como los cuerpos de las plantillas al cargar el workspace; el linter de publicación aplica una protección redundante en el momento de la publicación; el motor de instanciación vuelve a analizar el cuerpo resuelto tras la sustitución de parámetros, de modo que una plantilla que cuele palabras clave prohibidas mediante valores de parámetros sigue fallando. Los tres análisis juntos cierran la vía de introducción estática ($dynamicAnchor literal en una entrada de esquema o en el cuerpo de una plantilla), la vía de introducción paramétrica (un valor de $args: que contiene $dynamicRef) y la vía de elusión mediante herramientas externas (la protección en el momento de la publicación detecta todo lo que se haya saltado el parser).

Cuando el rechazo se activa, el error cita la palabra clave infractora y la ruta del archivo. Los autores ven el error en el momento de la escritura en lugar de en la primera instanciación; los cuerpos de las plantillas no están exentos del análisis en la carga.

La semántica de las referencias dinámicas se acopla a la evaluación en tiempo de ejecución de formas que rompen el contrato de determinismo en tiempo de compilación del compilador. Los autores que necesitan un comportamiento de referencias dinámicas reestructuran el esquema para usar la resolución estática de $ref; la comprobación no admite excepciones.

Ubicación en los tiers

SchemaLibrary es de Nivel 3 en el modelo de documentación por niveles de las entidades — opcional para los catálogos que necesitan reutilizar esquemas de un Component a otro. Los catálogos sin contenido de esquema repetido se distribuyen sin ninguna entidad SchemaLibrary; la marca de nivel indica «avanzado; omitir si no se necesita» para la navegación de la documentación, no una capacidad. El compilador trata SchemaLibrary de manera uniforme con los demás tipos de entidad de catálogo: la misma validación del sobre al cargar el workspace, la misma canalización de JSON Schema 2020-12 para el contenido de cada entrada, la misma canalización de publicación OCI en el momento de publicar una versión.

Dentro del Nivel 3, el mecanismo de helpers paramétricos spec.templates es a su vez opcional. Las bibliotecas con una estructura repetida considerable (una plantilla Probe parametrizada por puerto + ruta; una plantilla CORS parametrizada por los orígenes permitidos; una plantilla TLS parametrizada por las rutas de certificado + clave) se benefician de la reutilización mediante templates; las bibliotecas con entradas diversas y puntuales omiten por completo el bloque de plantillas y escriben cada entrada en línea bajo spec.schemas.