콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

컴팩트 형식 작성

컴팩트 형식은 JSON Schema 2020-12를 위한 YAML 형태의 선언적 약식 표기입니다. 작성자는 필드별 제약 조건을 인라인 플로 YAML 맵으로 작성하고(port: { type: integer, min: 1, max: 65535, default: 8080 }), 중간 객체 노드는 자연스러운 YAML 중첩으로 표현하며, 참조에는 JSON Schema의 표준 $ref:를 사용합니다. 컴파일러는 검증이 실행되기 전에 컴팩트 형식을 JSON Schema 2020-12로 변환하므로, 검증, 오류 보고, 그리고 스키마를 읽는 모든 도구는 어느 형식으로 작성되었든 해석된 JSON Schema를 대상으로 동작합니다.

이 페이지에서는 컴팩트 형식 어휘, 구조적 관례, 추론형 대 명시형 객체 디스패치, 닫힘 의미론, 허용되는 타입의 배열을 허용하는 type:의 이질성, 모든 추론형 범위에서 예약된 키워드, 그리고 x-aggrega-* 확장 네임스페이스를 설명합니다. 문서 간 $ref: 해석 의미론은 cross-document-ref.md를 참조하십시오. assertions 블록 작성 문법은 templates/assertions-block.md를 참조하십시오. 데이터 필러 집합(values:, infra:, provides:, uses:, features:, locals:, parameters:)은 data-pillars.md를 참조하십시오.

컴팩트 형식은 schema:, parameters: 및 SchemaLibrary 항목의 기본 작성 방식입니다. JSON Schema YAML도 동등한 작성 방식이며, 두 형식 모두 일급 형식으로서 하나의 스키마 안에서 혼용할 수 있습니다. 두 형식은 동일한 해석된 JSON Schema 문서로 컴파일되며, 이후의 도구와 검증은 작성 경로를 알지 못합니다.

어휘

컴팩트 형식의 키워드는 아래 표에 있는 것들입니다. 한 번 익히면 schema:, parameters:, SchemaLibrary 항목 전반에 걸쳐 적용할 수 있습니다.

타입 및 식별 키워드

키워드의미JSON Schema 컴파일 결과
type필드 타입(string, integer, number, boolean, object, array 또는 허용되는 타입의 배열)type:
description사람이 읽을 수 있는 문서description:
default필드가 없을 때의 기본값default:
required반드시 있어야 하는 필드에 대한 리프별 표시(required: true)부모의 required: 배열에 필드 이름을 추가합니다

제약 키워드

키워드의미JSON Schema 컴파일 결과
enum허용되는 값(목록)enum:
const허용되는 유일한 값 — 스칼라, 매핑 또는 리스트const:
min최솟값(숫자) 또는 최소 길이(문자열/배열)minimum:(숫자), minLength:(문자열), minItems:(배열) — type:에 따라 선택됨
max최댓값 또는 최대 길이, min과 대응maximum: / maxLength: / maxItems:
minLength / maxLength명시적 문자열 길이 제약minLength: / maxLength:에 직접 대응(min/max가 모호할 때 사용)
pattern문자열에 대한 정규식 패턴pattern:
format문자열이 따라야 하는 명명된 형식 — email, uri, hostname, ipv4, ipv6, uuid, date-time, date 중 하나(명명된 형식 참조)format:

Aggregate의 parameters: 블록에서는 이 중 일부가 Release 값을 읽기 전에 선언 자체에 대해서도 검사됩니다. 매개변수 자체의 minLength와 maxLength는 0 이상이어야 하며 음수는 Aggregate를 로드할 때 거부됩니다. 또한 중첩된 items, properties, valuesType 계약 안의 것을 포함한 모든 pattern은 컴파일 가능한 정규식이어야 합니다. 매개변수 계약을 읽을 때 패턴이 컴파일되기 때문입니다. 모든 format은 깊이와 관계없이 아래의 명명된 형식 중 하나여야 합니다. 불리언 또는 객체 매개변수의 min이나 max도 거부됩니다. 이 타입에서는 이 쌍이 아무것도 제한하지 않기 때문입니다. 각 오류는 Release가 해당 매개변수를 제공하는지 여부와 관계없이 매개변수 이름을 밝히며 빌드를 중단합니다. 중첩된 계약 안의 길이 범위에는 이 하한이 적용되지 않습니다. 각 검사가 실행되는 위치는 entities/aggregate.md를 참조하십시오.

명명된 형식

format은 문자열 값이 가져야 하는 형태를 지정합니다. 이름은 JSON Schema 명세가 정의한 것이며 명세의 철자를 그대로 따르고, 각각 명세가 정의한 의미를 검사합니다.

이름적합한 값정의 출처
email메일박스: 로컬 부분(점으로 구분된 아톰 또는 따옴표로 묶인 문자열), @, 그리고 도메인 또는 대괄호로 묶인 주소 리터럴 — ops@example.com. Joe <joe@example.com> 같은 표시 이름은 메일박스가 아닙니다RFC 5321, 4.1.2절(Mailbox)
uri절대 URI: 스킴, :, 그리고 나머지 부분이며, URI 문자 집합 밖의 문자는 퍼센트 인코딩됨 — https://example.com/a%20b, s3://bucket/key. /path 같은 상대 참조는 해당하지 않습니다RFC 3986(URI)
hostname호스트 이름: 문자, 숫자, 하이픈으로 이루어진 점으로 구분된 레이블로, 각 레이블은 1–63자이고 하이픈으로 시작하거나 끝나지 않으며, 전체 길이는 최대 253자 — db-primary.data.svc.cluster.local. Punycode 레이블(xn--…)은 작성된 그대로 허용되지만, 와일드카드 *, 밑줄, 끝의 점은 허용되지 않습니다RFC 1123, 2.1절
ipv4점으로 구분된 0에서 255 사이의 십진수 네 개 — 192.0.2.1RFC 2673, 3.2절(dotted-quad)
ipv6모든 텍스트 형식의 IPv6 주소 — 전체 형식, :: 압축 형식, 또는 IPv4 주소로 끝나는 형식 — 2001:db8::1. 존(%eth0)이나 접두사 길이(/64)는 주소의 일부가 아닙니다RFC 4291, 2.2절
uuid하이픈으로 구분된 8-4-4-4-12 그룹의 16진수 32자리, 대소문자 무관 — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122, 3절
date-time오프셋이 있는 타임스탬프 — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00. 날짜는 해당 월에 존재해야 하며, 윤초는 23:59 UTC에만 허용됩니다RFC 3339, 5.6절(date-time)
date달력 날짜 — 2026-09-28 — 해당 연도와 월에 존재하는 날짜RFC 3339, 5.6절(full-date)

형식은 문자열만 판정합니다. 다른 타입의 값은 그 type이 판정합니다. 또한 값의 구문만 판정합니다. 호스트 이름을 확인(resolve)하지 않고, URI를 가져오지 않으며, 메일박스에 연락하지 않습니다. 따라서 검사는 모든 빌드에서 같은 결과를 내며 네트워크가 필요하지 않습니다.

이 검사는 값이 스키마에 대해 검증되는 모든 곳에서 실행됩니다. Aggregate의 parameters:, Component나 Feature의 schema: 필러가 제약하는 values와 infra, usesSchema: 소켓의 페이로드 스키마가 제약하는 에지별 values와 infra, 그리고 이 스키마들이 도달하는 모든 SchemaLibrary 항목이 해당합니다. provides 필러의 형식 이름은 다른 스키마와 마찬가지로 카탈로그를 로드할 때 판정되지만, Recipe가 게시하는 값은 필러에 대해 검증되지 않으므로 그 값에는 형식이 검사되지 않습니다. allOf, anyOf, oneOf, not 안에서 형식을 만족하지 못한 값은 다른 제약을 만족하지 못한 값과 똑같이 해당 분기를 만족하지 못한 값입니다. 적합하지 않은 값은 필드, 값, 형식을 밝히며 거부됩니다.

표에 없는 이름은 스키마를 로드할 때 거부되며, 어떤 값이 도달하는지와는 관계없습니다. 거부 메시지는 지원되는 이름을 나열하므로 emial 같은 오타는 아무것도 검사하지 않는 제약이 아니라 진단이 됩니다. SchemaLibrary 항목의 경우 잘못된 이름을 확인하려면 카탈로그 전체에 대해 aggrega validate를 실행하십시오. 스키마가 해당 항목에 도달하는 Release도 거부되지만, 라이브러리를 찾을 수 없다고 보고합니다. password는 형식이 아닙니다. 비밀 정보를 담는 필드는 대신 sensitive: true를 선언합니다.

간접적으로 도달하는 형태에는 한 가지 제한이 있습니다. 필드의 형태가 다른 키워드(예: properties: 맵)를 함께 가진 $ref:, when:의 then: 또는 else:, 또는 선언된 속성을 가리키는 포인터를 통해 주어지는 경우, 해당 format은 그 형태가 직접 선언하거나 allOf를 통해 선언한 필드에서는 검사되지만, 그 형태 안의 anyOf, oneOf, not 또는 조건부 분기 안에서는 검사되지 않습니다.

조합 및 참조 키워드

키워드의미JSON Schema 컴파일 결과
$refJSON Pointer 프래그먼트 또는 외부 SchemaLibrary 항목에 대한 참조$ref:
allOf / anyOf / oneOfJSON Schema 조합동일한 키워드
patternProperties정규식 키 맵동일한 키워드
valuesType타입이 지정된 값 맵의 축약형(예: “모든 값이 문자열인 객체”)additionalProperties: { type: <X> }

