SchemaLibrary
Uma SchemaLibrary é uma entidade de catálogo que contém definições reutilizáveis de JSON Schema 2020-12 mais helpers parametrizados opcionais. Components e Features que compartilham formas de esquema — URLs, durações, estruturas comuns de probes, limites de recursos recorrentes — declaram essas formas uma única vez em uma biblioteca e as referenciam por URIs $ref canônicas. A entidade de biblioteca é de Nível 3: opcional para catálogos que precisam reutilizar esquemas entre um Component e outro. Catálogos sem conteúdo de esquema repetido são distribuídos sem nenhuma SchemaLibrary.
O papel da SchemaLibrary
Arquitetos de plataforma escrevem SchemaLibraries para centralizar formas de esquema que se repetem pelo catálogo. Uma biblioteca não é um bloco de construção implantável; é um namespace de definições. Autores de Component / Feature referenciam entradas de biblioteca pela sua URI $ref canônica, tipada uma vez e validada em todo lugar 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 vinculações comportamentais. As SchemaLibraries codificam apenas conteúdo de esquema — as regras estruturais que um valor deve satisfazer. Manter os três papéis distintos permite que cada tipo de entidade evolua no seu próprio ritmo; autores que não precisam de definições de esquema compartilhadas nunca encontram a entidade de biblioteca.
Envelope da entidade
Uma entidade SchemaLibrary carrega o envelope padrão do catálogo. apiVersion: aggrega.ai/v1beta1 e kind: SchemaLibrary marcam o tipo de entidade; metadata.name é um identificador em PascalCase; metadata.version segue estritamente o versionamento semântico. O conteúdo da biblioteca fica em spec: spec.schemas é obrigatório (a biblioteca deve 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]Escrevendo entradas de esquema
As entradas de esquema são escritas em uma de três formas. A forma compacta é a superfície padrão para formas curtas e comuns — type, pattern, enum, min, max e restrições semelhantes de uma linha. O YAML de JSON Schema 2020-12 é a opção de autoria de mesmo nível para entradas que precisam de toda a superfície do JSON Schema (palavras-chave de composição, forma condicional, $defs complexos). Misturar as duas em uma única entrada é suportado pelo despacho por nó conforme a forma do conteúdo do compilador da forma compacta; a via de escape $jsonschema: incorpora conteúdo completo de JSON Schema em qualquer nó quando a forma compacta não consegue expressar a intenção.
Um format em uma entrada verifica o que verifica em qualquer esquema: ele nomeia um entre email, uri, hostname, ipv4, ipv6, uuid, date-time e date, e um valor que um consumidor fornece para o campo é recusado a menos que tenha esse formato — consulte vocabulary/compact-form-authoring.md. Uma entrada que nomeia qualquer outro formato — password incluído — é recusada quando a biblioteca é carregada, então um aggrega validate do catálogo inteiro a recusa quer algo já a referencie ou não, nomeando a biblioteca, a entrada e o nome e listando os suportados, e um build ou pull cuja Release alcança a biblioteca é interrompido nela. Uma entrada que referencia outra biblioteca é avaliada onde um pilar de um Component ou de uma Feature a consome. Um campo que carrega material secreto declara sensitive: true em vez de um formato.
Templates e $instantiate:
Bibliotecas com estrutura repetida substancial declaram helpers parametrizados em spec.templates. Um template carrega um mapa $params: (declarações de parâmetros nomeados e tipados) mais um corpo (forma compacta ou conteúdo de JSON Schema que referencia os parâmetros como tokens escalares $<paramName>). As entradas de esquema instanciam templates por meio de associações $instantiate: + $args:; o mecanismo de substituição troca os marcadores de parâmetro 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 mecanismo de substituição não interpreta sintaxe de templates Go, não avalia condicionais nem executa laços. Autores que precisam 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
Nomes de bibliotecas, chaves de entradas de esquema e nomes de templates seguem PascalCase. O JSON Schema do envelope da entidade impõe a convenção em três posições por meio 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 por meio depropertyNames. - As chaves do mapa
spec.templatescorrespondem ao mesmo padrão por meio depropertyNames.
Uma SchemaLibrary com uma chave fora do PascalCase em spec.schemas ou spec.templates falha na validação do envelope no carregamento do workspace. A aplicação no nível do envelope é essencial: chaves de entradas de esquema aparecem em URIs $id canônicas (#/schemas/<name>); nomes de templates fazem referência a URIs canônicas no momento da instanciação. Detectar chaves fora do PascalCase no carregamento impede que elas se propaguem pelo ecossistema do catálogo.
Os nomes de parâmetros dentro do mapa $params: de um template são locais ao template — eles não aparecem em URIs $id canônicas e não são restringidos por padrão no nível do envelope. Os autores seguem a convenção de nomenclatura que 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 se entende num relance.
Para a semântica de resolução de $ref: entre documentos — como $ref: é resolvido através de limites de SchemaLibrary, a distinção de sintaxe de required: para consumidores que carregam $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.
Referenciando entradas de biblioteca
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 em relação ao catálogo resolvido; o fragmento #/schemas/<name> seleciona a entrada. Uma referência não carrega host de registro; um autor pode declarar uma versão mínima opcional como <Library>:<version>#/schemas/<name> (o separador de versão é :, como nos mapeamentos recipe/feature e no pin do lockfile), mas a versão resolvida é fornecida pelo lockfile de cada Release, que fixa cada biblioteca consumida por nome + versão + digest do conteúdo. Uma referência que carrega um host de registro — uma forma oci://<host>/… — é recusada na compilação com um diagnóstico que orienta o autor para a forma de identidade, de modo que uma localização física de registro nunca entra no código-fonte escrito. De onde os bytes da biblioteca são servidos (um diretório de catálogo local, o cache de conteúdo ou um registro remoto) é responsabilidade do resolvedor, associada no momento da resolução; mudar um registro de lugar é uma alteração na configuração do resolvedor, não no código-fonte.
Palavras-chave de 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 examina tanto as entradas de esquema quanto os corpos de templates no carregamento do workspace; o linter de publicação aplica uma proteção redundante no momento da publicação; o mecanismo de instanciação examina novamente o corpo resolvido após a substituição de parâmetros, de modo que um template que introduza palavras-chave proibidas por meio de valores de parâmetros ainda falha. As três verificações juntas fecham a via de introdução estática ($dynamicAnchor literal em uma entrada de esquema ou corpo de template), a via de introdução paramétrica (um valor $args: contendo $dynamicRef) e a via de desvio por ferramentas externas (a proteção no momento da publicação captura tudo o que tenha escapado do parser).
Quando a recusa é acionada, o erro cita a palavra-chave infratora e o caminho do arquivo. Os autores veem o erro no momento da escrita, e não na primeira instanciação; os corpos de templates não estão isentos da verificação no carregamento.
A semântica de referências dinâmicas se acopla à avaliação em tempo de execução de formas que quebram o contrato de determinismo em tempo de compilação do compilador. Autores que precisam 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 nos tiers
SchemaLibrary é de Nível 3 no modelo de documentação por níveis de entidades — opcional para catálogos que precisam reutilizar esquemas entre um Component e outro. Catálogos sem conteúdo de esquema repetido são distribuídos sem nenhuma entidade SchemaLibrary; a marcação de nível sinaliza “avançado; pule se não precisar” para a navegação da documentação, não uma capacidade. O compilador trata SchemaLibrary de forma uniforme com os outros tipos de entidade de catálogo: a mesma validação do envelope no carregamento do workspace, o mesmo pipeline de JSON Schema 2020-12 para o conteúdo de cada entrada, o mesmo pipeline de publicação OCI no momento do lançamento de uma versão.
Dentro do Nível 3, o mecanismo de helpers paramétricos spec.templates é ele mesmo opcional. 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 de certificado + chave) se beneficiam da reutilização de templates; bibliotecas com entradas diversas e pontuais ignoram completamente o bloco de templates e escrevem cada entrada inline em spec.schemas.