SchemaLibrary
Uma SchemaLibrary é uma entidade de catálogo que contém definições JSON Schema 2020-12 reutilizáveis e helpers parametrizados opcionais. Os Components e as Features que partilham formas de esquema — URLs, durações, estruturas de sondas comuns, limites de recursos recorrentes — declaram essas formas uma vez numa biblioteca e referenciam-nas através de URIs $ref canónicos. A entidade de biblioteca é de Nível 3: opcional para catálogos que precisam de reutilizar esquemas entre Components. Os catálogos sem conteúdo de esquema repetido são disponibilizados sem nenhuma SchemaLibrary.
O papel da SchemaLibrary
Os arquitetos de plataforma escrevem SchemaLibraries para centralizar formas de esquema que se repetem no catálogo. Uma biblioteca não é um bloco de construção implementável; é um espaço de nomes de definições. Os autores de Component / Feature referenciam as entradas da biblioteca pelo seu URI $ref canónico, tipado uma vez e validado em todos os locais onde a referência é resolvida.
A separação entre «biblioteca» e «consumidor» é intencional. Os Components declaram o contrato que uma instância preenche (os seus values, infra e provides, os seus sockets, os seus slots de credenciais). As Features codificam anexos comportamentais. As SchemaLibraries codificam apenas conteúdo de esquema — as regras estruturais que um valor tem de satisfazer. Manter os três papéis distintos permite que cada tipo de entidade evolua ao seu próprio ritmo; os autores que não precisam de definições de esquema partilhadas nunca encontram a entidade de biblioteca.
Envelope da entidade
Uma entidade SchemaLibrary tem o envelope de catálogo habitual. apiVersion: aggrega.ai/v1beta1 e kind: SchemaLibrary marcam o tipo de entidade; metadata.name é um identificador em PascalCase; metadata.version segue estritamente o controlo semântico de versões. O conteúdo da biblioteca fica em spec: spec.schemas é obrigatório (a biblioteca tem de declarar pelo menos uma entrada), e spec.templates é opcional (presente apenas quando a biblioteca usa helpers parametrizados).
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: WebPrimitives version: 1.0.0spec: schemas: URL: type: string pattern: "^https?://" HTTPMethod: type: string enum: [GET, POST, PUT, PATCH, DELETE]Escrever entradas de esquema
As entradas de esquema são escritas numa de três formas. A forma compacta é a superfície predefinida para formas curtas e comuns — type, pattern, enum, min, max e restrições semelhantes de uma linha. O YAML JSON Schema 2020-12 é a opção de autoria equivalente para entradas que precisam de toda a superfície do JSON Schema (palavras-chave de composição, forma condicional, $defs complexos). Misturar as duas numa única entrada é suportado através do despacho por forma de conteúdo, por nó, do compilador da forma compacta; a via de escape $jsonschema: incorpora conteúdo JSON Schema completo em qualquer nó quando a forma compacta não consegue exprimir a intenção.
Um format numa entrada verifica o que verifica em qualquer esquema: indica um de email, uri, hostname, ipv4, ipv6, uuid, date-time e date, e um valor que um consumidor forneça para o campo é recusado a menos que tenha esse formato — consulte vocabulary/compact-form-authoring.md. Uma entrada que indique qualquer outro formato — incluindo password — é recusada quando a biblioteca é carregada, pelo que um aggrega validate de todo o catálogo a recusa, quer algo já a referencie quer não, indicando a biblioteca, a entrada e o nome e listando os suportados, e uma compilação ou um pull cuja Release chegue à biblioteca é interrompido por causa dela. Uma entrada que referencie outra biblioteca é avaliada no local onde um pilar de Component ou de Feature a consome. Um campo que contenha material secreto declara sensitive: true em vez de um formato.
Templates e $instantiate:
As bibliotecas com estrutura repetida substancial declaram helpers parametrizados em spec.templates. Um template contém um mapa $params: (declarações de parâmetros tipados com nome) e um corpo (conteúdo em forma compacta ou JSON Schema que referencia os parâmetros como tokens escalares $<paramName>). As entradas de esquema instanciam templates através de associações $instantiate: + $args:; o motor de substituição substitui os marcadores dos parâmetros por valores escalares literais e produz o corpo da entrada resolvida.
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: $pathA substituição é apenas de escalares literais. O motor de substituição não interpreta a sintaxe de templates Go, não avalia condicionais nem executa ciclos. Os autores que precisem de helpers mais expressivos compõem Components ou Features que consomem as entradas da biblioteca com a sua própria variação.
Convenções de nomenclatura
Os nomes de bibliotecas, as chaves das entradas de esquema e os nomes de templates seguem PascalCase. O JSON Schema do envelope da entidade impõe a convenção em três posições através de restrições de padrão:
metadata.namecorresponde a^[A-Z][A-Za-z0-9]*$.- As chaves do mapa
spec.schemascorrespondem ao mesmo padrão através depropertyNames. - As chaves do mapa
spec.templatescorrespondem ao mesmo padrão através depropertyNames.
Uma SchemaLibrary com uma chave que não esteja em PascalCase em spec.schemas ou spec.templates falha a validação do envelope no carregamento do workspace. A imposição ao nível do envelope é essencial: as chaves das entradas de esquema aparecem nos URIs $id canónicos (#/schemas/<name>); os nomes de templates são referenciados nos URIs canónicos no momento da instanciação. Detetar chaves que não estejam em PascalCase no carregamento impede que se propaguem pelo ecossistema do catálogo.
Os nomes de parâmetros dentro do mapa $params: de um template são locais ao template — não aparecem nos URIs $id canónicos e não estão sujeitos a restrições de padrão ao nível do envelope. Os autores seguem a convenção de nomenclatura que melhor se adequar aos parâmetros do template; port, path, intervalSec e nomes de parâmetros semelhantes em minúsculas são típicos.
A uniformidade de nomenclatura nos níveis de biblioteca, esquema e template torna os identificadores de referência fáceis de ler: WebPrimitives#/schemas/URL lê-se num relance.
Para a semântica de resolução de $ref: entre documentos — como $ref: é resolvido através das fronteiras de SchemaLibrary, a distinção de sintaxe de required: para consumidores com $ref:, a expansão de cadeias de biblioteca para biblioteca e o comportamento em que o consumidor restringe a biblioteca — consulte vocabulary/cross-document-ref.md.
Referenciar entradas da biblioteca
Os autores de Component / Feature referenciam uma entrada de biblioteca pela sua identidade — a forma de nome simples <Library>#/schemas/<name>:
# Inside a Component schema:spec: schema: values: healthCheck: $ref: "WebPrimitives#/schemas/URL"O nome da biblioteca é resolvido contra o catálogo resolvido; o fragmento #/schemas/<name> seleciona a entrada. Uma referência não contém nenhum host de registo; um autor pode indicar um limite mínimo de versão opcional como <Library>:<version>#/schemas/<name> (o separador de versão é :, tal como nos mapeamentos de recipes/features e na fixação do lockfile), mas a versão resolvida é fornecida pelo lockfile de cada Release, que fixa cada biblioteca consumida por nome + versão + digest de conteúdo. Uma referência que contenha um host de registo — uma forma oci://<host>/… — é rejeitada na compilação com um diagnóstico que orienta o autor para a forma de identidade, pelo que uma localização física de registo nunca entra no source escrito. O local a partir do qual os bytes da biblioteca são servidos (um diretório de catálogo local, a cache de conteúdo ou um registo remoto) é da responsabilidade do resolvedor, definido no momento da resolução; mudar a localização de um registo é uma alteração da configuração do resolvedor, não do source.
Palavras-chave JSON Schema proibidas
As palavras-chave $dynamicAnchor e $dynamicRef do JSON Schema 2020-12 são proibidas nas entradas de SchemaLibrary. O parser de SchemaLibrary analisa tanto as entradas de esquema como os corpos de templates no carregamento do workspace; o linter de publicação aplica uma proteção redundante no momento da publicação; o motor de instanciação volta a analisar o corpo resolvido após a substituição de parâmetros, pelo que um template que introduza palavras-chave proibidas através de valores de parâmetros continua a falhar. As três análises em conjunto fecham a via de introdução estática ($dynamicAnchor literal numa entrada de esquema ou corpo de template), a via de introdução paramétrica (um valor $args: que contenha $dynamicRef) e a via de contorno através de ferramentas externas (a proteção no momento da publicação apanha tudo o que tenha escapado ao parser).
Quando a rejeição ocorre, o erro cita a palavra-chave em causa e o caminho do ficheiro. Os autores veem o erro no momento da autoria e não na primeira instanciação; os corpos de templates não estão isentos da análise no carregamento.
A semântica de referências dinâmicas acopla-se à avaliação em runtime de formas que quebram o contrato de determinismo em tempo de compilação do compilador. Os autores que precisem de comportamento de referências dinâmicas reestruturam o esquema para usar a resolução estática de $ref; a verificação não admite exceções.
Posicionamento por nível
A SchemaLibrary é de Nível 3 no modelo de documentação por níveis de entidade — opcional para catálogos que precisam de reutilizar esquemas entre Components. Os catálogos sem conteúdo de esquema repetido são disponibilizados sem nenhuma entidade SchemaLibrary; a marcação de nível sinaliza «avançado; ignorar se não for necessário» para a navegação na documentação, não para a capacidade. O compilador trata a SchemaLibrary de forma uniforme com os outros tipos de entidade de catálogo: a mesma validação de envelope no carregamento do workspace, o mesmo pipeline JSON Schema 2020-12 para o conteúdo de cada entrada, o mesmo pipeline de publicação OCI no momento da release.
Dentro do Nível 3, o mecanismo de helpers paramétricos spec.templates é ele próprio opcional. As bibliotecas com estrutura repetida substancial (um template Probe parametrizado por porta + caminho; um template CORS parametrizado pelas origens permitidas; um template TLS parametrizado pelos caminhos do certificado + chave) beneficiam da reutilização de templates; as bibliotecas com entradas diversas e pontuais ignoram completamente o bloco de templates e escrevem cada entrada inline em spec.schemas.