컨테이너 키워드

키워드의미JSON Schema 컴파일 결과
items배열 요소 형태items:(재귀적 축약형 또는 JSON Schema)
properties명시적 자식 선언(거의 필요하지 않음, 보통 YAML 구조로 암시됨)properties:
additionalProperties선언되지 않은 속성의 허용 여부(추론형 객체에서는 컴파일러가 추가하는 false이며, 명시적 type: object에서는 직접 작성하고, 작성하지 않으면 JSON Schema 자체의 기본값인 true가 적용됨)additionalProperties:

Aggrega 전용 키워드

키워드의미
validate불리언을 반환하는 필드별 Go 템플릿 조건식. false이면 validateMessage:와 함께 검증을 중단합니다
validateMessagevalidate: 실패 시 함께 표시되는 오류 메시지
when조건부 하위 트리 적용. 노드의 제약을 적용할지 결정하는 Go 템플릿 조건식
sensitive이 리프가 비밀 정보를 담고 있음을 선언합니다. x-aggrega-sensitive: true로 컴파일됩니다. 아래 “리프를 민감 정보로 선언하기”를 참조하십시오
$jsonschema탈출구 — 이 노드에 포함된 완전한 JSON Schema 하위 문서
$mode모호한 경우를 위한 선택적 디스패치 주석(거의 필요하지 않음, 아래 “추론된 객체 형식과 명시적 객체 형식” 참조)

차용한 JSON Schema 키워드($ref, allOf, format 등)는 JSON Schema와 동일한 구문을 사용하므로, JSON Schema를 이미 아는 작성자는 바로 알아볼 수 있습니다.

값이 데이터인 키워드는 그 값을 작성된 그대로 담습니다. default, enum, const에 주어진 매핑이나 리스트는 값 그 자체이며 결코 중첩 스키마가 아닙니다. endpoint: { type: object, default: { host: db, port: 5432 } }는 endpoint의 기본값을 그 객체로 설정하고, mode: { type: object, const: { kind: fast } }는 정확히 그 객체만 허용합니다. mode: { const: { kind: fast } }도 마찬가지인데, const는 enum과 같이 그 자체로 노드를 리프로 만들기 때문입니다. $jsonschema: 탈출구 안에서도 동일합니다.

압축 형식 리프의 구조

작성의 단위는 리프 노드, 즉 제약 딕셔너리를 가진 필드입니다:

field_name: { type: <type>, ...constraints... }

일반적인 패턴:

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 }

각 리프는 한 줄입니다. 제약 딕셔너리는 필드의 형태에 관한 모든 것을 담고, 부모 노드의 구조는 필드의 위치를 담습니다.

중첩 객체

객체 구조는 YAML 중첩을 그대로 반영합니다. 깊은 중첩도 바로 동작하며, 각 리프는 여전히 한 줄입니다:

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 }

컴파일러는 YAML 계층에서 객체 구조를 추론합니다. 중간 노드(여기서는 primary, resources, requests, limits, auth)는 중첩된 자식을 포함하는 객체 타입입니다. 컴파일러는 해석된 JSON Schema에 명시적인 type: object 및 properties: 블록을 출력하며, 작성자는 이를 작성하지 않습니다.

추론 형식과 명시적 객체 형식

compact form 객체 스코프는 두 가지 방식으로 작성할 수 있습니다.

추론 형식 — 자식이 부모 키 바로 아래에 오며, type: object 선언이 없습니다.

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }

컴파일러는 자식이 속성 선언이므로 이 스코프를 객체로 인식합니다. 컴파일러는 type: object, properties: { ... }를 생성하고, 컴파일 시점에 additionalProperties: false를 자동으로 주입합니다. 이 닫힘 의미론은 추론 형식 계약의 일부입니다. 개발자가 작성한 필드의 오타는 명확하게 실패합니다.

명시적 형식 — type: object를 선언하고 properties:를 나열합니다.

auth:
type: object
properties:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }
required: [password]
additionalProperties: true # genuinely-open map authored on purpose

명시적 형식에서는 컴파일러가 additionalProperties: false를 주입하지 않습니다. type: object를 선언하는 작성자는 닫힘 여부 결정에 대한 모든 책임을 집니다. 명시적 형식은 실제로 열린 맵(additionalProperties: true)과 다른 JSON Schema 키워드(patternProperties, propertyNames, unevaluatedProperties)가 필요한 객체를 위한 표면입니다.

작성 기준: 일반적인 닫힌 객체(카탈로그 스키마에서 흔한 경우)에는 추론 형식을 사용합니다. 객체가 실제로 열려 있어야 하거나, compact form이 직접 지원하지 않는 JSON Schema 키워드가 스키마에 필요한 경우에는 명시적 형식을 사용합니다.

폐쇄 의미론

관례에 따라 compact form의 추론 형식 객체는 닫혀 있습니다. 즉, 선언되지 않은 속성은 검증 오류를 발생시킵니다. 컴파일러는 모든 추론 형식 객체 스코프에 additionalProperties: false를 자동으로 내보냅니다. 이는 오타가 명확하게 실패하도록 하는 카탈로그 규율과 일치합니다.

객체를 열려면(임의의 추가 속성을 허용하려면) additionalProperties: true와 함께 명시적 형식을 사용합니다.

labels:
type: object
additionalProperties: true # opt-in; allow any string-keyed values

“모든 값이 같은 타입을 공유하는 객체”라는 흔한 패턴(예: 레이블용 string → string 맵)에는 valuesType:을 사용합니다.

labels: { type: object, valuesType: string }
nodeSelector: { type: object, valuesType: string }
counters: { type: object, valuesType: integer }

valuesType: <type>은 additionalProperties: { type: <type> }로 컴파일됩니다. 단일 키워드 약식을 둘 만큼 자주 쓰이는 패턴입니다.

위의 단순 타입 이름은 schema:와 SchemaLibrary에서의 표기입니다. Aggregate의 parameters: 슬롯에서는 값을 대신 계약으로 작성합니다 — valuesType: { type: string }. 값 자체가 계약인 나머지 두 키워드, 즉 items:와 properties: 아래의 각 항목에도 같은 내용이 적용됩니다. 파라미터 선언과 그 안에 중첩된 모든 계약이 하나의 형태를 가지기 때문입니다. 파라미터 슬롯에서 이 세 위치 중 어디에든 단순 타입 이름이 오면 거부되며, 진단은 어느 중첩 계약이 그것을 포함했는지 알려 줍니다. 파라미터 슬롯 어휘 전체는 entities/aggregate.md를 참조하십시오.

필수 필드

필수 필드는 리프마다 required: true를 사용합니다:

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 }

컴파일러는 객체 범위 안의 모든 required: true 표시를 수집하여 JSON Schema의 required: [field1, field2] 배열로 출력합니다. 이 표시는 속성이 선언된 위치와 관계없이 유효합니다. 추론 형식 범위에서도, 명시적 properties: 블록 안의 속성에서도 마찬가지입니다.

$ref:를 통해 SchemaLibrary 항목을 자신의 스키마로 가져오는 소비자는 필수 항목을 어느 방식으로든 지정할 수 있습니다. 참조 옆에 상위 수준의 required: [name1, name2] 배열을 두거나, 그곳의 properties: 아래에 선언한 속성에 required: true 표시를 두면 됩니다. 전체 규칙은 cross-document-ref.md §“문서 간 $ref:에서의 required: 구문”을 참조하십시오.

배열

배열은 type: array를 사용하며, items:로 요소의 형태를 기술합니다:

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 }

“타입이 지정된 스칼라의 배열”이라는 흔한 경우에는 인라인 형식이 한 줄로 끝납니다. 객체의 배열에서는 items:가 중첩된 compact-form 스키마를 도입합니다.

type: 키워드 — 스칼라 또는 타입 배열

type:는 단일 값(type: string) 또는 허용되는 타입의 배열(type: [string, integer, boolean])을 받습니다. 배열 형식은 “이 필드는 여러 타입 중 하나를 받는다”를 나타내는 JSON Schema 2020-12의 표준 표현입니다:

release_tier: { type: [string, integer], description: "Numeric tier or named tag" }

type:에 배열이 오면 값 공간은 명명된 타입들의 값 공간의 합집합입니다. 배열 형식을 사용하는 스키마를 작성하는 경우 다운스트림에서 두 형태를 모두 처리해야 합니다. 해석된 JSON Schema의 type 필드에는 문자열 또는 배열이 들어 있으며, 해석된 스키마를 순회하는 소비자는 두 형태를 모두 확인합니다.

모든 추론 형식 스코프에서의 예약 키워드

추론 형식 디스패치는 compact-form 어휘 수준에서 의미를 갖는 소수의 키워드를 인식합니다. description, type, default, required, 제약 키워드(enum, const, min, max, pattern, format 등), 그리고 Aggrega 전용 키워드(validate, validateMessage, when, sensitive)입니다. 이 키워드 중 하나가 추론 형식 객체 스코프에서 필드 이름으로 나타나면, 컴파일러는 둘러싼 스코프를 객체가 아닌 제약 리프로 읽습니다. 해당 키워드는 자식 속성이 아니라 제약으로 받아들여지며, 그 스코프의 다른 모든 키도 키워드여야 하므로 키워드가 아닌 첫 번째 키는 알 수 없는 키워드로 거부됩니다.

