SchemaLibrary
SchemaLibrary, yeniden kullanılabilir JSON Schema 2020-12 tanımlarını ve isteğe bağlı parametreli yardımcıları barındıran bir katalog varlığıdır. Şema biçimlerini paylaşan Components ve Features — URL’ler, süreler, ortak yoklama yapıları, tekrarlanan kaynak sınırları — bu biçimleri bir kütüphanede bir kez bildirir ve onlara kanonik $ref URI’leri aracılığıyla başvurur. Kütüphane varlığı Tier 3’tür: Component’ler arası şema yeniden kullanımına ihtiyaç duyan kataloglar için isteğe bağlıdır. Tekrarlanan şema içeriği olmayan kataloglar hiçbir SchemaLibrary olmadan yayımlanır.
SchemaLibrary’nin rolü
Platform mimarları, katalog genelinde yinelenen şema biçimlerini merkezileştirmek için SchemaLibraries yazar. Bir kütüphane dağıtılabilir bir yapı taşı değildir; bir tanımlar ad alanıdır. Component / Feature yazarları kütüphane girdilerine kanonik $ref URI’leriyle başvurur; bu girdiler bir kez tiplendirilir ve başvurunun çözümlendiği her yerde doğrulanır.
“Kütüphane” ile “tüketici” arasındaki ayrım bilinçlidir. Components bir örneğin doldurduğu sözleşmeyi (değerlerini, infra ve provides alanlarını, soketlerini, kimlik bilgisi yuvalarını) bildirir. Features davranışsal eklentileri kodlar. SchemaLibraries yalnızca şema içeriğini, yani bir değerin karşılaması gereken yapısal kuralları kodlar. Üç rolü ayrı tutmak, her varlık türünün kendi temposunda gelişmesini sağlar; paylaşılan şema tanımlarına ihtiyaç duymayan yazarlar kütüphane varlığıyla hiç karşılaşmaz.
Varlık zarfı
Bir SchemaLibrary varlığı standart katalog zarfını taşır. apiVersion: aggrega.ai/v1beta1 ve kind: SchemaLibrary varlık türünü belirtir; metadata.name PascalCase bir tanımlayıcıdır; metadata.version katı anlamsal sürümlemeye uyar. Kütüphanenin içeriği spec altında yer alır: spec.schemas zorunludur (kütüphane en az bir giriş bildirmelidir) ve spec.templates isteğe bağlıdır (yalnızca kütüphane parametreli yardımcılar kullandığında bulunur).
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]Şema girdilerinin yazılması
Şema girdileri üç biçimden biriyle yazılır. Kompakt biçim, kısa ve yaygın yapılar için varsayılan yüzeydir: type, pattern, enum, min, max ve benzeri tek satırlık kısıtlamalar. JSON Schema 2020-12 YAML, tam JSON Schema yüzeyine (birleştirme anahtar sözcükleri, koşullu yapı, karmaşık $defs) ihtiyaç duyan girdiler için eşdeğer bir yazım seçeneğidir. İkisinin tek bir girdi içinde karıştırılması, kompakt biçim derleyicisinin düğüm başına içerik yapısı yönlendirmesi sayesinde desteklenir; $jsonschema: kaçış yolu, kompakt biçim amacı ifade edemediğinde herhangi bir düğüme tam JSON Schema içeriği gömer.
Bir girdideki format, herhangi bir şemada denetlediği şeyi denetler: email, uri, hostname, ipv4, ipv6, uuid, date-time ve date biçimlerinden birini adlandırır ve bir tüketicinin alan için sağladığı değer, o biçime sahip olmadıkça reddedilir; bkz. vocabulary/compact-form-authoring.md. Başka bir biçimi adlandıran bir girdi (password dahil) kütüphane yüklendiğinde reddedilir; bu nedenle katalog genelindeki bir aggrega validate, henüz ona herhangi bir şey başvurmasa da kütüphaneyi, girdiyi ve adı belirterek ve desteklenen biçimleri listeleyerek onu reddeder; Release’i kütüphaneye ulaşan bir derleme veya çekme işlemi de bu girdide durur. Başka bir kütüphaneye başvuran bir girdi, bir Component veya Feature sütununun onu tükettiği yerde değerlendirilir. Gizli malzeme taşıyan bir alan, bir biçim yerine sensitive: true bildirir.
Şablonlar ve $instantiate:
Önemli ölçüde tekrarlanan yapıya sahip kütüphaneler, parametreli yardımcıları spec.templates altında bildirir. Bir şablon, bir $params: eşlemesi (adlandırılmış, türü belirtilmiş parametre bildirimleri) ile bir gövde (parametrelere $<paramName> skaler belirteçleri olarak başvuran compact form ya da JSON Schema içeriği) taşır. Şema girdileri, şablonları $instantiate: + $args: bağlamalarıyla örnekler; yerine koyma motoru, parametre yer tutucularını değişmez skaler değerlerle değiştirir ve çözümlenmiş girdinin gövdesini üretir.
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: $pathYerine koyma yalnızca değişmez skaler değerlerle yapılır. Yerine koyma motoru Go şablon sözdizimini yorumlamaz, koşulları değerlendirmez ve döngü çalıştırmaz. Daha ifade gücü yüksek yardımcılara ihtiyaç duyan yazarlar, kütüphane girdilerini kendi varyasyonlarıyla tüketen Components ya da Features oluşturur.
Adlandırma uzlaşımları
Kütüphane adları, şema girdisi anahtarları ve şablon adları PascalCase biçimini izler. Varlık zarfının JSON Schema’sı bu uzlaşımı üç konumda örüntü kısıtlamalarıyla uygular:
metadata.name,^[A-Z][A-Za-z0-9]*$ile eşleşir.spec.schemaseşleme anahtarlarıpropertyNamesaracılığıyla aynı örüntüyle eşleşir.spec.templateseşleme anahtarlarıpropertyNamesaracılığıyla aynı örüntüyle eşleşir.
spec.schemas veya spec.templates içinde PascalCase olmayan bir anahtar bulunan bir SchemaLibrary, çalışma alanı yüklenirken zarf doğrulamasında başarısız olur. Zarf düzeyindeki bu uygulama yük taşıyıcıdır: şema girdisi anahtarları kanonik $id URI’lerinde (#/schemas/<name>) yer alır; şablon adları ise örnekleme sırasında kanonik URI’lere başvurur. PascalCase olmayan anahtarları yükleme sırasında yakalamak, bunların katalog ekosistemi boyunca yayılmasını önler.
Bir şablonun $params: eşlemesindeki parametre adları şablona yereldir — kanonik $id URI’lerinde yer almazlar ve zarf düzeyinde örüntüyle kısıtlanmazlar. Yazarlar, şablonun parametrelerine uyan herhangi bir adlandırma uzlaşımını izler; port, path, intervalSec ve benzeri küçük harfli parametre adları tipiktir.
Kütüphane, şema ve şablon düzeylerindeki adlandırma tekdüzeliği, başvuru tanımlayıcılarının kolayca okunmasını sağlar: WebPrimitives#/schemas/URL bir bakışta okunur.
Belgeler arası $ref: çözümleme semantiği için — $ref: ifadesinin SchemaLibrary sınırları boyunca nasıl çözümlendiği, $ref: taşıyan tüketiciler için required: sözdizimi ayrımı, kütüphaneden kütüphaneye zincir genişletmesi ve tüketicinin kütüphaneyi daraltması davranışı — bkz. vocabulary/cross-document-ref.md.
Kütüphane girdilerine başvurma
Component / Feature yazarları bir kütüphane girdisine kimliği ile, yani yalın ad biçimi olan <Library>#/schemas/<name> ile başvurur:
# Inside a Component schema:spec: schema: values: healthCheck: $ref: "WebPrimitives#/schemas/URL"Kütüphane adı, çözümlenmiş kataloğa göre çözümlenir; #/schemas/<name> parçası girdiyi seçer. Bir başvuru kayıt defteri ana bilgisayarı taşımaz; yazar isteğe bağlı bir asgari sürüm tabanını <Library>:<version>#/schemas/<name> biçiminde belirtebilir (sürüm ayırıcısı, recipe/feature eşlemeleri ve kilit dosyası sabitlemesiyle uyumlu olarak : karakteridir), ancak çözümlenen sürümü, tüketilen her kütüphaneyi ad + sürüm + içerik özeti ile sabitleyen Release başına kilit dosyası sağlar. Kayıt defteri ana bilgisayarı taşıyan bir başvuru, yani oci://<host>/… biçimi, derleme sırasında yazarı kimlik biçimine yönlendiren bir tanılama ile reddedilir; böylece fiziksel bir kayıt defteri konumu hiçbir zaman yazılan kaynağa girmez. Kütüphanenin baytlarının nereden sunulduğu (yerel bir katalog dizini, içerik önbelleği veya uzak bir kayıt defteri) çözümleyicinin işidir ve çözümleme zamanında bağlanır; bir kayıt defterinin yerini değiştirmek kaynak değişikliği değil, çözümleyici yapılandırması değişikliğidir.
Yasaklı JSON Schema anahtar sözcükleri
JSON Schema 2020-12’nin $dynamicAnchor ve $dynamicRef anahtar sözcükleri, SchemaLibrary girdilerinde yasaktır. SchemaLibrary ayrıştırıcısı, çalışma alanı yükleme zamanında hem şema girdilerini hem de şablon gövdelerini tarar; yayımlama denetleyicisi yayımlama zamanında yedek bir koruma uygular; örnekleme motoru ise parametre yerine koymadan sonra çözümlenmiş gövdeyi yeniden tarar; böylece yasaklı anahtar sözcükleri parametre değerleri yoluyla içeri sokan bir şablon da yine başarısız olur. Üç tarama birlikte statik ekleme yolunu (bir şema girdisinde veya şablon gövdesinde doğrudan yazılmış $dynamicAnchor), parametrik ekleme yolunu ($dynamicRef içeren bir $args: değeri) ve bant dışı araçlarla atlatma yolunu (yayımlama zamanı koruması, ayrıştırıcıyı atlayan her şeyi yakalar) kapatır.
Reddetme tetiklendiğinde hata, soruna yol açan anahtar sözcüğü ve dosya yolunu belirtir. Yazarlar hatayı ilk örneklemede değil, yazma sırasında görür; şablon gövdeleri yükleme zamanı taramasından muaf tutulmaz.
Dinamik başvuru semantiği, çalışma zamanı değerlendirmesine derleyicinin derleme zamanı belirlenimcilik sözleşmesini bozacak biçimlerde bağlıdır. Dinamik başvuru davranışına ihtiyaç duyan yazarlar, şemayı statik $ref çözümlemesini kullanacak şekilde yeniden yapılandırır; bu denetimin devre dışı bırakılma seçeneği yoktur.
Katman yerleşimi
SchemaLibrary, varlık katmanı dokümantasyon modelinde Katman 3’tür; Component’ler arası şema yeniden kullanımına ihtiyaç duyan kataloglar için isteğe bağlıdır. Tekrarlanan şema içeriği olmayan kataloglar hiçbir SchemaLibrary varlığı olmadan yayımlanır; katman işareti, bir yetenek değil, dokümantasyonda gezinme için “ileri düzey; gerekmiyorsa atlayın” anlamını taşır. Derleyici SchemaLibrary’yi diğer katalog varlık türleriyle aynı şekilde ele alır: çalışma alanı yüklemesinde aynı zarf doğrulaması, girdi başına içerik için aynı JSON Schema 2020-12 işlem hattı, sürüm zamanında aynı OCI yayımlama işlem hattı.
Katman 3 içinde, spec.templates parametrik yardımcılar mekanizmasının kendisi de isteğe bağlıdır. Kayda değer ölçüde tekrarlanan yapıya sahip kütüphaneler (port + yol üzerinden parametrelenen bir Probe şablonu; izin verilen kaynaklar üzerinden parametrelenen bir CORS şablonu; sertifika + anahtar yolları üzerinden parametrelenen bir TLS şablonu) templates yeniden kullanımından yararlanır; çeşitli, tek seferlik girdilere sahip kütüphaneler şablon bloğunu tamamen atlar ve her girdiyi spec.schemas altında satır içinde yazar.