Kompakt biçimde yazım
Kompakt biçim, JSON Schema 2020-12 için YAML biçimli, bildirimsel bir kısaltmadır. Yazarlar alan başına kısıtları satır içi akış YAML eşlemleri olarak yazar (port: { type: integer, min: 1, max: 65535, default: 8080 }); ara nesne düğümleri doğal YAML iç içeliğiyle ifade edilir; başvurular JSON Schema’nın standart $ref: anahtarını kullanır. Derleyici, herhangi bir doğrulama çalışmadan önce kompakt biçimi JSON Schema 2020-12’ye dönüştürür; böylece doğrulama, hata raporlama ve bir şemayı okuyan her araç, şema hangi biçimde yazılmış olursa olsun çözümlenmiş JSON Schema üzerinde çalışır.
Bu sayfa kompakt biçim sözcük dağarcığını, yapısal uzlaşımları, çıkarımsal ve açık nesne biçimi ayrımını, kapanış semantiğini, izin verilen türlerden oluşan dizilere olanak tanıyan type: çeşitliliğini, her çıkarımsal biçim kapsamında ayrılmış anahtar sözcükleri ve x-aggrega-* uzantı ad alanını belgeler. Belgeler arası $ref: çözümleme semantiği için bkz. cross-document-ref.md. Assertions bloğu yazım grameri için bkz. templates/assertions-block.md. Veri sütunları kümesi (values:, infra:, provides:, uses:, features:, locals:, parameters:) için bkz. data-pillars.md.
Kompakt biçim; schema:, parameters: ve SchemaLibrary girdileri için varsayılan yazım yüzeyidir. JSON Schema YAML eşit düzeyde bir yazım seçeneğidir; iki biçim de birinci sınıftır ve tek bir şema içinde karıştırılabilir. İki biçim de aynı çözümlenmiş JSON Schema belgesine derlenir; sonraki araçlar ve doğrulama, yazım yolunun farkında değildir.
Sözcük dağarcığı
Kompakt biçimin anahtar sözcükleri aşağıdaki tablolarda yer alanlardır. Yazarlar bunları bir kez öğrenir ve schema:, parameters: ile SchemaLibrary girdilerinin tümünde uygular.
Tür ve kimlik anahtar sözcükleri
| Anahtar sözcük | Anlam | JSON Schema karşılığı |
|---|---|---|
type | Alan türü (string, integer, number, boolean, object, array ya da izin verilen türlerden oluşan bir dizi) | type: |
description | İnsan tarafından okunabilir belgeleme | description: |
default | Alan eksik olduğunda kullanılan varsayılan değer | default: |
required | Bulunması gereken alanlar için yaprak düzeyinde işaret (required: true) | Alan adını üst düğümün required: dizisine ekler |
Kısıt anahtar sözcükleri
| Anahtar sözcük | Anlam | JSON Schema karşılığı |
|---|---|---|
enum | İzin verilen değerler (liste) | enum: |
const | İzin verilen tek değer — bir skaler, bir eşlem ya da bir liste | const: |
min | En küçük değer (sayısal) ya da en küçük uzunluk (string/dizi) | minimum: (sayısal); minLength: (string); minItems: (dizi) — type: değerine göre seçilir |
max | En büyük değer ya da uzunluk, min ile paralel | maximum: / maxLength: / maxItems: |
minLength / maxLength | Açık string uzunluğu kısıtları | Doğrudan minLength: / maxLength: karşılığı (min/max belirsiz kalacağında kullanın) |
pattern | String’ler için düzenli ifade deseni | pattern: |
format | Bir string’in sahip olması gereken adlandırılmış biçim — email, uri, hostname, ipv4, ipv6, uuid, date-time, date değerlerinden biri (bkz. Adlandırılmış biçimler) | format: |
Bir Aggregate’in parameters: bloğunda bunların bazıları, herhangi bir Release değeri okunmadan önce bildirimin kendisi üzerinde de denetlenir. Bir parametrenin kendi minLength ve maxLength değerleri sıfır ya da daha büyüktür — negatif bir değer Aggregate yüklenirken reddedilir — ve iç içe bir items, properties ya da valuesType sözleşmesi içindekiler de dahil her pattern, derlenebilen bir düzenli ifade olmalıdır; çünkü desen, parametre sözleşmesi okunurken derlenir. Her format, hangi derinlikte olursa olsun, aşağıdaki adlandırılmış biçimlerden biri olmalıdır. Boolean veya nesne türündeki bir parametre üzerindeki min ya da max de reddedilir, çünkü bu çift o türlerde hiçbir şeyi sınırlamaz. Bu hataların her biri, bir Release parametreyi sağlasın ya da sağlamasın, parametrenin adını vererek derlemeyi durdurur. İç içe bir sözleşmenin içindeki uzunluk sınırı bu alt sınıra tabi değildir; her denetimin nerede çalıştığı için bkz. entities/aggregate.md.
Adlandırılmış biçimler
format, bir string değerin sahip olması gereken şekli adlandırır. Adlar, JSON Schema belirtiminin tanımladığı adlardır ve belirtimin yazdığı gibi yazılır; her biri, belirtimin ona yüklediği anlamı denetler:
| Ad | Uygun bir değer şudur | Tanımlayan |
|---|---|---|
email | bir posta kutusu: bir yerel kısım (noktayla ayrılmış atomlar ya da tırnaklı bir string), @, ardından bir alan adı ya da köşeli parantezli bir adres değişmezi — ops@example.com. Joe <joe@example.com> gibi bir görünen ad, posta kutusu değildir | RFC 5321, bölüm 4.1.2 (Mailbox) |
uri | mutlak bir URI: bir şema, :, ardından geri kalanı; URI alfabesi dışındaki her karakter yüzde kodlamalıdır — https://example.com/a%20b, s3://bucket/key. /path gibi göreli bir başvuru mutlak URI değildir | RFC 3986 (URI) |
hostname | bir ana makine adı: harf, rakam ve tirelerden oluşan, noktayla ayrılmış etiketler; her biri 1–63 karakterdir ve tireyle başlamaz ya da bitmez, toplamda en çok 253 karakter — db-primary.data.svc.cluster.local. Punycode etiketi (xn--…) yazıldığı gibi kabul edilir; joker karakter *, alt çizgi ya da sondaki nokta kabul edilmez | RFC 1123, bölüm 2.1 |
ipv4 | noktalarla ayrılmış, 0 ile 255 arasında dört ondalık sayı — 192.0.2.1 | RFC 2673, bölüm 3.2 (noktalı dörtlü) |
ipv6 | metin biçimlerinden herhangi birinde bir IPv6 adresi — tam, :: ile sıkıştırılmış ya da bir IPv4 adresiyle biten — 2001:db8::1. Bir bölge (%eth0) ya da önek uzunluğu (/64) adresin parçası değildir | RFC 4291, bölüm 2.2 |
uuid | tirelerle ayrılmış 8-4-4-4-12 gruplarında, büyük ya da küçük harfle 32 onaltılık basamak — 2eb8aa08-aa98-11ea-b4aa-73b441d16380 | RFC 4122, bölüm 3 |
date-time | farklı saat dilimi içeren bir zaman damgası — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00; gün, ayında var olan bir gün olmalıdır ve artık saniye yalnızca 23:59 UTC’de bulunabilir | RFC 3339, bölüm 5.6 (date-time) |
date | günü, ayında ve yılında var olan bir takvim tarihi — 2026-09-28 | RFC 3339, bölüm 5.6 (full-date) |
Bir biçim yalnızca string’leri değerlendirir: başka türdeki bir değeri değerlendirmek, o değerin type’ına düşer. Ayrıca yalnızca değerin sözdizimini değerlendirir — ana makine adı asla çözümlenmez, URI asla getirilmez, posta kutusuyla asla iletişime geçilmez — böylece denetim her derlemede aynı yanıtı verir ve ağ gerektirmez.
Denetim, bir değerin şemasına göre doğrulandığı her yerde çalışır: bir Aggregate’in parameters: alanı, bir Component’in ya da Feature’ın schema: sütunlarının kısıtladığı values ve infra, bir usesSchema: soketinin yük şemalarının kısıtladığı kenar başına values ve infra, ve bu şemaların ulaştığı her SchemaLibrary girdisi. Bir provides sütununun biçim adları, katalog yüklenirken diğer şemalarınki gibi değerlendirilir; bir Recipe’nin yayımladığı değerler sütuna göre doğrulanmaz, bu nedenle bunlar üzerinde hiçbir biçim denetlenmez. allOf, anyOf, oneOf ve not içinde, biçimini karşılamayan bir değer, tıpkı başka herhangi bir kısıtı karşılamayan bir değer gibi, o dalı karşılamayan bir değerdir. Uygun olmayan bir değer; alan, değer ve biçim adı belirtilerek reddedilir.
Tablo dışındaki bir ad, şema yüklenirken reddedilir; herhangi bir değer ona ulaşsın ya da ulaşmasın ret, desteklenen adları listeler — böylece emial gibi bir yazım hatası, hiçbir şey denetlemeyen bir kısıt değil bir tanılama olur. Bir SchemaLibrary girdisi için hatalı adı görmek üzere tüm katalog üzerinde aggrega validate komutunu çalıştırın: şemaları girdiye ulaşan bir Release de reddedilir, ancak kütüphaneyi bulunamadı olarak bildirir. password bir biçim değildir: gizli bilgi taşıyan bir alan bunun yerine sensitive: true bildirir.
Dolaylı olarak ulaşılan şekiller için bir sınır geçerlidir. Bir alanın şekli, yanında başka anahtar sözcükler (örneğin bir properties: eşlemesi) taşıyan bir $ref: aracılığıyla, bir when: ifadesinin then: ya da else: kısmı aracılığıyla veya bildirilmiş bir özelliğe işaret eden bir işaretçi aracılığıyla geliyorsa, format değeri şeklin doğrudan ve allOf aracılığıyla bildirdiği alanlarda denetlenir — ancak o şeklin içindeki bir anyOf, oneOf, not ya da koşullu dal içinde denetlenmez.
Bileşim ve başvuru anahtar sözcükleri
| Anahtar sözcük | Anlam | JSON Schema karşılığı |
|---|---|---|
$ref | Bir JSON Pointer parçasına ya da harici bir SchemaLibrary girdisine başvuru | $ref: |
allOf / anyOf / oneOf | JSON Schema bileşimi | Aynı anahtar sözcükler |
patternProperties | Düzenli ifade anahtarlı eşlem | Aynı anahtar sözcük |
valuesType | Türlendirilmiş değer eşlemleri için kısaltma (örn. “tüm değerleri string olan nesne”) | additionalProperties: { type: <X> } |
Kapsayıcı anahtar sözcükleri
| Anahtar sözcük | Anlam | JSON Schema karşılığı |
|---|---|---|
items | Dizi öğesinin şekli | items: (özyinelemeli kompakt biçim ya da JSON Schema) |
properties | Açık alt öğe bildirimi (nadiren gerekir; genellikle YAML yapısıyla örtük olarak verilir) | properties: |
additionalProperties | Bildirilmemiş özelliklere izin verilip verilmediği (çıkarımsal biçimdeki bir nesnede derleyicinin eklediği false; açık bir type: object üzerinde bunu siz yazarsınız ve yazmadığınız yerde JSON Schema’nın kendi varsayılanı olan true geçerlidir) | additionalProperties: |
Aggrega’ya özgü anahtar sözcükler
| Anahtar sözcük | Anlam |
|---|---|
validate | Boolean döndüren, alan düzeyinde Go şablonu yüklemi; false sonucu doğrulamayı validateMessage: ile durdurur |
validateMessage | Bir validate: başarısızlığına eşlik eden hata iletisi |
when | Koşullu alt ağaç uygulaması; düğümün kısıtlarının uygulanıp uygulanmayacağını belirleyen Go şablonu yüklemi |
sensitive | Bu yaprağın gizli bilgi taşıdığını bildirir. x-aggrega-sensitive: true olarak derlenir. Aşağıdaki “Bir yaprağı hassas olarak bildirme” bölümüne bakın |
$jsonschema | Kaçış yolu — bu düğüme gömülü tam bir JSON Schema alt belgesi |
$mode | Belirsiz durumlar için isteğe bağlı yönlendirme ek açıklaması (nadiren gerekir; aşağıdaki “Çıkarımlı ve açık nesne biçimi” bölümüne bakın) |
JSON Schema’dan ödünç alınan anahtar sözcükler ($ref, allOf, format vb.) JSON Schema ile aynı sözdizimini kullanır; böylece JSON Schema’yı zaten bilen yazarlar bunları hemen tanır.
Değeri veri olan bir anahtar sözcük, bu değeri yazıldığı gibi taşır. default, enum veya const için verilen bir eşlem ya da liste değerin kendisidir, asla iç içe bir şema değildir: endpoint: { type: object, default: { host: db, port: 5432 } }, endpoint için varsayılanı o nesne yapar ve mode: { type: object, const: { kind: fast } } tam olarak o nesneyi kabul eder — mode: { const: { kind: fast } } de öyle, çünkü const, enum gibi düğümü tek başına bir yaprak yapar. Aynısı bir $jsonschema: kaçış yolu içinde de geçerlidir.
Kompakt biçimli bir yaprağın yapısı
Yazımın birimi bir yaprak düğümdür — kısıt sözlüğüne sahip bir alan:
field_name: { type: <type>, ...constraints... }Yaygın kalıplar:
port: { type: integer, default: 8080 }port: { type: integer, min: 1, max: 65535, default: 8080 }identifier: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$" }log_level: { type: string, enum: [debug, info, warn, error], default: info }name: { type: string, minLength: 1, required: true }email: { type: string, format: email }enabled: { type: boolean, default: false }Her yaprak tek satırdır. Kısıt sözlüğü alanın biçimine ilişkin her şeyi kapsar; üst düğümün yapısı ise alanın konumunu belirler.
İç içe nesneler
Nesne yapısı YAML iç içeliğini yansıtır. Derin iç içelik doğrudan çalışır ve her yaprak yine tek satırda kalır:
spec: schema: architecture: { type: string, enum: [standalone, replication], default: standalone } primary: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" } limits: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "500m" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "1Gi" } auth: username: { type: string, default: app_user } password: { type: string, sensitive: true }Derleyici, nesne yapısını YAML hiyerarşisinden çıkarır. Ara düğümler (burada: primary, resources, requests, limits, auth) iç içe alt öğeleri içeren nesne türleridir. Derleyici, çözümlenmiş JSON Schema’da açık type: object ve properties: blokları üretir; yazar bunları yazmaz.
Çıkarımlı ve açık nesne biçimi
Kompakt biçimli bir nesne kapsamı iki şekilde yazılabilir:
Çıkarımlı biçim — alt öğeler doğrudan üst anahtarın altında, type: object bildirimi olmadan:
auth: username: { type: string, default: app_user } password: { type: string, sensitive: true, required: true }Derleyici, alt öğeleri özellik bildirimleri olduğu için kapsamı bir nesne olarak tanır. type: object, properties: { ... } üretir ve derleme zamanında additionalProperties: false değerini otomatik olarak ekler. Kapalılık semantiği çıkarımlı biçim sözleşmesinin bir parçasıdır: geliştiricinin yazdığı alanlardaki yazım hataları açıkça hata verir.
Açık biçim — type: object bildirilir, properties: listelenir:
auth: type: object properties: username: { type: string, default: app_user } password: { type: string, sensitive: true } required: [password] additionalProperties: true # genuinely-open map authored on purposeDerleyici, açık biçimde additionalProperties: false EKLEMEZ. type: object bildiren yazarlar kapalılık kararının tüm sorumluluğunu üstlenir; açık biçim, gerçekten açık eşlemeler (additionalProperties: true) ve başka JSON Schema anahtar sözcüklerine (patternProperties, propertyNames, unevaluatedProperties) ihtiyaç duyan nesneler için kullanılan yüzeydir.
Yazım ölçütü: sıradan kapalı nesneler için (katalog şemalarında yaygın durum) çıkarımlı biçimi kullanın. Nesnenin gerçekten açık olması gerektiğinde veya şema, kompakt biçimin doğrudan taşımadığı JSON Schema anahtar sözcüklerini gerektirdiğinde açık biçimi kullanın.
Kapalılık semantiği
Uzlaşım gereği, compact form’daki çıkarımsal biçim nesneleri kapalıdır: bildirilmemiş özellikler bir doğrulama hatası üretir. Derleyici, her çıkarımsal biçim nesne kapsamına additionalProperties: false değerini otomatik olarak yazar. Bu, yazım hatalarının açıkça başarısız olduğu katalog disipliniyle örtüşür.
Bir nesneyi açmak için (rastgele ek özelliklere izin vererek), açık biçimi additionalProperties: true ile kullanın:
labels: type: object additionalProperties: true # opt-in; allow any string-keyed valuesYaygın “tüm değerleri aynı türü paylaşan nesne” kalıbı için (ör. etiketler için string → string eşlemesi), valuesType: kullanın:
labels: { type: object, valuesType: string }nodeSelector: { type: object, valuesType: string }counters: { type: object, valuesType: integer }valuesType: <type>, additionalProperties: { type: <type> } olarak derlenir. Tek anahtar sözcüklü bir kısaltmayı hak edecek kadar sık görülen bir kalıptır.
Yukarıdaki yalın tür adı, schema: ve SchemaLibrary yazımıdır. Bir Aggregate parameters: yuvasında ise değeri bunun yerine bir sözleşme olarak yazın — valuesType: { type: string }. Aynısı, değeri kendisi bir sözleşme olan diğer iki anahtar sözcük için de geçerlidir: items: ve properties: altındaki her girdi; çünkü bir parametre bildirimi ve onun içine yerleştirilmiş her sözleşme tek bir şekil taşır. Bir parametre yuvasında bu üç konumdan herhangi birindeki yalın tür adı reddedilir ve tanılama, onu hangi iç içe sözleşmenin taşıdığını belirtir. Parametre yuvası sözcük dağarcığının tamamı için bkz. entities/aggregate.md.
Zorunlu alanlar
Zorunlu alanlar, her yaprakta required: true kullanır:
auth: username: { type: string, default: app_user } password: { type: string, sensitive: true, required: true } database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }Derleyici, bir nesne kapsamı içindeki tüm required: true işaretlerini toplar ve bunları JSON Schema’nın required: [field1, field2] dizisi olarak üretir. İşaret, özelliğin bildirildiği her yerde geçerlidir: çıkarımlı biçimdeki bir kapsamda ve açık bir properties: bloğu içindeki bir özellikte.
Bir SchemaLibrary girdisini $ref: aracılığıyla kendi şemasına çeken bir tüketici, zorunlu alanlarını iki yoldan biriyle belirtebilir — başvurunun yanında üst düzeyde bir required: [name1, name2] dizisiyle ya da orada properties: altında bildirdiği bir özellikte required: true işaretiyle. Kuralın tamamı için cross-document-ref.md §“Belgeler arası $ref: altında required: sözdizimi” bölümüne bakın.
Diziler
Diziler, öğe biçimini tanımlayan items: ile birlikte type: array kullanır:
tags: { type: array, items: { type: string } }
ports: { type: array, items: { type: integer, min: 1, max: 65535 } }
extraEnvVars: type: array items: name: { type: string, required: true } value: { type: string } valueFrom: { type: object, additionalProperties: true }
allowedHosts: type: array min: 1 # minItems max: 100 # maxItems items: { type: string, format: hostname }Yaygın durum olan “türü belirli skalerlerden oluşan dizi” için satır içi biçim tek satırdır. Nesne dizilerinde items:, iç içe bir kompakt biçimli şema tanımlar.
type: anahtar sözcüğü — skaler ya da tür dizisi
type: tek bir değer (type: string) ya da izin verilen türlerden oluşan bir dizi (type: [string, integer, boolean]) kabul eder. Dizi biçimi, JSON Schema 2020-12’nin “bu alan birkaç türden birini kabul eder” anlamına gelen standart ifadesidir:
release_tier: { type: [string, integer], description: "Numeric tier or named tag" }type: bir dizi taşıdığında değer uzayı, adı verilen türlerin değer uzaylarının birleşimidir. Dizi biçimini tüketen şemalar yazan yazarlar her iki biçimi de sonraki aşamalarda ele almalıdır — çözümlenmiş JSON Schema’nın type alanı ya bir dize ya da bir dizi tutar ve çözümlenmiş şemayı dolaşan tüketiciler her iki biçimi de denetler.
Her çıkarımlı biçim kapsamında ayrılmış anahtar sözcükler
Çıkarımlı biçim yönlendirmesi, kompakt biçim sözcük dağarcığı düzeyinde anlam taşıyan küçük bir anahtar sözcük kümesini tanır: description, type, default, required, kısıt anahtar sözcükleri (enum, const, min, max, pattern, format vb.) ve Aggrega’ya özgü anahtar sözcükler (validate, validateMessage, when, sensitive). Bu anahtar sözcüklerden herhangi biri çıkarımlı biçimdeki bir nesne kapsamında alan adı olarak geçtiğinde derleyici, çevreleyen kapsamı bir nesne olarak değil, bir kısıt yaprağı olarak okur: anahtar sözcük bir alt özellik olarak değil, bir kısıt olarak alınır ve o kapsamdaki diğer her anahtarın da bir anahtar sözcük olması gerekir; böylece anahtar sözcük olmayan ilk anahtar, bilinmeyen bir anahtar sözcük olarak reddedilir.
sensitive burada özellikle anılmayı hak eder, çünkü gerçek bir geliştiricinin yazdığı bir alan için diğer Aggrega’ya özgü anahtar sözcüklerden çok daha olası bir addır. Gerçekten sensitive adlı bir özelliğe ihtiyaç duyan bir şema — örneğin values değerleri kendine ait bir sensitive bayrağı sunan bir bileşen — çevreleyen kapsamı, type veya default adlı bir özellik için yapacağı gibi tam olarak açıkça bildirmelidir. Bunu aşağıdaki açık biçim ya da çevreleyen kapsamdaki $mode: jsonschema sağlar: $mode: jsonschema altında düğümün tamamı yazıldığı haliyle JSON Schema olarak okunur ve burada sensitive kompakt biçim anahtar sözcüğü değil, sıradan içeriktir.
Ayrılmış bir anahtar sözcükle adlandırılmış bir özelliğe ihtiyaç duyan şemalar için (örneğin geliştiricinin yazdığı bir description: alanı, bir type: alanı ya da bir default: alanı olan bir Component sözleşmesi), sorunlu kapsam için açık biçimi kullanın:
spec: schema: values: type: object properties: description: { type: string } # property named "description" type: { type: string } # property named "type" default: { type: string } # property named "default" required: [description, type] additionalProperties: falseAçık biçim yönlendirmeyi atlar — properties: alt öğeleri açıkça sıralar, bu nedenle anahtar sözcük çakışması oluşmaz.
Bu kısıt, her çıkarımlı biçim kapsamında özyinelemeli olarak geçerlidir. Ayrılmış bir anahtar sözcükle adlandırılmış bir özellik içeren iç içe çıkarımlı biçimdeki bir nesne, o kapsamda bir kısıt yaprağı olarak okunur. Çözüm aynıdır: sorunlu kapsamı açık biçime geçirin.
Referanslar
Referanslar, JSON Schema’nın $ref: yapısını sözdizimsel ve anlamsal olarak ödünç alır:
resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 }Bir compact-form şema içindeki $defs: blokları yeniden kullanılabilir tanımlar bildirir. Her girdi kendisi de bir compact-form (ya da JSON Schema veya karma) şemadır. Referans, #/$defs/<Name> JSON Pointer parçasıyla verilir:
Bloğu, alanları ona referans veren sütunun içinde bildirin; sütunun yanında değil, o alanların yanında. Bir schema: bloğu kendi üst düzeyinde yalnızca üç veri sütunu adını kabul eder; bu nedenle values: ile kardeş olarak yazılmış bir $defs:, varlık yüklenirken reddedilir ve hata, sorunlu anahtarı ve bu bloğun içerebileceği sütun kümesini belirtir. İşaretçi her iki durumda da #/$defs/<Name> olarak yazılır.
$defs: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" } limits: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
primary: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: { $ref: "#/$defs/PodResources" }SchemaLibrary girdilerini hedefleyen belgeler arası referanslar için cross-document-ref.md sayfasına bakın. OCI URI kısaltmasının genişletilmesi için uri-grammar.md sayfasına bakın.
Referansı bir özelliğe değil, bir tanıma yöneltin
Bir $defs: girdisini adlandıran işaretçi (#/$defs/PodResources) tercih edilmesi gereken biçimdir. İşaretçi,
JSON Schema’nın izin verdiği her yerde geçerlidir; bu nedenle bildirilmiş bir özelliğin içine yönelen işaretçi de kabul edilir ve uygulanır,
ancak daha az kesin biçimde raporlanır ve bu farkı işaretçiyi yazmadan önce bilmekte yarar vardır.
Biçimi bir $defs: girdisinden gelen alan, alan alan denetlenir: bir hata, gerçekten yanlış olan değerin
yolunda raporlanır ve o alanın altındaki yalnızca ilk hata değil,
tüm hatalar raporlanır.
$defs: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary: resources: { $ref: "#/$defs/PodResources" }Burada hatalı bir cpu, primary.resources.requests.cpu yolunda raporlanır.
Biçimi bildirilmiş bir özelliğin içine yönelen bir işaretçiden gelen alan, belgenin bütününün parçası olarak denetlenir. Kısıtlar yine geçerlidir ve bunları ihlal eden belge yine durdurulur; ancak hata onun içindeki değerde değil, işaretçiyi taşıyan alanda raporlanır ve bu türden birkaç alan aynı anda yanlışsa yalnızca biri belirtilir.
primary: resources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary: resources: { $ref: "#/properties/primary/properties/resources" }secondary altındaki hatalı bir cpu, secondary.resources yolunda raporlanır.
İki yazım biçimi de aynı belgeleri kabul eder ve reddeder; tek istisna,
Adlandırılmış biçimler bölümünde belirtilen format sınırıdır: işaretçi üzerinden, biçimin bir anyOf, oneOf ya da not
dalı içindeki format denetlenmez. Bunun dışında fark, mesajın size
ne kadar bilgi verdiğidir; bu en çok, işaretin o yola göre yerleştirildiği bir düzenleyicide önem taşır. Aynısı,
kendi işaretçisi dışarıya, özelliklere uzanan bir $defs: girdisi için de geçerlidir: bir tanıma
bu işaretçi üzerinden ulaşmak, daha kaba raporu devralır.
when: ile koşullu şekil
JSON Schema 2020-12, koşullu şekli if/then/else ile ifade eder. Kompakt biçim, daha doğrudan bir kısaltma olarak when: sağlar: doğruysa düğümün diğer kısıtlarını uygulayan, yanlışsa düğümü kısıtları hiç yokmuş gibi ele alan bir Go şablonu yüklemi.
secondary: $ref: "#/$defs/NodePool" when: '{{ eq $.architecture "replication" }}' required: true properties: replicaCount: { type: integer, min: 2 }Yüklem, üst öğenin örnek değerlerine karşı değerlendirilir. $, çevreleyen nesne kapsamını belirtir. architecture değeri replication olduğunda kısıtlar (required: true ve ek replicaCount: min: 2) başvurulan NodePool üzerine uygulanır. architecture değeri standalone olduğunda bu kısıtlar etkin değildir.
Yüklem, standart Go şablonu işlevlerine (Sprig) erişebilir. Derleyici when: yapısını JSON Schema’nın if/then/else yapısına ve Go şablonu yüklemini doğrulama çalışmadan önce değerlendiren bir sarmalayıcıya derler. Yüklem örneğe göre saf olduğundan belirlenimcilik korunur.
validate: ve validateMessage: ile alan başına özel doğrulama
Bazı kısıtlar min / max / pattern / enum ile ifade edilemez. Bunlar için kompakt biçim validate: sağlar: yanlış olduğunda doğrulamayı özel bir hatayla durduran bir Go şablonu yüklemi.
db_size: type: string pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$" validate: '{{ regexFind "^[0-9]+" . | atoi | lt 100 }}' validateMessage: "db_size must exceed 100 in its declared unit"Yüklem, alanın değeri üzerinde çalışır (. olarak erişilebilir); çevreleyen nesne kapsamı $’dır. Yüklem false döndürürse doğrulama, validateMessage: kullanarak (verilmemişse varsayılan bir iletiyle) bir hata üretir.
validate:, JSON Schema’nın standart sözcük dağarcığının ötesindeki durumları ele alır: özel anlamsal doğrulama (semver biçimi denetimi, bir dizenin JSON içeriği), bir alanın kısıtının bir kardeş alana bağlı olduğu, alanlar arası ama dar kapsamlı kurallar ve tam bir assertions: bloğuna değmeyecek kısıtlar.
validate:, rol bakımından when:’den farklıdır: when: kısıtların uygulanıp uygulanmayacağını değiştirir; validate: ise kendisi bir kısıttır.
Hiçbir tek alanın “doğrulanan alan” olmadığı, gerçekten alanlar arası ve geniş kapsamlı kurallar için özel assertions: bloğunu kullanın. Bkz. templates/assertions-block.md.
Bir yaprağı hassas olarak bildirmek — sensitive:
Bir values, infra veya provides yaprağı, tanımladığı verinin gizli malzeme taşıdığını bildirebilir:
spec: schema: values: origin: type: string required: true sensitive: true description: "The credential material itself." key: type: string default: value description: "The data key the material is stored under."sensitive: true, çözümlenmiş JSON Schema’da o düğüm üzerinde, diğer x-aggrega-* ek açıklamalarının yanında x-aggrega-sensitive: true uzantı anahtar sözcüğüne derlenir. Derleyici, bir dağıtımdaki hangi eklentilerin hassas olarak bildirilmiş malzemeyi işlediğini türetmek için bunu okur ve türetilen bu bilgiyi derlenmiş grafikte taşır.
Bunu konum belirleyicisine değil, verinin kendisine bildirin. Bu ayrım anahtar sözcüğün asıl amacıdır ve tersine çevirmek kolaydır. Bir kimlik bilgisinin malzemesi hassastır; onu tutan kaynağın adı ve o kaynaktaki veri anahtarı ise hassas değildir — ikisi de herkese açıktır ve ikisi de kaynağa başvuran her tüketiciye açık metin olarak işlenir. Bir konum belirleyicisini işaretlemek onun hakkında doğru olmayan bir şey söyler ve bu hatayı bildirimi okuyan aşağı akıştaki her şeye yayar. Yukarıdaki örnekte origin işaretlenmiştir, key ise bilerek işaretlenmemiştir.
Tamamlayıcı ifade — dolgunun kendi yaprakları hakkında ne bildirdiğinden bağımsız olarak bu noktaya bağlanan her şey gizli malzeme işler — hiç de bir yaprak bildirimi değildir. Bu, bir eklenti yuvası üzerindeki sensitive anahtarıdır; bkz. entities/component.md “Attachment Slots”.
Bütün bir nesneyi hassas olarak bildirmek
Anahtar sözcük bir skaler yerine bir nesne üzerinde de bulunabilir ve bu durumda o nesnenin altındaki her şeyi kapsar — nesnenin kendi alt öğelerini ve daha derinde iç içe geçmiş her şeyi. Bütün bir blok malzeme olduğunda ve her yaprağı ayrı ayrı işaretlemek birinin eklediği bir sonraki yaprağı işaretsiz bırakacağında başvurulacak bildirim budur.
Nesnenin alt öğeleri açık bir properties: bloğunda bulunmalıdır. Çıkarımlı nesne biçiminin işe yaramadığı tek yer burasıdır ve nedeni, etrafından dolaşmak yerine bilinmeye değerdir:
spec: schema: values: credentials: type: object sensitive: true properties: # required here username: { type: string } password: { type: string }Alt öğeleri, çıkarımlı nesne biçiminin diğer her yerde izin verdiği şekilde doğrudan işaretçinin yanına yazmak derleme zamanında reddedilir — ilk alt öğe, alt öğenin kendi anahtarı üzerinde konumlandırılarak bilinmeyen bir anahtar sözcük olarak raporlanır:
values: credentials: type: object sensitive: true password: # refused: unknown keyword "password" type: stringBu ret, etrafından dolaşılacak bir sınırlama değil, doğru bir davranıştır. Bir düğüm, bir kompakt biçim anahtar sözcüğü taşıdığı anda bir kısıt yaprağı olarak okunur ve sensitive: da bunlardan biridir — dolayısıyla o noktadan itibaren her kardeş anahtar da bir anahtar sözcük olmalıdır ve password bir anahtar sözcük değildir. properties: bloğu, “aşağıdaki anahtarlar başka anahtar sözcükler değil, özellik adlarıdır” diyen şeydir ve Çıkarımlı ve açık nesne biçimi bölümünün anlattığı belirsizlik gidermenin aynısıdır. Tanılamayı “işaretçi bir nesneye konamaz” şeklinde okumak kaçınılması gereken yanlış okumadır: konabilir ve blok bunu söylemenin yoludur.
Bildirilmiş bir nesnenin içindeki bir yaprağın kendi işaretçisine ihtiyacı yoktur. Bir işaretçi eklemek zararsızdır ve yeni bir şey söylemez, çünkü nesnenin bildirimi onu zaten kapsar.
Anahtar sözcüğün yapmadıkları
Ad, anahtar sözcüğün karşılamadığı varsayımlara davetiye çıkarır; bu nedenle sınırı açıkça belirtelim:
- Hiçbir şeyi şifrelemez. Bir gizlilik mekanizması değil, bir bildirim üzerindeki ek açıklamadır.
- Bir CloudFormation şablonunun parametrelerinin doldurulduğu durum dışında doğrulama veya reddetme yapmaz. Bir yaprak hassas olarak bildirildiği için hiçbir değer kabul edilmez veya reddedilmez ve hiçbir derleme sonucu değişmez — ancak bir CloudFormation Recipe’inin veya FeatureRecipe’inin
valuesMappingöğesi, kaynaklı bir şablonun parametrelerini doldurmak için hassas olarak bildirilmiş bir yaprağı okuduğunda, o eşlemenin bağladığı her sabit değer derlemeyi durdurur; bu nedenle yalnızca bildirimle farklılaşan iki derleme farklı sonuçlanabilir. Bkz. A secret bound to a CloudFormation parameter would be written into the template (Bir CloudFormation parametresine bağlanan bir gizli bilgi şablona yazılırdı). - İşlenmiş çıktının malzemeden arınmış olduğunu garanti etmez. Bir yapıtın malzeme taşıyıp taşımadığı, yazarın hangi dolguyu eklediğine ve yazarın onun
valuesalanına ne yazdığına bağlıdır — bkz. architecture/08-credential-model.md “What the compiler does and does not guarantee”. Yazarın satır içi sağladığı, hassas olarak bildirilmiş bir değer, derleme onu nerede işliyorsa orada, bildirilmemiş bir değerle tam olarak aynı şekilde işlenir. - Bir teslim mekanizmasını zorunlu kılmaz. Satır içi bir değeri bir depo başvurusuna dönüştüremez ve bir yuvanın
injectizin listesinin izin verdiklerini daraltmaz. - O CloudFormation reddi dışında bir derlemeyi durdurmaz. Aşağıda açıklanan, derleme zamanında verdiği bildirimler tavsiye niteliğindedir: derleme tamamlanana kadar çalışır ve yapıtlarını yazar. Bir bildirimi ölümcül hâle getirmek, derlemeye eklenen bir yönetişim politikasıyla ifade edilen bir kuruluş tercihidir; anahtar sözcüğün kendi başına yaptığı bir şey değildir. Yukarıdaki CloudFormation sağlayıcısının reddi istisnadır: derlemeyi durdurur, çünkü bir şablona yazılan sabit değer yığını okuyabilen herkes tarafından okunabilir.
- Çoğu hedefte işlenmiş hiçbir baytı değiştirmez ve bu hedeflerde hiçbir zaman değiştirmeyecektir. Kendine ait bir hassasiyet kavramı taşıyan bir hedef platform, bir bildirimin yerleşebileceği bir yerdir; böyle bir kavramı olmayan bir hedefte bildirimin değiştireceği hiçbir şey yoktur, kalıcı olarak. Terraform, böyle bir ilkel taşıyan tek standart kitaplık hedefidir: tedarik edilmiş bir modülün girdisi, yazarın hassas olarak bildirdiği malzemeyi aldığında, işlenmiş çıktıya o girdi için Terraform’un kendi hassasiyet özniteliğini belirten, üretilmiş bir geçersiz kılma dosyası eklenir — bkz. providers/terraform.md “Declared-sensitive module inputs”. Diğer her yerde, mevcut bir katalog genelinde bir yaprağı hassas olarak bildirmek işlenmiş her yapıtı aynı bırakır.
Aracın yazdırdıklarında neyi değiştirir
Bir bildirimin gerçekten değiştirdiği tek şey, aracın bir insanın okuması için yazdırdıklarıdır: hata ayıklama çıktısı ve aşağıda açıklanan bir reddin metni. Hata ayıklama yüzeylerinde hassas olarak bildirilmiş bir değer <redacted> sabit metniyle değiştirilir:
aggrega build --tracekomutunun.trace/dizinine yazdığı geçiş başına iz;aggrega inspectkomutunun bir Aggregate için yazdırdığı düğüm başınaValues:bloğu;aggrega inspectkomutunun çözümlenmiş bir Release için yazdırdığı yaprak başına eklenti bloğu.
Anahtar her zaman korunur ve yalnızca değeri değiştirilir; böylece okuyucu yaprağın yazıldığını ve bir şeyin gizlendiğini yine de görür. Yazarın bildirmediği bir yaprak, gizlenen bir kardeşinin yanında değerini olduğu gibi yazdırır — değiştirme yalnızca bildirimi izler; bu nedenle bildirim taşımayan password adlı bir alan yazdırılır, bildirilmiş key adlı bir alan ise yazdırılmaz.
Bir bildirim altındaki her yaprağa ulaşır ve üç yüzeyin hepsine aynı şekilde ulaşır. Bildirim bir nesne üzerinde olduğunda, o nesnenin içinde iç içe geçmiş her değer de, hangi derinlikte olursa olsun gizlenir — nesnenin bildirimi onları adlandırır, dolayısıyla onları gizlemek yazarın yazmadığı hiçbir şeyi öne sürmez. Eşleşme metin üzerinde değil tam yol bölümleri üzerinde yapılır; bu nedenle adı yalnızca bildirilmiş bir adla başlayan bir kardeşe dokunulmaz: dbPassword bildirmek dbPasswordHint öğesini gizlemez.
İzin gizlemesi, gizlenen değer hata ayıklanan değer olduğunda tek bir derleme için kapatılabilir: aggrega build --trace --trace-unredacted değerleri iz dosyalarına yazar ve bu dosyaların her birini bunu belirten bir üst bilgiyle işaretler. Bu, hiçbir yapılandırma ayarı olmayan, çağrı zamanında yapılan bir seçimdir; yalnızca ize ulaşır ve cli/aggrega-build.md “Showing the withheld values” bölümünde belgelenmiştir. aggrega inspect düzenlerinin kendi seçeneği, --unredacted, vardır ve cli/aggrega-inspect.md “Showing the withheld values” bölümünde belgelenmiştir.
Bu davranışın sınırları, davranışın kendisinden daha önemlidir.
İşlenmiş yapıtlar hiçbir zaman sansürlenmez. dist/ altındaki her şey, işlemenin ürettiği haliyle aynen yazılır, çünkü dağıtılabilir olan budur: bir manifest içine yazılmış bir yer tutucu, korunan bir dağıtım değil bozuk bir dağıtım olurdu. Sansürleme, aracın yazdırdığı şeyleri kapsar, hiçbir zaman diske yazdığı şeyleri kapsamaz. Bir bildirimi dist/ dizininin yayımlanmasının güvenli olduğuna dair bir söz olarak okumak, kaçınılması gereken tek yanlış okumadır — yukarıdaki sınır değişmez ve dist/, en çok gizli malzeme taşıyan eki kadar hassas kalır.
Bir bildirimin işlenmiş bir yapıta ekleyebileceği bir şey vardır ve bu sansürleme değildir: bir hedefin kendine ait bir hassasiyet temel öğesi olduğunda, bildirim bu öğeye işlenir. Değer yine tam olarak yazılır — hiçbir şey saklanmaz ya da değiştirilmez — ve yapıtın kazandığı şey, değerin yanında hedefin kendi işaretlemesidir; böylece hedefin araçları değeri yazarın bildirdiği gibi ele alabilir. Bugün bunu sunan hedef Terraform’dur; özniteliğinin neyi garanti ettiği ve etmediği providers/terraform.md “Declared-sensitive module inputs” bölümündedir. Böyle bir işaretleme yalnızca işlenmiş adın kimliğinin bildirimin kendisinden geri kazanıldığı yerlere taşınır; adı bir şablonun uydurduğu yerde işaretleme yaklaşık olarak konmaz, hiç bulunmaz, çünkü yazarın bildirmediği bir değeri işaretlemek o değer hakkında yanlış bir şey ileri sürmek olurdu. Bu şablon bir valuesMapping olduğunda — bir Recipe’in ya da bir bileşene eklenmiş bir Feature’ın FeatureRecipe’inin — derleme, aşağıda anlatıldığı gibi bunu bildirir.
Sansürleme, bir bildirimin adlandırdığı şeylere ve bir şablonun okuduğu görülen şeylere ulaşır. Bir values ya da infra sütunundaki bildirilmiş bir yaprak ve hassas olarak bildirilmiş bir provides anahtarından malzeme taşıyan bir teslim anahtarı, her ikisi de adlarıyla tanımlanır ve saklanır. Bir şablonun hesapladığı değer kimsenin bildirmediği bir anahtarın altına düşer; bu yüzden onu tanımlayan, yazarın yazdığı referanstır: izde, şablonu hassas olarak bildirilmiş bir yaprağı okuyan bir locals: girdisi ya da source: alanı saklanır; zaten saklanmış bir kardeşi okuyan bir locals: girdisi de saklanır. Bu okuma bilinçli olarak temkinlidir — bütün bir nesneye ulaşmak, altındaki her bildirilmiş yaprağa ulaşır ve verisinin tamamını aktaran bir şablon hepsine ulaşır — bu yüzden çözümlenemeyen bir referans yazdırmak yerine saklar.
İşlenmiş bir belge yeniden işleme olarak gösterilir ve bunu belirtir. İzin ayrıştırılmış Workload’u, Recipe’in şablonunun ürettiği bir belgedir: içindeki hiçbir şey her karakterin hangi bildirimden geldiğini kaydetmez; bu yüzden içinde yerine koyma yapılacak bir anahtar yoktur ve bağlantıyı alan alan geri kazanmak bir değerin içeriğini incelemek anlamına gelir — derleyici bunu yapmaz. İzin bunun yerine gösterdiği, aynı workload: şablonunun, hassas olarak bildirilmiş verisi zaten yerine koyma metni olarak okunan bir bağlama karşı yeniden değerlendirilmesidir; bu, belgenin yanındaki bir workload_note girdisinde duyurulur. Şablon bir dizenin bulunduğu yerde yine bir dize gördüğü için, yeniden işleme yazılan belgenin biçimini korur ve yerine koyma metni saklanan verinin kendi konumunda durur. İki fark kalır ve not ikisini de belirtir: bir değerin içeriğine göre dallanan bir şablon, yerine koyma metnine karşı farklı işler ve eksenin adlandırmadığı bir veri değişmeden taşınır. Bu, işlenenin bir hata ayıklama görünümüdür, hiçbir zaman onun bir kopyası değildir.
Tüketilen bir düğümün değerleri, kenarın onları taşıdığı her iki yüzeyde de o düğümün bildirimlerine göre saklanır. Bir uses kenarı görünümü, hedef bileşenin yayımladığını yeniden üretir; bu yüzden onu hedefin kendi şeması yönetir: hedefin hassas olarak bildirdiği bir provides anahtarı, tüketici hiçbir şey bildirmese bile tüketicinin izinde saklanır. Kenarın kendi inject bloğu bu anahtarı tüketen bileşenin bir teslim anahtarına yönlendirdiğinde, o teslim anahtarı da saklanır — bu, bir ekin inject eşlemesinin izlediği, aynı bildirimi okuyan kuralla aynıdır; böylece iki bağlantı birbiriyle çelişemez. aggrega inspect düzenleri, tüketilen bir düğümün yayımlanmış değerlerini değil, bir düğümün kendi sütunlarını ve eklerini gösterir; bu yüzden orada saklanacak düğümler arası bir görünüm yoktur.
Bir bağlantı üzerine yazılmış bir ek, onu gösteren her yüzeyde kendi Feature’ının bildirimlerine göre saklanır. İz onu o bağlantının uses kenarı görünümü altında, .context.uses.<alias>.features.<slot> konumunda gösterir; aggrega inspect ise onu çözümlenmiş bir Release’te bağlantının satırının altında yazdırır. Her ikisinde de Feature’ının hassas olarak bildirdiği bir values ya da infra yaprağı, aynı Feature bileşene doğrudan eklendiğinde olduğu gibi aynen saklanır; izde ayrıca ekin çözümlenmiş provides değerinin, Feature’ın hassas olarak bildirdiği bir anahtarı da saklanır. Türü, sürümü, etiketleri ve bildirilmemiş her yaprak ve provides anahtarı aynen yazdırılır; böylece yayımlanmış bir konum belirteci, konumunu belirttiği malzemenin yanında okunabilir kalır. Bileşen üzerinde ya da bir soket üzerinde sensitive: true bildiren bir yuva, eki gizli malzeme işleyen olarak işaretler ve kendiliğinden hiçbir yaprağı saklamaz — hangi yaprakların saklanacağını bildirmek Feature’a düşer.
Makine tarafından okunabilen izdüşümler sözleşme gereği birebirdir ve geldikleri dosyalarla aynı özeni gerektirir. aggrega inspect --raw bir varlığı tam yazıldığı gibi çıkarır; aggrega inspect --output yaml ise bir Release dahil her tür için yazılmış varlığı yeniden üretir. İkisi de hiçbir şeyi yerine koymaz ve bu bilinçlidir: bunlar bir betiğin ayrıştırdığı ve bir diff’in karşılaştırdığı çıktılardır; bu yüzden kendisinin bir kısmını sessizce saklayan bir çıktı, yeniden ürettiğini ileri sürdüğü girdiyi yanlış temsil eder ve tüketicilerinin dayandığı gidiş-dönüşü bozar. Bir yaprağı hassas olarak bildirmek, onu bu çıktıların dışında tutmaya yetmez: bunları, Aggregate’i ve Release’i nasıl aktarıyor, saklıyor ve paylaşıyorsanız öyle aktarın, saklayın ve paylaşın.
Derlenmiş çizge, nerede verilirse verilsin saklama yapan tek makine tarafından okunabilen izdüşümdür. aggrega inspect, aggrega validate ve aggrega build üzerindeki --ir-graph, çalıştırmanın çözümlediği çizgeyi, komutun zaten ürettiği her şeyin yanında JSON olarak yazar; arka plan hizmetinin aggrega/irGraph yöntemi de bir düzenleyiciye aynı çizgeyle yanıt verir; her birinde, bir yazarın hassas olarak bildirdiği bir değer, okunabilir düzenlerde olduğu gibi aynen yerine konur. --ir-graph yanında --unredacted bunun yerine bu değerleri yazdırır; arka plan hizmetinin isteğindeki unredacted alanı da öyle. Böylece bir komuttan okunan çizge ile arka plan hizmetinin protokolü üzerinden okunan çizge, aynı işleme kuralı altındaki aynı belgedir ve yazılmış değerlere ihtiyaç duyan bir işlem hattı ya da istemci bunları istemek zorundadır.
Bir reddin bildirilmiş bir değer hakkında söyledikleri
Bir yazarın hassas olarak bildirdiği bir değeri okuyan bir şablonun ortaya çıkardığı ret, o değeri taşımaz. Bir şablon derlemeyi durdurduğunda — fail çağıran bir doğrulama, değerlendirilemeyen bir ifade, şablonun üretmesi gereken belge olarak okunamayan bir çıktı — ve başvurularından biri hassas olarak bildirilmiş bir veriye ulaştığında, bildirilen sonuç aynı şablonun ikinci kez, hassas olarak bildirilmiş her verinin zaten <redacted> olarak okunduğu bir bağlama karşı değerlendirilmesinden gelir — şablon kendisinin açıkça yazdığı bir cümlede durmadıysa; o durum aşağıdaki ilk durumdur:
assertion failed: the admin password <redacted> must be supplied as a reference- Cümlesi şablonda açıkça yazılmış bir
fail, yazıldığı gibi bildirilir. Derlemeyi durduran çağrı, tırnak içinde tek bir dize verilmişfailolduğunda —fail "…", içine hiçbir şey aktarılmadan ve cümlesine hiçbir şey eklenmeden — ret, değer ne içerirse içersin ve çağrıya hangi dal yol açarsa açsın o cümleyi taşır, çünkü cümle şablonun okuduğu hiçbir şeyi alıntılamaz: yanlış biçimdeki bir kaynağı reddeden bir doğrulama, biçime ilişkin kendi açıklamasını gösterir. Başka herhangi bir şekilde oluşturulan bir cümle —printf, bir alan, bir değişken,fail’e aktarılan bir değer — aşağıdaki durumlara göre bildirilir. - İkinci değerlendirme aynı ifadede aynı nedenle başarısız olursa, bildirilen başarısızlık odur. Yazarın kendi cümlesi, değerin bulunduğu yerde
<redacted>ile korunur; şablonun kodladığı, tırnak içine aldığı ya da başka biçimde dönüştürdüğü bir değer de gizlenir, çünkü değiştirme dönüştürmeden önce gerçekleşir. - Başarısız olmazsa, ret başarısız olan ifadeyi adlandırır ve metninin gizlendiğini belirtir. Bu, davranışı değerin içeriğine bağlı olan bir şablondur — yerine konan metne karşı başka bir dala girmiş ya da başka bir yerde başarısız olmuştur — bu yüzden oluşturduğu hiçbir şey gösterilemez. Böyle bir retin kendini açıklamasını sağlamak için, ilk durumun anlattığı gibi cümlesini
failçağrısında açıkça yazın. Ret yine de derlemeyi durdurur ve kodunu korur. - Workload şemasının reddettiği, işlenmiş bir Workload şemaya göre ifade edilir. Belgenin alanları, şablonunun okuduğu verilere geri bağlantı taşımaz; bu nedenle o şablon hassas olarak bildirilmiş bir veriyi okuduğunda, bir değeri alıntılayabilecek her bulgu bunun yerine kısıtı belirtir, değerin yerinde
<redacted>ve nedenini açıklayan bir bildirim bulunur. Değerden türetilen hiçbir öneri verilmez; değer alıntılamayan bir bulgu — eksik bir anahtar, Workload’un kabul etmediği bir anahtar — her zamanki gibi okunur:
.containers.main.imagePullPolicy: against /$defs/container: enum: <redacted> does not satisfy enum ["Always","Never","IfNotPresent"] (the value is withheld because the template that rendered this document reads a value declared sensitive)- Bir pipeline adımının, adımın bildirilmiş girdi sözleşmesince reddedilen
withgirdisi, sözleşmeye göre ifade edilir; bu,withşablonu hassas olarak bildirilmiş bir veriyi okuduğunda geçerlidir: girdideki başarısız her konum ve onu reddeden şema anahtar sözcüğü, ardından nedenini açıklayan bir bildirim gelir; girdinin taşıdığı hiçbir şey yer almaz. - Bir
source:koordinatını adlandıran ret, hiçbir bildirimin üretmediği şeylere göre ifade edilir; bu, birsource:şablonu o koordinatı hassas olarak bildirilmiş bir veriyi okuyarak ürettiğinde geçerlidir — kaynak lockfile’da ya da önbellekte yoktur, önbellekteki arşivi lockfile’ın kaydettiğiyle eşleşmez ya da varlığın yanında kaydedilen sabitleme lockfile ile uyuşmaz. Böyle bir reddin yazdırdığı her satır, aramanın kullandığı koordinatları adlandırır; bu yüzden kaynağı url’si ve istendiği sürüm ya da referansla — bunları okuduğu yerde — adlandırır, böyle bir şablonun ürettiği her birinin yerinde<redacted>bulunur ve nedeninin gizlendiğini belirtir. Kodunu ve derlemenin o kod için verdiği düzeltme önerisini korur:
source-artifact https://example.com/fragments/app.yaml@<redacted>: the reason is withheld: the template producing this source reads a value declared sensitive, and the reason names what the template producedBildirilmiş sayılan, bildirimlerin adlandırdığı şeydir; bu, bir şablonun okuyabileceği bağlamın her bölümünde geçerlidir: bileşenin kendi values ve infra alanları, ona ve bağlantılarının her birine eklenmiş Features, bildirilmiş materyal taşıyan bir teslim anahtarı, Component’inin hassas olarak bildirdiği bir provides anahtarı, aşağıda açıklandığı gibi bağlamın taşıdığı bir listenin her girdisi ve bunlardan herhangi birinden hesaplanan bir locals: girdisi. Bunların hiçbirini okumayan bir şablon, hiçbir yerde bildirim yokmuş gibi, bayt bayt aynı biçimde bildirir; bu nedenle yalnızca bildirilmiş bir değeri okuyan bir şablonun ortaya çıkardığı ret farklı bildirilir. Okuma, izin kullandığıyla aynıdır ve bir şablonun yazdığı başvurulardan okunur: bütün bir nesneye ulaşmak, altındaki her bildirilmiş yaprağa ulaşır; bu yüzden değer içermeyen metni de gizleyebilir. Verisinin tamamını tek seferde aktaran bir şablon — ardından hiçbir şey gelmeyen nokta ya da $, toJson gibi bir işleve verilen, yazdırılan ya da adıyla çağırdığı bir şablona aktarılan — içindeki her bildirilmiş değeri okur, bu yüzden reddi de aynı biçimde bildirilir; bir range ya da with gövdesinin içinde nokta, o gövdenin yinelediği ya da adlandırdığı değerdir ve onu aktarmak yalnızca o değerin içerdiğini okur. Buradaki hiçbir şey --trace-unredacted bayrağına bağlı değildir: o bayrak yalnızca iz dosyalarına ulaşır ve bir ret bayrakla da bayraksız da aynı okunur.
Bildirilmiş bir değer, bir listenin içi de dahil, nerede durursa dursun gizlenir. Bir listenin girdileri farklı varlıklar tarafından yönetilir ve her girdi kendi varlığının bildirimlerine göre gizlenir. Sınırın tamamını kapsayan bir FeatureRecipe’nin okuduğu .boundary görünümünde, internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges ve cross_boundary_uses_edges içinde listelenen her bağlantı, hedefinin yayımladığı provides değerlerini taşır ve bunlar hedefin Component’i anahtarı hassas olarak bildirdiğinde gizlenir; feature_attachments içindeki her girdi ise o eklentinin infra değerini taşır ve bu, Feature’ı yaprağı bildirdiğinde gizlenir. Bir bileşene eklenmiş bir Feature’ın bağlamında, .context.used_by içindeki her girdi bağlanan bileşenin yayımladığını taşır ve bu, bağlanan bileşenin Component’i anahtarı bildirdiğinde gizlenir. Varlığı hiçbir şey bildirmeyen bir girdideki aynı anahtar olduğu gibi aktarılır ve gizlenmiş bir girdiden hesaplanan bir locals: girdisi onunla birlikte gizlenir. Bir liste üzerinde yinelemek ya da girdilerinden birine index aracılığıyla ulaşmak tüm listeyi okur; bu nedenle her girdinin taşıdığını okumak sayılır:
error calling fail: target secret_ref "<redacted>" must start with ref-Bu, derlemenin ortaya çıkardığı bir reddin metnine ulaşır. Bir sağlayıcıya, girdisinin hangi kısmının bildirilmiş bir değerden geldiği hakkında söylenenler — bir valuesMapping eşlemesinin ürettiği değerler, işlenmiş bir workload: belgesi, her artifacts: girdisi, bir omits: girdisinin her alanı — bir listenin içinden okunan bir değeri hesaba katmaz; bu nedenle bir sağlayıcının bildirilmiş bir değeri kendi ele alışı, yukarıda açıklanan, bağlı bir literalin CloudFormation tarafından reddedilmesi de dahil, böyle bir değere ulaşmaz.
Bazı retler bunun dışında kalır. Bir plugin’in yazdığı metin — bir provider’ın ya da bir pipeline adımının kendi reddi — plugin’in cümlesidir ve plugin’in yazdığı gibi taşınır. Derlemenin doğrulamaları ve işlemesi dışında değerlendirilen bir şablon — bir Aggregate’teki parametre enterpolasyonu ve parametre denetimleri, bir şemanın when: ve validate: şablonları ve sabitlemesini kaydeden bir source: koordinatının çözümlenmesi — başarısızlığını olduğu gibi bildirir.
Değişmez değer olarak taşınan bir değer için derleme uyarısı
Bir derleme, hassas olarak bildirilmiş materyali değişmez değer olarak taşıyan her teslim anahtarı için bir uyarı yazdırır. Uyarı, bir eklentinin inject bloğu eklentinin Feature’ının hassas olarak bildirdiği bir provides anahtarını tüketen bileşenin bir teslim anahtarına yönlendirdiğinde ve değer gerçekten teslim edildiğinde tetiklenir:
warning: node "db" (provider "helm"): attachment "user_password" delivers a valuedeclared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where thetarget supports it, fill the slot with an attachment that delivers a reference insteadBununla ilgili üç şey kasıtlıdır.
Bir değerin nasıl taşındığını bildirir, bir şeyin yanlış olduğunu değil. Değişmez değer teslim etmek çoğu zaman bir hedefin kabul ettiği tek yoldur ve tam da bunu yapmak için var olan bütün bir eklenti ailesi bulunur. Uyarı, yazara hangi değerin bu yolu nerede izlediğini söyler; böylece seçim örtük değil görünür olur; seçimin bir hata olduğunu iddia etmez.
Bir uyarıdır, asla bir durdurma değildir. Derleme başarılı olur ve yapıtlarını değiştirmeden yazar. Değişmez değer olarak teslim edilen bir kimlik bilgisinin derlemeyi başarısız kılmasını isteyen bir kuruluş bunu derleme üzerinde bir yönetişim politikası olarak ifade eder; bir reddin yeri orasıdır — bazı dağıtımların çiğnemesi gereken bir kural, bir derleyici varsayılanı değildir.
Karar bağlantılardan verilir, asla değerden değil. Uyarı, bir şemanın bildirdiği hassasiyeti ve yazarın yazdığı teslimi okur. Hiçbir değer incelenmez; bu yüzden bir alanın adına ya da içeriğine bakılarak kimlik bilgisi olduğu asla tahmin edilmez ve bir parola içeren bildirilmemiş bir değer hiçbir şey tetiklemez.
İki durum bilerek sessiz kalır. Başvurduğu provides anahtarı hiçbir şey yayımlamayan bir teslim anahtarı değişmez değer teslim etmez ve hiçbir şey bildirmez — uyarı gerçekleşmiş bir teslimi izler. inject izin listesi boş olan bir slot ise teslimi Recipe’ye bırakır; bu yüzden yazar bildirilecek bir teslim anahtarı yazmamıştır ve üzerinde işlem yapacağı bir şey yoktur.
Uyarı kendi sınıfındadır, kendi koduyla anahtarlanır ve --no-unsupported-field-warnings onu susturmaz: o bayrak bir hedefin doğruluk bildirimlerini kapsar; bunlar farklı nedenlerle susturulan farklı bir değerlendirmedir. Uyarı, dil sunucusu --build-on-inspect (ya da serve.build_on_inspect yapılandırma anahtarı) açık olarak çalıştığında düzenleyiciye de ulaşır ve orada Aggregate üzerinde bir sorun olarak görünür. Bu ayar, aggrega inspect ile tutarlılık için varsayılan olarak kapalıdır: terminal komutu bir grafiği incelerken işleme aşamasına hiç ulaşmaz, bu yüzden böyle bir uyarı da üretmez; hiç uyarı üretmeyen bir düzenleyici incelemesi size terminalin gösterdiğinin aynısını gösterir. Ayarı açmak, düzenleyiciden ek katmanı istemenin yoludur ve bunu yaptığınızda diske hiçbir şey yazılmaz — aşama çalışır ve yapıtları atılır. Bir derlemenin işleme sırasında ürettiği uyarıları ekler, bir derlemenin durduğu denetimlerin hiçbirini eklemez. Yayımlanan her sorun onu üreten katmanı adlandırır; böylece bir düzenleyici bu uyarıyı çözümleme ve analiz aşamalarının bildirdiklerinden ayrı tutabilir.
Bir eşlemenin işaretsiz render ettiği değer için derleme uyarısı
Bir derleme, yazar üzerinde hâlâ denetimi elinde tutarken işaretini bir render’ın taşıyamadığı, hassas olarak bildirilmiş her values yaprağı için bir uyarı yazdırır. Uyarı, değerleri bir valuesMapping çıktısı olan bir source: üzerinden yapılan render’da tetiklenir: Component’inin bildirdiği bir yaprak üzerinde bir Recipe’nin eşlemesi ya da bir bileşene eklenmiş bir Feature’ın FeatureRecipe’sinin, o Feature’ın bildirdiği bir yaprak üzerindeki eşlemesi. Eşlemenin çıktı anahtarları kendi icadıdır; bu nedenle hiçbir bildirim bunlardan hiçbirini adlandırmaz ve hedef, yaprak için anahtar başına hiçbir işaret almaz:
warning: node "api" (provider "terraform"): attachment "token": "values.token" is declaredsensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMappingwhose output keys no declaration names, so the target receives no per-key sensitivitymarking for it; ...Satır, yaprağı yazıldığı koordinatta ve birleşimi denetleyen eşlemenin ait olduğu Recipe ya da FeatureRecipe ile adlandırır, çünkü bildirim ve eşleme iki farklı varlıkta yazılır; bir eklemenin satırı, eklendiği adla başlar, böylece bir bileşen üzerindeki tek bir Feature’ın iki eklemesi birbirinden ayırt edilir. Denetim aracı eşlemeyi kaldırmaktır: eşleme olmadan bir kaynak render’ının aldığı değerler, bildirilmiş yaprak yollarıyla anahtarlanır ve işaret onlarla birlikte taşınır. Yalnızca yapıtlara yönelik bir render ile yalnızca iş yüküne yönelik bir render sessiz kalır, çünkü hedeflerine hiçbir değer haritası vermezler; boş bir values sütununa karşı render edilen, bir sınıra eklenmiş Feature da sessiz kalır — yukarıdaki sınır orada kalıcıdır ve bir uyarı yapılacak hiçbir şey adlandırmaz. Değişmez olarak taşınan bir değer için verilen uyarı gibi, bu da bir uyarıdır ve asla bir durdurma değildir; render edilen hiçbir baytı değiştirmez, kendi kodu sensitivity-not-conveyed olan kendi sınıfıdır ve --no-unsupported-field-warnings onu susturmaz. Uyarılar ve linter çıktısı tam biçimini verir.
Bildirimin okunduğu ve okunmadığı yerler
Anahtar sözcük, üzerinde bulunduğu düğümde okunur ve okuma ardından bir bildirimin o veriye ulaşabileceği her yolu izler: iç içe özellik haritaları, her bileşim dalı ve bir $ref hedefi. Bir dal da bir referans hedefi de kendilerini taşıyan özelliğe bileşir; bu nedenle ikisinden biri aracılığıyla bulunan bir bildirim o özellik için toplanır; yolu yalnızca bir properties inişi uzatır.
Bir işaretçi, bu anahtar sözcüklerden birinin yanında da, anahtar sözcüğün ulaştığı yerin içinde de olsa okunur; bu nedenle iki biçim bilinçli bir yerleştirme gerektirmez:
- Bir
$refyanında ya da referansın hedefinin içinde. Referans veren yapraktaki bir işaretçi o yaprağı bildirir. Referans verilen şemadaki bir işaretçi de referans veren yaprak için, o yaprağın yolu artı altındaki zincirde toplanır — asla tanımın içindeki, yazılmış hiçbir değerin bulunmadığı bir yolda değil. - Bir bileşim anahtar sözcüğünün (
allOf/anyOf/oneOf) yanında ya da bir dalın kendipropertiesiçinde. Bir dal, kendisini taşıyan nesneye bileşir; bu nedenle her dala inilir — JSON Schema olarak yazılmış bir düğümün koşullu dalları da dahil — ve bunlardan birinin içindeki bir bildirim, bileşen özelliğin kendi yolu artı zincirinde toplanır.
Bir biçim ise işaretçinin bilinçli olarak yerleştirilmesini gerektirir:
- Dizi yaprağının kendisinde,
itemsöğe türünde değil. Öğeleri hassas malzeme taşıyan bir dizi, dizide hassas olarak bildirilir, çünkü bir öğe türü bir özellik haritası değildir ve içine inilmez.
parameters: farklı bir sözcük dağarcığıdır
sensitive, parameters: türlendirilmiş sözleşme sözcük dağarcığının bir parçası değildir. Bunu bir parametre girdisinde bildiren bir Aggregate, Aggregate yüklendiğinde, doğrudan sorunlu anahtarın üzerinde konumlanmış ve unexpected property: "sensitive" bildiren bir belge zarfı tanılamasıyla reddedilir — parametre sözleşmesi kapalı bir nesne olduğundan, bu sözcük dağarcığının dışındaki her anahtarın gördüğü işlemin aynısıdır.
Bu asimetri bilinçlidir: hassasiyet ekseni, bir katalog varlığının bildirdiği üç veri sütununu kapsar; bir parametre ise bir sütun yaprağı değil, bir ortam sözleşmesi girdisidir. Kimlik bilgisi malzemesinin bir parametre aracılığıyla yukarı taşınması architecture/08-credential-model.md içindeki “Legacy charts that demand a formatted string” bölümünde belgelenmiştir; bu bölüm, o yolun yaptığı ödünleşimi açıklar.
allOf, anyOf, oneOf ile bileşim
Bileşim anahtar sözcükleri JSON Schema’daki gibi çalışır:
# Inherit and extendsecondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 }
# Disjunction (one of several shapes)auth: oneOf: - existingSecret: { type: string, required: true } - rootPassword: { type: string, required: true } username: { type: string, default: app_user } password: { type: string, required: true }Derleyici, çözümlenmiş JSON Schema’da aynı bileşim anahtar sözcüklerini üretir. Bileşimi oluşturan girdilerin her biri kompakt biçim, JSON Schema ya da $ref: başvuruları olabilir. Bir bileşim içinde bunların karıştırılması desteklenir.
Kaçış yolu — $jsonschema:
Kompakt biçimin sözcük dağarcığının ötesindeki durumlarda ($dynamicRef, unevaluatedProperties, derin not: bileşimi, özyinelemeli türler) herhangi bir düğüm tam JSON Schema’ya geçebilir:
values: architecture: { type: string, enum: [standalone, replication] } some_complex_field: $jsonschema: | type: object unevaluatedProperties: false allOf: - $ref: "#/$defs/Foo" - not: required: [conflicting_field] patternProperties: "^x-": { type: string } $defs: Foo: type: object properties: name: { type: string }$jsonschema: bloğu JSON Schema YAML’ı içerir; derleyici bunu saydam bir doğrudan geçiş olarak ele alır — içerik, çözümlenmiş JSON Schema belgesine doğrudan o düğümün konumunda girer. Doğrulama, hata raporlama ve araçların tümü çözümlenmiş belge üzerinde çalışır; kaçış yalnızca yazma kolaylığı içindir.
Bir not: dalı, dışladığı biçimin neden reddedildiğini söyleyen bir description: taşıyabilir. Bu dalla eşleşen bir değer, bu durumda genel “not allowed here (burada izin verilmiyor)” ifadesinin yerine, açıklama gerekçe olarak tek satırda yazdırılarak reddedilir — bu yüzden onu, reddedilen değerin yazarının okuması gereken cümle olarak yazın. Yalnızca not: dalının kendisine yazılan açıklama kullanılır; dalın yalnızca başvurduğu bir $defs girdisindeki açıklama kullanılmaz.
Bloğun içindeki her düğüm JSON Schema olarak okunur ve oraya yazılan bir kompakt biçim anahtar sözcüğü kompakt anlamını korur (bir dize üzerindeki min: 3 yine en küçük uzunluktur). Bloktaki bir $ref, bloğun dışındaki gibi çözümlenir: #/$defs/Foo, sütunun $defs: girdilerinden birini adlandırır; bu yüzden örnek Foo’yu orada bildirir ve kimsenin bildirmediği bir girdiyi adlandıran başvuru, varlık yüklenirken reddedilir. $dynamicRef bir $dynamicAnchor’a göre çözümlenir; bu sayede özyinelemeli bir yapı yazılabilir. Özyinelemenin derinlerinde doğrulamayı geçemeyen bir değer, onu tutan alanda bildirilir — children öğeleri { $dynamicRef: "#node" } olan bir ağaçta iki düzey aşağıdaki hatalı bir name için tree.children.
unevaluatedProperties ve unevaluatedItems için bir sınır geçerlidir. Ayrıca bir başvuru, bir bileşim anahtar sözcüğü (allOf, anyOf, oneOf), bir koşul ya da bağımlı bir şema taşıyan bir düğüme yazıldığında her ikisi de yüklenir ancak uygulanmaz — ve unevaluatedItems, contains’in yanında da uygulanmaz. Yukarıdaki örnekte unevaluatedProperties: false, allOf’un yanında durduğundan, ne Foo ne de patternProperties extra’yı bildirmediği hâlde { name: n, extra: 1 } kabul edilir.
$jsonschema: kaçışı belge başına değil, düğüm başınadır. Bir şema basit kısımlar için kompakt biçimi, tek karmaşık alan için JSON Schema kaçışını ve paylaşılan yapılar için $ref: kullanabilir — hepsi tek bir belgede.
Kompakt biçim ile JSON Schema’yı tek belgede karıştırma
Kompakt biçim ve JSON Schema, herhangi bir düğüm sınırında serbestçe karıştırılabilir. Yönlendirme kuralı içeriğin şekline göre işler:
$jsonschema:içeren bir düğüm JSON Schema olarak ele alınır (kaçış yolu).- JSON Schema tarzı üst düzey anahtar sözcükler (
type:,properties:,additionalProperties:,if:vb.) içeren bir düğüm JSON Schema olarak ele alınır (açık biçim). - Yalnızca özellik adı → alt şema girdileri içeren (JSON Schema’ya ayrılmış anahtar sözcük içermeyen) bir düğüm kompakt biçim olarak ele alınır (çıkarımlı biçim).
- Yalnızca
$ref:içeren bir düğüm, doğrudan aktarılan bir başvurudur. allOf:/anyOf:/oneOf:içeren bir düğüm bileşimdir; her girdi bağımsız olarak yönlendirilir.
Kompakt biçimli yapraklar için standart kalıp field_name: { type: ..., constraints... } şeklindedir: bilinen bir kompakt biçim sözcük dağarcığı içeren bir YAML eşlemi. Yönlendirme, kısıt sözlüklerini anahtarlarından tanır.
Nadir görülen belirsiz durumda (örneğin, çıkarımlı biçim yönlendirmesinin JSON Schema anahtar sözcüğü olarak yorumlayacağı, adı tam olarak type olan bir alan içeren kompakt biçimli bir şema), standart çözüm açık biçimdir; yukarıdaki “Her çıkarımlı biçim kapsamında ayrılmış anahtar sözcükler” bölümüne bakın.
Bir sözleşmeyi dosyadan içe aktarma — $import:
Bir sözleşmenin, onu bildiren varlığın içinde yer alması gerekmez. $import:, sözleşmenin okunacağı dosyayı belirtir:
spec: schema: $import: ./contracts/api-server.schema.yamlBu durumda spec.schema bütünüyle o dosyadan gelir; dosya, yerini aldığı blokla tam olarak aynı biçimde yazılır: en üstte sütunlar, altında compact form ya da JSON Schema YAML’ı:
values: greeting: { type: string, enum: [hello, howdy], default: hello }infra: image_tag: { type: string, default: "1.0" }provides: host: { type: string }Tek bir sütun da kendi başına içe aktarılabilir; kardeşleri onun yanında satır içinde yazılır:
spec: schema: values: $import: ./contracts/values.yaml infra: image_tag: { type: string, default: "1.0" }Aynı biçim, bir usesSchema: soketinin valueSchema: ve infraSchema: alanlarında da çalışır.
Bunu yöneten kurallar:
$import:, bulunduğu konumdaki tek anahtardır. Yanına yazılan bir kardeş anahtar, ikisinden biri atılmak yerine reddedilir.- Göreli bir yol, onu bildiren varlık dosyasını içeren dizine göre okunur; derlemenin çalıştırıldığı dizine göre asla okunmaz. Bu,
valuesMapping:,workload:veartifacts:alanlarının kullandığı tabanın aynısıdır. Yol bu dizinin içinde kalmalıdır, çünkü varlığın bir yayınının taşıdığı her dosya oradan alınır: bu dizinden dışarı çıkan bir yol ya da mutlak bir yol, varlıkla birlikte taşınmayacak bir dosyayı belirtir ve reddedilir; bkz. A path names content outside the entity’s own directory (Bir yol, varlığın kendi dizini dışındaki içeriği belirtiyor). Birden çok varlığın paylaştığı bir şema,$ref:ile başvurulan bir SchemaLibrary içinde yer almalıdır. - İçe aktarılan dosya varlıkla birlikte taşınır. Yayınlanan bir varlık, şemasının içe aktardığı her dosyayı, bir zincirin tüm dosyaları dahil, taşır; böylece bir kayıt defterinden çekilen bir kopya aynı sözleşmeyi okur ve ona göre yazılmış değerleri doğrular; bkz.
aggrega push. - İçe aktarılan dosya bir varlık belgesi değil, şema içeriği taşır. İçeriği bir YAML eşlemesi olmayan dosya, dosya adı belirtilerek reddedilir.
- İçe aktarılan bir dosyanın kendisi de tek bir
$import:olabilir; bu özyinelemeli olarak çözümlenir. Hâlihazırda okunmakta olan bir dosyaya geri dönen zincir, zincir belirtilerek reddedilir.
İçe aktarma, varlık yüklendiğinde okunur; böylece o varlığı okuyan her yüzey aynı sözleşmeyi görür: aggrega validate, bir derleme, aggrega push, aggrega inspect ve düzenleyici. Okunamayan bir dosya ya da şema olmayan içerik, sözleşmeyi uygulanmamış bırakmak yerine o noktada reddedilir; bir push işlemi de bunu herhangi bir şey yayınlanmadan önce reddeder.
$import: ve $ref: birbirinin yerine kullanılamaz. $import: bir dosyayı belirtir ve içeriğin tamamının yerini alır; $ref: ise bir SchemaLibrary girdisini kimliğiyle belirtir ve herhangi bir düğümde birleştirilir. Bir kütüphane kimliği ya da kayıt defteri ana bilgisayarı taşıyan bir $import: değeri, $ref: kullanılması yönünde bir yönlendirmeyle reddedilir. Bkz. cross-document-ref.md.
Aggrega uzantı ad alanı — x-aggrega-*
Kompakt biçim, x-aggrega- önekiyle başlayan her anahtar sözcüğü Aggrega’ya özgü bir uzantı olarak tanır. Ad alanı açıktır: yeni açıklamalar, anahtar sözcük başına sözlük düzenlemesi gerekmeden kataloğa girer. x-aggrega-selector, x-aggrega-narrowed-from veya gelecekteki açıklamaları yazan yazarlar, içeriklerini derleme zamanında reddedilmeden çözümlenmiş JSON Schema’da doğru kapsama yerleştirir.
Ad alanı öneki önemlidir: x-agrega-source gibi bir yazım hatası (bir g eksik) uzantı anahtar sözcüğü olarak TANINMAZ ve çıkarımsal biçim kapsamlarındaki kapalı nesne semantiği tarafından reddedilir. Önek kapsamı, kataloğun açıklama yüzeyi için bir yazım hatası algılama ağı işlevi görür.
Belirli x-aggrega-* açıklamaları, derleyici tarafından işlem hattının bilinen noktalarında üretilir:
x-aggrega-selector:—usesSchema:vefeaturesSchema:sentezi tarafından, uyumlu sağlayıcı Components’i hedefleyen seçici dizesini taşımak için üretilir.x-aggrega-sensitive:—sensitive: truebildiren bir yaprak tarafından üretilir. Yukarıdaki Bir yaprağı hassas olarak bildirme bölümüne bakın.
Kendi uzantı anahtar sözcüklerini yazan katalog yazarları aynı ad alanını kullanır; derlenmiş JSON Schema’yı tüketen aşağı akış araçları, x-aggrega-* anahtarlarını JSON Schema’nın kendi anahtar sözcük alanıyla çakışmadan okur.
Çalışılmış örnek — MariaDB Component şeması
Bir MariaDB veri deposu için temsili bir kompakt biçimli Component şeması; baştan sona çıkarımsal biçimi, karışık yaprak kısıtlarını, referansları, koşullu şekli ve kimlik doğrulama bloğu için çalışılmış bir oneOf örneğini gösterir:
spec: schema: values: architecture: type: string enum: [standalone, replication] default: standalone description: | Topology mode. `standalone` runs a single primary; `replication` runs a primary plus N secondary replicas governed by the secondary block.
primary: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: { $ref: "#/$defs/PodResources" } persistence: { $ref: "#/$defs/PersistenceSpec" }
secondary: when: '{{ eq $.architecture "replication" }}' properties: replicaCount: { type: integer, min: 2, max: 8, default: 2 } resources: { $ref: "#/$defs/PodResources" } persistence: { $ref: "#/$defs/PersistenceSpec" }
auth: oneOf: - existingSecret: { type: string, required: true } - rootPassword: { type: string, sensitive: true, required: true } username: { type: string, default: app_user } password: { type: string, sensitive: true, required: true } database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }
metrics: enabled: { type: boolean, default: false } serviceMonitor: enabled: { type: boolean, default: false } namespace: { type: string }
labels: { type: object, valuesType: string }
$defs: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" } limits: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
PersistenceSpec: size: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$", required: true } storageClass: { type: string }JSON Schema YAML olarak yazıldığında aynı sözleşme her nesnenin type: object, properties: ve additionalProperties: false değerlerini açıkça yazar ve her zorunlu alanı üst öğenin required: alanında yeniden listeler; bu yüzden çok daha uzun olur. Kompaktlık kazancı daha büyük Component sözleşmelerinde katlanarak artar ve kompakt biçimi schema:, parameters: ve SchemaLibrary girdileri için varsayılan yazım yüzeyi yapacak kadar anlamlıdır.
Çapraz bağlantılar
- Belgeler arası
$ref:çözümleme semantiği için (belgeler arası bir başvurunun yanındakirequired:sözdizimi; kütüphaneden kütüphaneye zincir genişletme; tüketicinin kütüphaneyi daraltması): cross-document-ref.md. assertions:bloğunun yazım dilbilgisi için (compact formvalidate:ile ifade edilemeyen alanlar arası kurallar): templates/assertions-block.md.- Compact form şemalarını barındıran veri sütunları kümesi için (
values:,infra:,provides:,uses:,features:,locals:,parameters:): data-pillars.md. - OCI URI kısaltmasının genişletme kuralları için (alan adı varsayılanı, kayıt defteri segmenti, sürüm geri dönüşü, yayıncı genişletmesi): uri-grammar.md.
- SchemaLibrary varlığının yazımı için (
$ref:ile başvurulabilen şemaların katalogda bulunduğu yer): ../entities/schemalibrary.md.