sensitive는 여기서 특별히 언급할 필요가 있습니다. 다른 Aggrega 전용 키워드보다 개발자가 작성하는 실제 필드 이름으로 쓰일 가능성이 훨씬 높기 때문입니다. 실제로 sensitive라는 이름의 속성이 필요한 스키마(예를 들어 values가 자체 sensitive 플래그를 노출하는 component)는 type이나 default라는 이름의 속성과 마찬가지로 둘러싼 스코프를 명시적으로 선언해야 합니다. 아래의 명시적 형식을 쓰거나 둘러싼 스코프에 $mode: jsonschema를 지정하면 됩니다. $mode: jsonschema에서는 노드 전체가 작성된 JSON Schema로 읽히며, 여기서 sensitive는 compact-form 키워드가 아닌 일반 내용입니다.

예약 키워드의 이름을 딴 속성이 필요한 스키마(예: 개발자가 작성한 description: 필드, type: 필드 또는 default: 필드가 있는 Component 계약)에서는 문제가 되는 스코프에 명시적 형식을 사용합니다.

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: false

명시적 형식은 디스패치를 우회합니다. properties:가 자식을 명시적으로 나열하므로 키워드 충돌이 발생하지 않습니다.

이 제약은 모든 추론 형식 스코프에 재귀적으로 적용됩니다. 예약 키워드의 이름을 딴 속성을 포함하는 중첩된 추론 형식 객체는 해당 스코프에서 제약 리프로 읽힙니다. 해결 방법은 같습니다. 문제가 되는 스코프를 명시적 형식으로 바꾸면 됩니다.

참조

참조는 JSON Schema의 $ref:를 구문과 의미 모두 그대로 빌려 씁니다:

resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }

compact form 스키마 안의 $defs: 블록은 재사용 가능한 정의를 선언합니다. 각 항목은 그 자체로 compact form(또는 JSON Schema, 또는 혼합) 스키마입니다. #/$defs/<Name> JSON Pointer 프래그먼트로 참조합니다:

블록은 그 블록을 참조하는 필드가 속한 pillar 안에, 해당 필드 옆에 선언합니다. pillar 옆이 아닙니다. schema: 블록은 자신의 최상위 수준에서 세 가지 데이터 pillar 이름만 허용하므로, values:와 같은 수준에 작성한 $defs:는 엔터티를 로드할 때 거부되며, 문제가 된 키와 그 위치에 둘 수 있는 pillar 집합이 함께 표시됩니다. 어느 경우든 포인터는 #/$defs/<Name>로 표기합니다.

$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 항목을 대상으로 하는 문서 간 참조는 cross-document-ref.md를 참조하십시오. OCI URI 축약형 확장은 uri-grammar.md를 참조하십시오.

참조는 속성이 아니라 정의를 가리키십시오

$defs: 항목을 가리키는 포인터(#/$defs/PodResources)가 기본으로 사용할 형태입니다. 포인터는 JSON Schema가 허용하는 곳이면 어디서나 사용할 수 있으므로, 선언된 속성을 가리키는 포인터도 허용되고 적용되지만, 오류가 덜 정확하게 보고되므로 작성하기 전에 그 차이를 알아 둘 필요가 있습니다.

$defs: 항목에서 형태를 가져오는 필드는 필드 단위로 검사됩니다. 실패는 실제로 잘못된 값의 경로에서 보고되며, 해당 필드 아래의 모든 실패가 첫 번째 실패만이 아니라 전부 보고됩니다.

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary:
resources: { $ref: "#/$defs/PodResources" }

여기서 잘못된 cpu는 primary.resources.requests.cpu에서 보고됩니다.

선언된 속성을 가리키는 포인터에서 형태를 가져오는 필드는 문서 전체의 일부로 검사됩니다. 제약 조건은 여전히 적용되며 이를 위반하는 문서는 여전히 중단되지만, 실패는 그 안의 값이 아니라 포인터를 가진 필드에서 보고되며, 그러한 필드 여러 개가 동시에 잘못된 경우 그중 하나만 표시됩니다.

primary:
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary:
resources: { $ref: "#/properties/primary/properties/resources" }

secondary 아래의 잘못된 cpu는 secondary.resources에서 보고됩니다.

두 작성 방식은 Named formats에 명시된 format에 관한 한 가지 제한을 제외하면 같은 문서를 허용하고 거부합니다. 포인터를 통하는 경우 형태의 anyOf, oneOf 또는 not 분기 안에 있는 format은 검사되지 않습니다. 그 밖에 다른 점은 메시지가 얼마나 많은 정보를 알려 주는가이며, 이는 해당 경로를 기준으로 마커가 배치되는 편집기에서 가장 중요합니다. 자체 포인터가 다시 속성 쪽을 가리키는 $defs: 항목에도 같은 내용이 적용됩니다. 그 항목을 통해 정의에 도달하면 덜 정밀한 보고를 그대로 물려받습니다.

when:을 통한 조건부 형태

JSON Schema 2020-12는 조건부 형태를 if/then/else로 표현합니다. 컴팩트 형식은 더 직접적인 축약형으로 when:을 제공합니다. 이는 Go 템플릿 조건식으로, 참이면 노드의 나머지 제약 조건을 적용하고, 거짓이면 노드를 해당 제약 조건이 존재하지 않는 것처럼 취급합니다.

secondary:
$ref: "#/$defs/NodePool"
when: '{{ eq $.architecture "replication" }}'
required: true
properties:
replicaCount: { type: integer, min: 2 }

조건식은 상위 객체의 인스턴스 값을 기준으로 평가됩니다. $는 둘러싼 객체 범위를 가리킵니다. architecture가 replication이면 제약 조건(required: true와 추가된 replicaCount: min: 2)이 참조된 NodePool 위에 적용됩니다. architecture가 standalone이면 해당 제약 조건은 비활성 상태입니다.

조건식에서는 표준 Go 템플릿 함수(Sprig)를 사용할 수 있습니다. 컴파일러는 when:을 JSON Schema의 if/then/else와, 검증이 실행되기 전에 Go 템플릿 조건식을 평가하는 래퍼로 컴파일합니다. 조건식은 인스턴스에 대해 순수하므로 결정성이 유지됩니다.

validate:와 validateMessage:를 통한 필드별 사용자 정의 검증

일부 제약 조건은 min / max / pattern / enum으로 표현할 수 없습니다. 이런 경우를 위해 compact form은 validate:를 제공합니다. 이는 거짓이면 사용자 정의 오류와 함께 검증을 중단하는 Go 템플릿 술어입니다.

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"

술어는 필드의 값(.으로 접근)을 대상으로 실행되며, 주변 객체 범위는 $입니다. 술어가 거짓을 반환하면 검증은 validateMessage:(제공되지 않은 경우 기본 메시지)를 사용해 오류를 생성합니다.

validate:는 JSON Schema의 표준 어휘를 넘어서는 경우를 처리합니다. 사용자 정의 의미 검증(semver 형식 검사, 문자열 안의 JSON 내용), 한 필드의 제약 조건이 형제 필드에 의존하는 필드 간이지만 범위가 좁은 규칙, 그리고 완전한 assertions: 블록을 쓸 가치가 없는 제약 조건이 이에 해당합니다.

validate:는 역할 면에서 when:과 다릅니다. when:은 제약 조건의 적용 여부를 전환하고, validate:는 그 자체가 제약 조건입니다.

어느 한 필드도 “검증 대상”이 아닌, 범위가 넓은 진정한 필드 간 규칙에는 전용 assertions: 블록을 사용합니다. templates/assertions-block.md를 참조하십시오.

리프를 민감한 것으로 선언하기 — sensitive:

values, infra 또는 provides 리프는 자신이 설명하는 데이터가 비밀 자료를 담고 있다고 선언할 수 있습니다.

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는 해석된 JSON Schema의 해당 노드에서 다른 x-aggrega-* 주석과 함께 확장 키워드 x-aggrega-sensitive: true로 컴파일됩니다. 컴파일러는 이를 읽어 배포에서 어떤 첨부가 민감한 것으로 선언된 자료를 다루는지 도출하고, 도출한 사실을 컴파일된 그래프에 실어 전달합니다.

위치 지정자가 아니라 데이터에 선언하십시오. 이 구분이 키워드의 핵심이며, 거꾸로 이해하기 쉽습니다. 자격 증명의 자료는 민감하지만, 그것을 보관하는 리소스의 이름과 그 리소스 안의 데이터 키는 민감하지 않습니다. 둘 다 공개되어 있으며, 해당 리소스를 참조하는 모든 소비자에 평문으로 렌더링됩니다. 위치 지정자에 표시하면 그것에 대해 사실이 아닌 내용을 진술하게 되고, 그 오류가 선언을 읽는 모든 하위 요소로 전파됩니다. 위 예에서 origin은 표시되어 있고 key는 의도적으로 표시되어 있지 않습니다.

이를 보완하는 진술, 즉 채움이 자신의 리프에 대해 무엇을 선언하든 이 지점에 바인딩되는 것은 무엇이든 비밀 자료를 다룬다는 진술은 리프 선언이 전혀 아닙니다. 이는 첨부 슬롯의 sensitive입니다. entities/component.md의 “Attachment Slots”를 참조하십시오.

객체 전체를 민감한 것으로 선언하기

이 키워드는 스칼라가 아니라 객체에 둘 수도 있으며, 그 경우 해당 객체 아래의 모든 것, 즉 객체 자신의 자식과 더 깊이 중첩된 모든 것에 적용됩니다. 블록 전체가 자료이고 각 리프를 따로 표시하면 다음에 누군가 추가하는 리프가 표시되지 않은 채 남게 될 때 사용할 선언입니다.

객체의 자식은 명시적인 properties: 블록 안에 있어야 합니다. 이곳은 추론된 객체 형식이 통하지 않는 유일한 곳이며, 그 이유는 우회하기보다 알아 둘 가치가 있습니다.

spec:
schema:
values:
credentials:
type: object
sensitive: true
properties: # required here
username: { type: string }
password: { type: string }

추론된 객체 형식이 다른 모든 곳에서 허용하는 방식대로 표시자 바로 옆에 자식을 작성하면 컴파일 시점에 거부됩니다. 첫 번째 자식이 알 수 없는 키워드로 보고되며, 위치는 그 자식 자신의 키입니다.

values:
credentials:
type: object
sensitive: true
password: # refused: unknown keyword "password"
type: string

이 거부는 우회해야 할 제약이 아니라 올바른 동작입니다. 노드는 compact form 키워드를 갖는 순간 제약 리프로 읽히며, sensitive:도 그런 키워드입니다. 따라서 그 시점부터 모든 형제 키도 키워드여야 하는데, password는 키워드가 아닙니다. properties: 블록은 “아래의 키는 키워드가 아니라 속성 이름”이라고 말해 주는 것이며, 추론된 객체 형식과 명시적 객체 형식에서 설명하는 것과 같은 모호성 해소입니다. 진단을 “표시자는 객체에 둘 수 없다”로 읽는 것은 피해야 할 오해입니다. 둘 수 있으며, 블록이 그것을 표현하는 방법입니다.

선언된 객체 안의 리프에는 별도의 표시자가 필요하지 않습니다. 추가해도 해가 없지만 새로운 의미는 없습니다. 객체의 선언이 이미 그 리프를 포함하기 때문입니다.

이 키워드가 하지 않는 일

이름 때문에 키워드가 실제로 하지 않는 일을 가정하기 쉬우므로, 한계를 분명히 밝혀 둡니다.

  • 아무것도 암호화하지 않습니다. 이는 선언에 붙는 주석일 뿐, 기밀성 메커니즘이 아닙니다.
  • CloudFormation 템플릿의 파라미터를 채우는 경우를 제외하면 검증하거나 거부하지 않습니다. 리프가 민감한 것으로 선언되었다는 이유로 값이 수락되거나 거부되지 않으며, 빌드 결과도 바뀌지 않습니다. 단, CloudFormation Recipe나 FeatureRecipe의 valuesMapping이 민감한 것으로 선언된 리프를 읽어 가져온 템플릿의 파라미터를 채우는 경우에는, 그 매핑이 바인딩하는 모든 리터럴이 빌드를 중단시키므로 선언 여부만 다른 두 빌드의 결과가 달라질 수 있습니다. A secret bound to a CloudFormation parameter would be written into the template (CloudFormation 파라미터에 바인딩된 비밀이 템플릿에 기록됨)를 참조하십시오.
  • 렌더링된 출력에 자료가 없음을 보장하지 않습니다. 아티팩트에 자료가 담기는지는 작성자가 어떤 채움을 첨부했고 그 values에 무엇을 썼는지에 달려 있습니다. architecture/08-credential-model.md의 “What the compiler does and does not guarantee”를 참조하십시오. 작성자가 인라인으로 제공한 민감한 것으로 선언된 값은, 빌드가 그것을 렌더링하는 곳이라면 어디서든 선언되지 않은 값과 똑같이 렌더링됩니다.
  • 전달 메커니즘을 강제하지 않습니다. 인라인 값을 저장소 참조로 바꿀 수 없으며, 슬롯의 inject 허용 목록이 허용하는 범위를 좁히지도 않습니다.
  • 앞서 말한 CloudFormation 거부를 통하지 않고는 빌드를 중단하지 않습니다. 아래에서 설명하는, 이 키워드가 발생시키는 빌드 시점 알림은 권고입니다. 빌드는 끝까지 실행되고 아티팩트를 기록합니다. 알림을 치명적 오류로 만드는 것은 조직의 선택이며, 빌드에 첨부된 거버넌스 정책으로 표현됩니다. 키워드가 스스로 하는 일이 아닙니다. 위의 CloudFormation provider 거부는 예외로서 빌드를 중단합니다. 템플릿에 기록된 리터럴은 스택을 읽을 수 있는 누구나 읽을 수 있기 때문입니다.
  • 대부분의 대상에서는 렌더링된 바이트를 하나도 바꾸지 않으며, 그런 대상에서는 앞으로도 바꾸지 않습니다. 자체적인 민감성 개념을 갖춘 대상 플랫폼이라야 선언이 반영될 곳이 있습니다. 그런 개념이 없는 대상에서는 선언이 바꿀 것이 영구히 없습니다. Terraform은 그러한 기본 요소를 갖춘 유일한 표준 라이브러리 대상입니다. 벤더링된 모듈의 입력이 작성자가 민감한 것으로 선언한 자료를 받는 경우, 렌더링된 출력에 해당 입력에 대한 Terraform 자체의 민감성 속성을 명시하는 생성된 재정의 파일이 추가됩니다. providers/terraform.md의 “Declared-sensitive module inputs”를 참조하십시오. 그 밖의 모든 곳에서는 기존 카탈로그 전반에 걸쳐 리프를 민감한 것으로 선언해도 렌더링된 모든 아티팩트가 동일하게 유지됩니다.

도구가 출력하는 내용에서 바뀌는 것

선언이 실제로 바꾸는 한 가지는 사람이 읽도록 도구가 출력하는 내용, 즉 디버그 출력과 아래에서 설명하는 거부 메시지의 텍스트입니다. 디버그 화면에서는 민감한 것으로 선언된 값이 고정 텍스트 <redacted>로 대체됩니다.

  • aggrega build --trace가 .trace/에 기록하는 패스별 트레이스
  • aggrega inspect가 Aggregate에 대해 출력하는 노드별 Values: 블록
  • aggrega inspect가 해석된 Release에 대해 출력하는 리프별 첨부 블록

키는 항상 유지되고 값만 대체되므로, 읽는 사람은 리프가 작성되어 있으며 무언가가 가려졌다는 것을 여전히 알 수 있습니다. 작성자가 선언하지 않은 리프는 가려진 형제 옆에 값이 그대로 출력됩니다. 대체는 오로지 선언만을 따르므로, 선언이 없는 password라는 필드는 출력되고, 선언된 key라는 필드는 출력되지 않습니다.

선언은 그 아래의 모든 리프에 미치며, 세 화면 모두에 같은 방식으로 적용됩니다. 선언이 객체에 있으면 그 객체 안에 중첩된 각 값도 깊이에 관계없이 가려집니다. 객체의 선언이 그 값들을 지칭하므로, 가리더라도 작성자가 쓰지 않은 것을 주장하지 않습니다. 일치는 텍스트가 아니라 경로 세그먼트 전체를 기준으로 하므로, 이름이 선언된 이름으로 시작할 뿐인 형제는 영향을 받지 않습니다. dbPassword를 선언해도 dbPasswordHint는 가려지지 않습니다.

가려진 값 자체를 디버깅해야 할 때는 한 번의 빌드에 한해 트레이스의 가림을 끌 수 있습니다. aggrega build --trace --trace-unredacted는 값을 트레이스 파일에 기록하고, 해당 파일마다 그 사실을 알리는 헤더를 표시합니다. 이는 구성 설정이 없는 호출 시점의 선택이며, 트레이스에만 적용되고, cli/aggrega-build.md의 “Showing the withheld values”에 문서화되어 있습니다. aggrega inspect 레이아웃에는 별도의 --unredacted가 있으며, cli/aggrega-inspect.md의 “Showing the withheld values”에 문서화되어 있습니다.

이 동작에서는 동작 자체보다 그 경계가 더 중요합니다.

렌더링된 아티팩트는 절대 가려지지 않습니다. dist/ 아래의 모든 것은 렌더링이 만들어 낸 그대로 출력됩니다. 그것이 배포 대상이기 때문입니다. manifest에 자리 표시자를 써 넣으면 보호된 배포가 아니라 망가진 배포가 됩니다. 가리기는 도구가 출력하는 것에만 적용되며, 도구가 쓰는 것에는 결코 적용되지 않습니다. 선언을 dist/를 공개해도 안전하다는 약속으로 읽는 것이 피해야 할 오독입니다. 위에서 설명한 한계는 그대로이며, dist/는 가장 많은 기밀 자료를 담은 attachment만큼 민감합니다.

선언이 렌더링된 아티팩트에 추가할 수 있는 것이 하나 있으며, 이는 가리기가 아닙니다. 대상이 자체 민감성 기본 요소를 가진 경우, 선언이 그 안에 렌더링됩니다. 값은 여전히 전부 기록되며 아무것도 감춰지거나 대체되지 않습니다. 아티팩트가 얻는 것은 값 옆에 붙는 대상 자체의 표시이며, 이를 통해 대상의 도구가 작성자가 선언한 대로 값을 다룰 수 있습니다. 현재 이를 제공하는 대상은 Terraform이며, 그 속성이 보장하는 것과 보장하지 않는 것은 providers/terraform.md “Declared-sensitive module inputs”에 있습니다. 이러한 표시는 렌더링된 이름의 정체가 선언 자체에서 복원되는 경우에만 전달됩니다. 템플릿이 이름을 만들어 낸 경우에는 표시를 근사하지 않고 생략합니다. 작성자가 선언하지 않은 값을 표시하면 그 값에 대해 거짓을 주장하게 되기 때문입니다. 그 템플릿이 valuesMapping인 경우, 즉 Recipe의 것이거나 component에 연결된 Feature의 FeatureRecipe의 것인 경우, 아래에서 설명하는 대로 빌드가 이를 알립니다.

가리기는 선언이 지정하는 것과, 템플릿이 읽는 것으로 확인되는 것에 적용됩니다. values 또는 infra 영역의 선언된 리프, 그리고 민감하다고 선언된 provides 키의 자료를 전달하는 전달 키는 모두 이름으로 식별되어 감춰집니다. 템플릿이 계산한 값은 아무도 선언하지 않은 키 아래에 놓이므로, 대신 작성자가 쓴 참조로 식별합니다. 트레이스에서 템플릿이 민감하다고 선언된 리프를 읽는 locals: 항목이나 source: 필드는 감춰지며, 이미 감춰진 형제 항목을 읽는 locals: 항목도 마찬가지입니다. 이 해석은 의도적으로 보수적입니다. 객체 전체에 접근하면 그 아래의 모든 선언된 리프에 접근하는 것이고, 데이터 전체를 넘기는 템플릿은 그 모두에 접근하는 것입니다. 따라서 해석할 수 없는 참조는 출력하지 않고 감춥니다.

렌더링된 문서는 재렌더링으로 표시되며, 그 사실을 밝힙니다. 트레이스의 파싱된 Workload는 Recipe의 템플릿이 만들어 낸 문서입니다. 그 안의 어떤 것도 각 문자가 어느 선언에서 왔는지 기록하지 않으므로, 그 안에서 대체할 키가 없으며, 필드별로 연결을 복원하려면 값의 내용을 검사해야 하는데 컴파일러는 그렇게 하지 않습니다. 대신 트레이스가 보여 주는 것은 민감하다고 선언된 데이터가 이미 대체 텍스트로 읽히는 컨텍스트에 대해 같은 workload: 템플릿을 다시 평가한 결과이며, 이는 문서 옆의 workload_note 항목으로 안내됩니다. 템플릿은 문자열이 있던 자리에서 문자열을 보므로, 재렌더링은 출력된 문서의 형태를 유지하고 대체 텍스트는 감춰진 데이터 자체의 위치에 놓입니다. 두 가지 차이가 남으며 안내 항목은 둘 다 밝힙니다. 값의 내용에 따라 분기하는 템플릿은 대체 텍스트에 대해 다르게 렌더링되며, 축이 지정하지 않는 데이터는 그대로 전달됩니다. 이는 렌더링된 것의 디버깅용 보기일 뿐, 결코 그 사본이 아닙니다.

소비된 노드의 값은 그 노드의 선언에 따라 감춰지며, 엣지가 값을 전달하는 두 표면 모두에서 그렇습니다. uses 엣지 보기는 대상 component가 게시한 것을 재현하므로 대상 자체의 스키마가 이를 결정합니다. 대상이 민감하다고 선언한 provides 키는 소비자가 아무것도 선언하지 않더라도 소비자의 트레이스에서 감춰집니다. 엣지 자체의 inject 블록이 그 키를 소비하는 component의 전달 키로 연결하는 경우, 그 전달 키도 감춰집니다. 이는 attachment의 inject 매핑이 따르는 것과 같은 규칙이며 같은 선언을 읽으므로, 두 연결 방식이 서로 어긋날 수 없습니다. aggrega inspect 레이아웃은 노드 자체의 영역과 attachment를 보여 줄 뿐 소비된 노드의 게시된 값은 보여 주지 않으므로, 거기에는 감출 노드 간 보기가 없습니다.

연결에 작성된 attachment는 자체 Feature의 선언에 따라 감춰지며, 이를 보여 주는 모든 표면에서 그렇습니다. 트레이스는 이를 해당 연결의 uses 엣지 보기 아래 .context.uses.<alias>.features.<slot>에 표시하고, aggrega inspect는 해석된 Release에서 연결 줄 아래에 출력합니다. 두 곳 모두에서, Feature가 민감하다고 선언한 values 또는 infra 리프는 같은 Feature가 component에 직접 연결된 경우와 똑같이 감춰지며, 트레이스에서는 Feature가 민감하다고 선언한 attachment의 해석된 provides 키도 감춰집니다. 타입, 버전, 레이블, 그리고 선언되지 않은 모든 리프와 provides 키는 그대로 출력되므로, 게시된 위치 지정자는 그것이 가리키는 자료 옆에서 계속 읽을 수 있습니다. component나 소켓에서 sensitive: true를 선언한 슬롯은 attachment가 기밀 자료를 다룬다고 표시할 뿐 스스로 어떤 리프도 감추지 않습니다. 어떤 리프를 감출지는 Feature가 선언할 몫입니다.

기계 판독용 투영은 계약상 원문 그대로이며, 원본 파일과 같은 방식으로 다루어야 합니다. aggrega inspect --raw는 엔터티를 작성된 그대로 출력하며, aggrega inspect --output yaml은 Release를 포함한 모든 종류의 작성된 엔터티를 재현합니다. 어느 쪽도 아무것도 대체하지 않으며, 이는 의도된 것입니다. 이 출력은 스크립트가 파싱하고 diff가 비교하는 대상이므로, 자신의 일부를 조용히 감추는 출력은 재현한다고 주장하는 입력을 잘못 나타내고 소비자가 의존하는 왕복 변환을 깨뜨립니다. 리프를 민감하다고 선언하는 것만으로는 이러한 출력에서 그 리프를 배제할 수 없습니다. 이 출력을 파이프로 넘기고, 저장하고, 공유할 때는 Aggregate와 Release 자체를 다루듯이 다루십시오.

컴파일된 그래프는 어디에 제공되든 값을 감추는 유일한 기계 판독용 투영입니다. aggrega inspect, aggrega validate, aggrega build의 --ir-graph는 명령이 원래 만드는 출력과 함께 실행이 해석한 그래프를 JSON으로 기록하며, 데몬의 aggrega/irGraph는 같은 그래프로 편집기에 응답합니다. 각각에서 작성자가 민감하다고 선언한 값은 읽기용 레이아웃과 똑같이 대체됩니다. --ir-graph와 함께 --unredacted를 지정하면 대신 그 값들을 출력하며, 데몬 요청의 unredacted 필드도 마찬가지입니다. 따라서 명령에서 읽은 그래프와 데몬 프로토콜로 읽은 그래프는 같은 처리 규칙이 적용되는 같은 문서이며, 작성된 값이 필요한 파이프라인이나 클라이언트는 이를 명시적으로 요청해야 합니다.

거부가 선언된 값에 대해 말하는 내용

작성자가 sensitive로 선언한 값을 읽는 템플릿이 발생시킨 거부에는 그 값이 담기지 않습니다. 템플릿이 빌드를 중단시킬 때 — fail을 호출하는 어서션, 평가할 수 없는 표현식, 템플릿이 생성해야 하는 문서로 읽히지 않는 출력 — 그 참조 중 하나가 sensitive로 선언된 데이터에 닿으면, 보고되는 내용은 sensitive로 선언된 모든 데이터가 이미 <redacted>로 읽히는 컨텍스트에 대해 같은 템플릿을 한 번 더 평가한 결과에서 나옵니다. 단, 템플릿이 스스로 작성한 문장에서 멈춘 경우는 예외이며, 이는 아래의 첫 번째 경우입니다:

assertion failed: the admin password <redacted> must be supplied as a reference
  • 템플릿에 문장이 그대로 작성된 fail은 작성된 대로 보고됩니다. 빌드를 중단시킨 호출이 따옴표로 묶은 문자열 하나를 받은 fail인 경우 — fail "…", 즉 파이프로 전달된 것도 없고 그 문장에 조합된 것도 없는 경우 — 값의 내용이나 어떤 분기가 그 호출로 이어졌는지와 관계없이 거부에는 그 문장이 담깁니다. 그 문장은 템플릿이 읽은 어떤 것도 인용하지 않기 때문입니다. 형식이 잘못된 오리진을 거부하는 어서션은 그 형식에 대한 자체 설명을 보여 줍니다. 다른 방식으로 만들어진 문장 — printf, 필드, 변수, fail로 파이프된 값 — 은 이어지는 경우에 따라 보고됩니다.
  • 두 번째 평가가 같은 표현식에서 같은 이유로 실패하면, 그 실패가 보고됩니다. 작성자 자신의 문장은 값이 있던 자리에 <redacted>가 들어간 채로 유지되며, 템플릿이 인코딩하거나 인용하거나 다른 방식으로 변환한 값도 숨겨집니다. 치환이 변환보다 먼저 일어나기 때문입니다.
  • 그렇지 않으면, 거부는 실패한 표현식을 지목하고 그 텍스트가 숨겨졌다고 알립니다. 이는 동작이 값의 내용에 따라 달라진 템플릿입니다. 대체 텍스트에 대해 다른 분기를 탔거나 다른 곳에서 실패한 것이므로, 템플릿이 구성한 어떤 것도 보여 줄 수 없습니다. 이런 거부가 스스로를 설명하게 하려면, 첫 번째 경우에서 설명한 대로 fail 호출에 그 문장을 그대로 작성하십시오. 거부는 여전히 빌드를 중단시키며 그 코드도 유지합니다.
  • Workload 스키마가 거부한 렌더링된 Workload는 스키마를 바탕으로 문구가 작성됩니다. 문서의 필드에는 템플릿이 읽은 데이터로 돌아가는 연결이 없으므로, 템플릿이 sensitive로 선언된 데이터를 읽은 경우 값을 인용할 수 있는 모든 결과는 대신 제약 조건을 명시하고, 값의 자리에 <redacted>를 넣고 그 이유를 밝히는 안내를 덧붙입니다. 값에서 도출된 조언은 제공되지 않으며, 값을 인용하지 않는 결과 — 누락된 키, Workload가 허용하지 않는 키 — 는 평소와 같이 표시됩니다:
.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)
  • 파이프라인 단계의 선언된 입력 계약이 거부한 그 단계의 with 입력은 계약을 바탕으로 문구가 작성됩니다. with 템플릿이 sensitive로 선언된 데이터를 읽는 경우가 해당됩니다. 입력에서 실패한 각 위치와 이를 거부한 스키마 키워드가 표시되고, 그 이유를 밝히는 안내가 뒤따르며, 입력이 담고 있던 내용은 전혀 표시되지 않습니다.
  • source: 좌표를 지목하는 거부는 선언되지 않은 것이 생성한 내용을 바탕으로 문구가 작성됩니다. source: 템플릿이 sensitive로 선언된 데이터를 읽어 그 좌표를 생성한 경우가 해당되며, 소스가 lockfile이나 캐시에 없거나, 캐시된 아카이브가 lockfile에 기록된 내용과 일치하지 않거나, 엔터티 옆에 기록된 pin이 lockfile과 다른 경우입니다. 이러한 거부가 출력하는 모든 줄은 조회에 사용된 좌표를 지목하므로, 소스를 그 url과 요청된 버전 또는 참조로 지목하되 — 그것들을 읽은 경우 — 그러한 템플릿이 생성한 각 항목은 <redacted>로 표시하고, 그 이유가 숨겨졌다고 알립니다. 거부는 그 코드와, 빌드가 해당 코드에 대해 제시하는 해결 방법을 유지합니다:
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 produced

선언된 것으로 간주되는 범위는, 템플릿이 읽을 수 있는 컨텍스트의 모든 부분에서 선언이 지목하는 것입니다. 즉 컴포넌트 자신의 values와 infra, 컴포넌트와 그 각 연결에 첨부된 Features, 선언된 자료를 전달하는 delivery 키, 해당 Component가 sensitive로 선언한 provides 키, 컨텍스트가 담고 있는 목록의 각 항목(아래에서 설명), 그리고 이들 중 어느 것에서든 계산된 locals: 항목입니다. 이들 중 어느 것도 읽지 않는 템플릿은 어디에도 선언이 없을 때와 바이트 단위로 정확히 똑같이 보고하므로, 선언된 값을 읽은 템플릿이 발생시킨 거부만 다르게 보고됩니다. 이 판단은 trace가 사용하는 것과 같으며, 템플릿이 작성한 참조로부터 읽어 냅니다. 객체 전체에 닿으면 그 아래의 선언된 모든 리프에 닿으므로, 값을 담지 않은 텍스트를 숨길 수도 있습니다. 데이터 전체를 한꺼번에 넘기는 템플릿 — 뒤에 아무것도 없는 점이나 $를 toJson 같은 함수에 전달하거나, 출력하거나, 이름으로 호출하는 템플릿에 넘기는 경우 — 은 그 안의 선언된 모든 값을 읽으므로, 그 거부도 같은 방식으로 보고됩니다. range나 with 본문 안에서 점은 그 본문이 순회하거나 지목하는 값이며, 이를 넘기면 그 값이 담은 것만 읽습니다. 여기서의 어떤 것도 --trace-unredacted에 의존하지 않습니다. 이 플래그는 trace 파일에만 적용되며, 거부는 플래그가 있든 없든 똑같이 표시됩니다.

선언된 값은 목록 안을 포함해 어디에 있든 숨겨집니다. 하나의 목록에 있는 항목들은 서로 다른 엔터티가 관할하며, 각 항목은 자신의 엔터티를 기준으로 숨겨집니다. 바운더리 전체에 걸친 FeatureRecipe가 읽는 .boundary 뷰에서는 internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges, cross_boundary_uses_edges에 나열된 각 연결이 그 대상이 게시하는 provides를 담고 있으며, 대상의 Component가 해당 키를 sensitive로 선언한 경우 숨겨집니다. 또한 feature_attachments의 각 항목은 해당 첨부의 infra를 담고 있으며, 그 Feature가 해당 리프를 선언한 경우 숨겨집니다. 컴포넌트에 첨부된 Feature의 컨텍스트에서는 .context.used_by의 각 항목이 연결하는 컴포넌트가 게시하는 것을 담고 있으며, 연결하는 컴포넌트의 Component가 해당 키를 선언한 경우 숨겨집니다. 아무것도 선언하지 않은 엔터티의 항목에 있는 같은 키는 그대로 인용되며, 숨겨진 항목에서 계산된 locals: 항목도 함께 숨겨집니다. 목록을 순회하거나 index를 통해 그 항목 중 하나에 접근하면 목록 전체를 읽게 되므로, 모든 항목이 담고 있는 것을 읽은 것으로 간주됩니다:

error calling fail: target secret_ref "<redacted>" must start with ref-

이는 빌드가 발생시키는 거부의 텍스트에 적용됩니다. 프로바이더의 입력 중 어느 것이 선언된 값에서 왔는지에 대해 프로바이더에게 전달되는 정보 — valuesMapping이 생성한 값, 렌더링된 workload: 문서, 각 artifacts: 항목, omits: 항목의 각 필드 — 는 목록 내부에서 읽은 값을 포함하지 않으므로, 선언된 값에 대한 프로바이더 자체의 처리는, 위에서 설명한 바인딩된 리터럴에 대한 CloudFormation의 거부를 포함해, 그러한 값에 미치지 않습니다.

일부 거부는 이 범위 밖에 있습니다. 플러그인이 작성하는 텍스트 — provider나 파이프라인 단계 자체의 거부 — 는 플러그인의 문장이며, 플러그인이 작성한 그대로 전달됩니다. 빌드의 어서션과 렌더링 밖에서 평가되는 템플릿 — Aggregate의 파라미터 보간과 파라미터 검사, 스키마의 when: 및 validate: 템플릿, pin을 기록하는 source: 좌표의 해석 — 은 실패한 그대로 실패를 보고합니다.

리터럴로 전달되는 값에 대한 빌드 권고

빌드는 sensitive로 선언된 자료를 리터럴 값으로 전달하는 delivery 키마다 권고를 하나씩 출력합니다. 이 권고는 첨부의 inject 블록이 그 첨부의 Feature가 sensitive로 선언한 provides 키를 소비하는 컴포넌트의 delivery 키로 라우팅하고, 그 값이 실제로 전달될 때 발생합니다:

warning: node "db" (provider "helm"): attachment "user_password" delivers a value
declared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where the
target supports it, fill the slot with an attachment that delivers a reference instead

이 권고에는 의도된 점이 세 가지 있습니다.

이 권고는 값이 어떻게 전달되는지를 보고할 뿐, 무언가 잘못되었다고 보고하지 않습니다. 리터럴 전달은 대상이 받아들이는 유일한 방식인 경우가 많으며, 바로 그렇게 하기 위해 존재하는 첨부 계열 전체가 있습니다. 권고는 어떤 값이 그 경로를 어디서 타는지 작성자에게 알려 선택이 암묵적이지 않고 드러나게 할 뿐, 그 선택이 실수라고 주장하지 않습니다.

이 권고는 경고이며 결코 중단이 아닙니다. 빌드는 성공하고 아티팩트를 변경 없이 기록합니다. 리터럴로 전달되는 자격 증명 때문에 빌드가 실패하기를 원하는 조직은 이를 빌드에 대한 거버넌스 정책으로 표현하며, 거부는 그곳에 속합니다. 일부 배포가 어겨야만 하는 규칙은 컴파일러 기본값이 아닙니다.

이 권고는 값이 아니라 배선을 근거로 판단됩니다. 권고는 스키마가 선언한 민감도와 작성자가 작성한 전달 방식을 읽습니다. 어떤 값도 검사하지 않으므로, 필드의 이름이나 내용으로 자격 증명이라고 추측하는 일은 없으며, 우연히 비밀번호를 담은 선언되지 않은 값은 아무것도 발생시키지 않습니다.

두 가지 경우는 의도적으로 아무것도 출력하지 않습니다. 참조하는 provides 키가 아무것도 게시하지 않는 delivery 키는 리터럴을 전달하지 않으므로 아무것도 보고하지 않습니다. 권고는 실제로 일어난 전달을 따르기 때문입니다. 그리고 inject 허용 목록이 비어 있는 슬롯은 전달을 Recipe에 맡기므로, 작성자가 작성한 보고할 delivery 키가 없고 조치할 것도 없습니다.

이 권고는 자체 코드를 키로 하는 별도의 클래스이며, --no-unsupported-field-warnings로는 억제되지 않습니다. 이 플래그는 대상의 충실도 알림을 다루는데, 이는 다른 판단이며 다른 이유로 억제됩니다. 이 권고는 언어 서버가 --build-on-inspect(또는 serve.build_on_inspect 설정 키)를 켠 상태로 실행 중이면 편집기에도 전달되어 Aggregate의 문제로 표시됩니다. 이 설정은 aggrega inspect와의 일관성을 위해 기본적으로 꺼져 있습니다. 터미널 명령은 그래프를 검사하는 동안 렌더링 단계에 도달하지 않으므로 이러한 권고를 발생시키지 않으며, 마찬가지로 아무것도 발생시키지 않는 편집기 검사는 터미널과 같은 내용을 보여 주는 것입니다. 설정을 켜는 것은 편집기에 추가 계층을 요청하는 방법이며, 켜더라도 디스크에는 아무것도 기록되지 않습니다. 단계가 실행되고 그 아티팩트는 폐기됩니다. 이 설정은 빌드가 렌더링 중에 발생시키는 권고를 추가할 뿐, 빌드를 중단시키는 검사는 하나도 추가하지 않습니다. 게시되는 모든 문제는 그것을 발생시킨 계층을 지목하므로, 편집기는 이 권고를 해석 및 분석 단계가 보고하는 권고와 구분할 수 있습니다.

매핑이 표시 없이 렌더링하는 값에 대한 빌드 권고

빌드는 작성자가 아직 조정할 수단을 쥐고 있는데도 렌더가 그 표시를 전달할 수 없는, 민감으로 선언된 values 리프마다 권고를 하나씩 출력합니다. 이 권고는 값이 valuesMapping의 출력인 source:에서의 렌더에서 발생합니다. 이는 Recipe의 매핑이 그 Component가 선언한 리프를 대상으로 하는 경우이거나, 컴포넌트에 부착된 Feature의 FeatureRecipe의 매핑이 그 Feature가 선언한 리프를 대상으로 하는 경우입니다. 매핑의 출력 키는 매핑이 직접 만든 것이므로 어떤 선언도 그 키를 명명하지 않으며, 대상은 해당 리프에 대한 키별 표시를 받지 못합니다:

warning: node "api" (provider "terraform"): attachment "token": "values.token" is declared
sensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMapping
whose output keys no declaration names, so the target receives no per-key sensitivity
marking for it; ...

선언과 매핑은 서로 다른 두 엔터티에 작성되므로, 이 줄은 리프를 작성된 좌표로 명명하고, 그 매핑이 결합을 좌우하는 Recipe 또는 FeatureRecipe를 명명합니다. 부착의 줄은 부착된 이름으로 시작하므로, 한 컴포넌트에 있는 한 Feature의 두 부착을 구별할 수 있습니다. 매핑을 제거하는 것이 조정 수단입니다. 매핑이 없으면 소스 렌더가 받는 값은 선언된 리프 경로를 키로 가지며, 표시가 값과 함께 전달됩니다. 아티팩트 전용 렌더와 워크로드 전용 렌더는 대상에 값 맵을 전혀 넘기지 않으므로 조용히 지나가며, 경계에 부착된 Feature도 마찬가지입니다. 이 Feature는 빈 values 기둥을 대상으로 렌더링하므로 위의 한계가 그곳에서는 영구적이며, 경고가 할 일을 명명할 수 없습니다. 리터럴로 전달되는 값에 대한 권고와 마찬가지로, 이것은 경고이며 결코 중단이 아니고, 렌더링된 바이트를 바꾸지 않으며, 고유한 코드 sensitivity-not-conveyed를 가진 별도의 분류이고, --no-unsupported-field-warnings로 끄지 않습니다. Warnings and Linter Output (경고 및 린터 출력)에 전체 형태가 있습니다.

선언을 읽는 곳과 읽지 않는 곳

키워드는 그것이 놓인 노드에서 읽히며, 이후 선언이 해당 데이터에 도달할 수 있는 모든 경로를 따라갑니다. 즉 중첩된 속성 맵, 각 합성 분기, 그리고 $ref의 대상입니다. 분기와 참조 대상은 모두 그것을 가진 속성 위에 합성되므로, 어느 쪽을 통해 발견된 선언이든 그 속성에 대해 수집됩니다. 경로를 확장하는 것은 properties 하강뿐입니다.

마커는 이러한 키워드 옆에 있든 키워드가 도달하는 곳 안에 있든 읽히므로, 다음 두 형태는 의도적으로 배치할 필요가 없습니다:

  • $ref 옆, 또는 참조 대상 안. 참조하는 리프에 있는 마커는 그 리프를 선언합니다. 참조된 스키마에 있는 마커도 참조하는 리프에 대해 수집되며, 그 리프의 경로에 그 아래의 체인을 더한 위치에서 수집됩니다. 작성된 값이 존재하지 않는 정의 내부의 경로에서는 결코 수집되지 않습니다.
  • 합성 키워드(allOf / anyOf / oneOf) 옆, 또는 분기 자체의 properties 안. 분기는 그것을 가진 객체 위에 합성되므로, JSON Schema로 작성된 노드의 조건부 분기를 포함하여 모든 분기로 하강하며, 분기 안의 선언은 합성하는 속성 자체의 경로에 그 체인을 더한 위치에서 수집됩니다.

한 가지 형태는 마커를 의도적으로 배치해야 합니다:

  • 배열 리프 자체에, 그 items 요소 타입이 아닌 곳에. 요소가 민감한 내용을 담는 배열은 배열에서 민감으로 선언합니다. 요소 타입은 속성 맵이 아니며 그 안으로 하강하지 않기 때문입니다.

parameters:는 다른 어휘입니다

sensitive는 parameters: 타입 계약 어휘에 속하지 않습니다. 파라미터 항목에 이를 선언한 Aggregate는 Aggregate가 로드될 때 거부되며, 문제가 된 키 자체에 위치한 unexpected property: "sensitive"를 보고하는 문서 엔벨로프 진단이 표시됩니다. 파라미터 계약은 닫힌 객체이므로, 이는 해당 어휘 밖의 어떤 키든 받는 것과 같은 처리입니다.

이 비대칭은 의도된 것입니다. 민감도 축은 카탈로그 엔터티가 선언하는 세 가지 데이터 기둥을 다루며, 파라미터는 기둥의 리프가 아니라 환경 계약 입력입니다. 파라미터를 통해 자격 증명 내용을 끌어올리는 방법은 architecture/08-credential-model.md의 “Legacy charts that demand a formatted string” 항목에 문서화되어 있으며, 그 경로가 감수하는 트레이드오프도 그곳에 설명되어 있습니다.

allOf, anyOf, oneOf를 사용한 합성

합성 키워드는 JSON Schema에서와 동일하게 동작합니다.

# Inherit and extend
secondary:
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 }

컴파일러는 해석된 JSON Schema에 동일한 합성 키워드를 출력합니다. 합성되는 각 항목은 compact form, JSON Schema, 또는 $ref: 참조 중 어느 것이든 될 수 있습니다. 하나의 합성 안에서 이들을 섞어 쓰는 것도 지원됩니다.

탈출구 — $jsonschema:

compact form의 어휘를 넘어서는 경우($dynamicRef, unevaluatedProperties, 깊은 not: 합성, 재귀 타입)에는 어떤 노드든 완전한 JSON Schema로 전환할 수 있습니다:

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: 블록에는 JSON Schema YAML이 들어갑니다. 컴파일러는 이를 투명한 패스스루로 처리하며, 그 내용은 해당 노드의 위치에 그대로 해석된 JSON Schema 문서로 들어갑니다. 검증, 오류 보고, 도구는 모두 해석된 문서를 대상으로 동작합니다. 이 탈출 방식은 순전히 작성 편의를 위한 것입니다.

not: 분기는 그것이 제외하는 형태가 왜 거부되는지 설명하는 description:을 가질 수 있습니다. 그러면 그 분기와 일치하는 값은 일반적인 “not allowed here(여기서는 허용되지 않음)” 문구 대신 그 설명을 이유로 하여 한 줄로 출력되며 거부됩니다 — 따라서 거부된 값의 작성자가 읽어야 할 문장으로 작성하십시오. not: 분기 자체에 작성된 설명만 사용되며, 분기가 참조만 하는 $defs 항목에 작성된 설명은 사용되지 않습니다.

블록 안의 모든 노드는 JSON Schema로 읽히며, 그 안에 작성된 컴팩트 형식 키워드는 컴팩트 형식의 의미를 유지합니다(문자열의 min: 3은 여전히 최소 길이입니다). 블록 안의 $ref는 블록 밖에서와 같은 방식으로 해석됩니다. #/$defs/Foo는 필러의 $defs: 항목을 가리키므로 예제에서는 그곳에 Foo를 선언하며, 아무도 선언하지 않은 항목을 가리키는 참조는 엔터티를 로드할 때 거부됩니다. $dynamicRef는 $dynamicAnchor를 기준으로 해석되므로 재귀적인 형태를 작성할 수 있습니다. 재귀 깊숙한 곳에서 실패한 값은 그것을 담은 필드에서 보고됩니다. children 항목이 { $dynamicRef: "#node" }인 트리에서 두 단계 아래의 잘못된 name은 tree.children에서 보고됩니다.

unevaluatedProperties와 unevaluatedItems에는 한 가지 제한이 있습니다. 참조, 합성 키워드(allOf, anyOf, oneOf), 조건 또는 종속 스키마도 함께 가진 노드에 작성하면 둘 다 로드되지만 강제되지 않습니다. 또한 unevaluatedItems는 contains 옆에서도 강제되지 않습니다. 위 예제에서 unevaluatedProperties: false는 allOf 옆에 있으므로, Foo와 patternProperties 어느 쪽도 extra를 선언하지 않았는데도 { name: n, extra: 1 }이 허용됩니다.

$jsonschema: 탈출은 문서 단위가 아니라 노드 단위입니다. 하나의 스키마에서 단순한 부분에는 compact form을, 복잡한 필드 하나에는 JSON Schema 탈출을, 공유되는 형태에는 $ref:를 사용할 수 있으며, 이 모두를 한 문서 안에서 쓸 수 있습니다.

하나의 문서에서 compact form과 JSON Schema 혼용하기

compact form과 JSON Schema는 어느 노드 경계에서든 자유롭게 혼용할 수 있습니다. 디스패치 규칙은 내용의 형태에 따라 결정됩니다.

  • $jsonschema:를 포함하는 노드는 JSON Schema(탈출구)로 처리됩니다.
  • JSON Schema 스타일의 최상위 키워드(type:, properties:, additionalProperties:, if: 등)를 포함하는 노드는 JSON Schema(명시적 형식)로 처리됩니다.
  • 속성 이름 → 하위 스키마 항목만 포함하는(JSON Schema 예약 키워드가 없는) 노드는 compact form(추론 형식)으로 처리됩니다.
  • $ref:만 있는 노드는 참조 패스스루입니다.
  • allOf: / anyOf: / oneOf:가 있는 노드는 합성이며, 각 항목은 독립적으로 디스패치됩니다.

compact form 리프의 표준 패턴은 field_name: { type: ..., constraints... }입니다. 즉 알려진 compact form 어휘를 포함하는 YAML 맵입니다. 디스패치는 제약 조건 딕셔너리를 그 키로 인식합니다.

드물게 모호한 경우(예: 추론 형식 디스패치가 JSON Schema 키워드로 해석할, 이름이 말 그대로 type인 필드를 가진 compact form 스키마)에는 명시적 형식이 표준적인 해결책입니다. 위의 “모든 추론 형식 범위의 예약 키워드”를 참조하십시오.

파일에서 계약 가져오기 — $import:

계약이 반드시 그것을 선언하는 엔터티 안에 있어야 하는 것은 아닙니다. $import:는 계약을 읽어 올 파일을 지정합니다:

spec:
schema:
$import: ./contracts/api-server.schema.yaml

그러면 spec.schema 전체가 해당 파일에서 오며, 이 파일은 대체하는 블록과 정확히 같은 방식으로 작성합니다. 최상위에 필러를 두고, 그 아래에 compact form 또는 JSON Schema YAML을 둡니다:

contracts/api-server.schema.yaml
values:
greeting: { type: string, enum: [hello, howdy], default: hello }
infra:
image_tag: { type: string, default: "1.0" }
provides:
host: { type: string }

필러 하나만 따로 가져오고, 그 형제 필러는 옆에 인라인으로 작성할 수도 있습니다:

spec:
schema:
values:
$import: ./contracts/values.yaml
infra:
image_tag: { type: string, default: "1.0" }

같은 형식은 usesSchema: 소켓의 valueSchema:와 infraSchema:에서도 동작합니다.

이를 규정하는 규칙은 다음과 같습니다:

  • $import:는 그것이 나타나는 위치의 유일한 키입니다. 그 옆에 작성한 형제 키는 둘 중 하나를 버리는 대신 거부됩니다.
  • 상대 경로는 그것을 선언한 엔터티 파일이 있는 디렉터리를 기준으로 읽으며, 빌드를 실행하는 디렉터리를 기준으로 읽지 않습니다. 이는 valuesMapping:, workload:, artifacts:가 사용하는 것과 같은 기준입니다. 경로는 그 디렉터리 안에 머물러야 합니다. 엔터티의 게시본이 담는 모든 파일을 그곳에서 가져오기 때문입니다. 그 디렉터리 밖으로 올라가는 경로나 절대 경로는 엔터티와 함께 이동하지 않을 파일을 가리키므로 거부됩니다. A path names content outside the entity’s own directory (경로가 엔터티 자체 디렉터리 밖의 콘텐츠를 가리킴)를 참조하십시오. 여러 엔터티가 공유하는 스키마는 SchemaLibrary에 두고 $ref:로 참조합니다.
  • 가져온 파일은 엔터티와 함께 이동합니다. 게시된 엔터티는 스키마가 가져오는 각 파일을 체인의 모든 파일까지 포함하여 담으므로, 레지스트리에서 가져온 사본도 같은 계약을 읽고 그에 맞춰 작성된 값을 검증합니다. aggrega push를 참조하십시오.
  • 가져온 파일은 엔터티 문서가 아니라 스키마 콘텐츠를 담습니다. 콘텐츠가 YAML 맵이 아닌 파일은 해당 파일을 명시하며 거부됩니다.
  • 가져온 파일 자체가 단일 $import:일 수 있으며, 이는 재귀적으로 해석됩니다. 이미 읽고 있는 파일로 되돌아가는 체인은 해당 체인을 명시하며 거부됩니다.

가져오기는 엔터티를 로드할 때 읽으므로, 그 엔터티를 읽는 모든 표면이 같은 계약을 봅니다: aggrega validate, 빌드, aggrega push, aggrega inspect, 그리고 에디터입니다. 읽을 수 없는 파일이나 스키마가 아닌 콘텐츠는 계약을 적용하지 않은 채로 두는 대신 그 시점에 거부되며, push는 무엇이든 게시하기 전에 이를 거부합니다.

$import:와 $ref:는 서로 바꿔 쓸 수 없습니다. $import:는 파일을 지정하고 콘텐츠 전체를 대체합니다. $ref:는 SchemaLibrary 항목을 식별자로 지정하고 어떤 노드에서든 합성됩니다. 라이브러리 식별자나 레지스트리 호스트를 담은 $import: 값은 $ref:를 사용하라는 안내와 함께 거부됩니다. cross-document-ref.md를 참조하십시오.

Aggrega 확장 네임스페이스 — x-aggrega-*

압축 형식은 x-aggrega- 접두사가 붙은 모든 키워드를 Aggrega 전용 확장으로 인식합니다. 이 네임스페이스는 열려 있으므로, 새 주석이 키워드별 어휘 수정 없이 카탈로그에 추가됩니다. x-aggrega-selector, x-aggrega-narrowed-from 또는 향후 추가될 주석을 작성하면, 컴파일 시점에 거부되지 않고 해석된 JSON Schema의 올바른 범위에 그 내용이 들어갑니다.

네임스페이스 접두사는 중요합니다. x-agrega-source(g 하나 누락)와 같은 오타는 확장 키워드로 인식되지 않으며, 추론 형식 범위의 닫힌 객체 의미론에 의해 거부됩니다. 접두사 범위는 카탈로그의 주석 영역에 대한 오타 검출망 역할을 합니다.

특정 x-aggrega-* 주석은 파이프라인의 잘 알려진 지점에서 컴파일러가 생성합니다.

  • x-aggrega-selector: — usesSchema: 및 featuresSchema: 합성이 호환되는 provider Components를 대상으로 하는 선택자 문자열을 담기 위해 생성합니다.
  • x-aggrega-sensitive: — sensitive: true를 선언한 리프가 생성합니다. 위의 리프를 민감 항목으로 선언하기를 참조하십시오.

자체 확장 키워드를 작성하는 카탈로그 작성자도 같은 네임스페이스를 사용합니다. 컴파일된 JSON Schema를 사용하는 다운스트림 도구는 JSON Schema 자체의 키워드 공간과 충돌하지 않고 x-aggrega-* 키를 읽습니다.

작업 예제 — MariaDB Component 스키마

MariaDB 데이터 저장소를 위한 대표적인 축약형 Component 스키마입니다. 전체에 걸친 추론 형식, 혼합된 리프 제약 조건, 참조, 조건부 형태, 그리고 인증 블록에 대한 oneOf 작업 예를 보여 줍니다.

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로 작성하면 같은 계약에서 모든 객체의 type: object, properties:, additionalProperties: false를 일일이 적고 각 필수 필드를 상위의 required:에 다시 나열해야 하므로 훨씬 길어집니다. 이러한 간결성의 이점은 더 큰 Component 계약에서 누적되며, 축약형을 schema:, parameters: 및 SchemaLibrary 항목의 기본 작성 방식으로 삼을 만큼 의미가 있습니다.

교차 참조

  • 문서 간 $ref: 해석 의미론(문서 간 참조 옆에 두는 required: 구문, 라이브러리 간 체인 확장, 소비자에 의한 라이브러리 좁히기)에 대해서는 cross-document-ref.md를 참조하십시오.
  • assertions: 블록 작성 문법(compact form의 validate:로 표현할 수 없는 필드 간 규칙)에 대해서는 templates/assertions-block.md를 참조하십시오.
  • compact form 스키마를 담는 데이터 기둥 집합(values:, infra:, provides:, uses:, features:, locals:, parameters:)에 대해서는 data-pillars.md를 참조하십시오.
  • OCI URI 축약형 확장 규칙(도메인 기본값, 레지스트리 세그먼트, 버전 폴백, 게시자 확장)에 대해서는 uri-grammar.md를 참조하십시오.
  • SchemaLibrary 엔터티 작성($ref:로 참조할 수 있는 스키마가 카탈로그에서 위치하는 곳)에 대해서는 ../entities/schemalibrary.md를 참조하십시오.