검증 범위
Aggrega는 작성된 콘텐츠를 서로 다른 네 개의 스키마 계층에서 검증합니다. 각 계층은 다루는 범위가 다르고, 컴파일 파이프라인의 서로 다른 지점에서 실행되며, 서로 다른 형태의 오류를 생성합니다. 검증 오류를 만난 작성자는 어느 계층이 입력을 거부했는지 알면 도움이 됩니다. 같은 필드가 둘 이상의 계층의 적용을 받을 수 있으며, 어느 계층에서 오류가 발생했는지에 따라 무엇을 어디서 고쳐야 하는지가 정해지기 때문입니다.
이 페이지는 네 개의 계층, 각 계층의 파이프라인상 위치, 각 계층이 따르는 오류 형태 관례, 그리고 같은 필드에 둘 이상의 계층이 적용될 때 계층들이 상호작용하는 방식을 설명합니다.
네 가지 계층
계층 1 — JSON Schema 엔벨로프
범위. 모든 카탈로그 YAML의 구조적 형태: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, 최상위 spec: 블록, 그리고 스키마가 선언하는 엔티티별 필수 필드입니다. 각 엔티티 종류(Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary)는 자체 JSON Schema를 가지며, 이는 스키마 참조에 문서화되어 있습니다. Workload도 그곳에 스키마가 있으며, 이 집합에서 작성자가 독립된 카탈로그 파일이 아니라 다른 엔티티 안에 작성하는 유일한 종류입니다. 즉 Recipe나 FeatureRecipe의 workload: 블록, 또는 WorkloadLibrary 항목 안에 작성합니다. 어디에 작성되든 동일한 엔벨로프 검사가 적용되며, aggrega validate는 Workload 파일을 단일 엔티티 대상으로 직접 받아들입니다.
검증 시점. 해석(resolver / load) 단계에서 파일별로 실행됩니다. 각 문서는 로드될 때 해당 종류의 JSON Schema에 대해 검사되며, 스키마가 선언한 필드 밖의 키는 이후의 검증이 실행되기 전에 그 자리에서 거부됩니다.
오류 형태. 스키마 불일치는 문서 엔벨로프 실패로 보고됩니다. 그 머리에는 문제가 있는 문서의 범주가 붙습니다. 카탈로그 엔티티는 [CATALOG_ERROR E0215], Aggregate는 [DEVELOPER_ERROR E0215], Release는 [OPS_ERROR E0215]이며, 메시지는 종류, 파일, 행과 열, 필드 경로, 위반된 제약 조건을 명시합니다:
[CATALOG_ERROR E0215] <path> document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schema필수 필드 누락과 타입 불일치도 같은 형태로 드러납니다 — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".
계층 2 — 필러 스키마(schema: / featuresSchema / usesSchema)
범위. 엔티티가 담는 데이터 필러 — values, infra, parameters, 그리고 featuresSchema가 슬롯을 선언하는 features: 연결 블록과 usesSchema가 관할하는 uses: 블록입니다. 도메인 2 엔티티(Component, Feature)는 YAML 엔벨로프에 JSON Schema 2020-12 선언을 포함합니다(인라인 spec.schema — 축약형 또는 전체형 — 또는 공유 SchemaLibrary 항목을 가리키는 $ref:). 도메인 3 엔티티(Recipe, FeatureRecipe)는 자체 검증 단계에서 해석된 스키마를 사용합니다.
검증 시점. 해석 단계에서, JSON Schema 엔벨로프 검사를 통과한 후에 실행됩니다. 컴파일러는 엔티티에 작성된 schema:를 usesSchema 및 featuresSchema 선언에서 파생된 자동 생성 기반 스키마와 합성하며, 합성된 스키마는 Aggregate의 모든 컴포넌트 인스턴스에서 개발자가 제공한 values: / infra: / features: / uses: 블록을 검증합니다.
오류 형태. 제약 위반은 엔티티, 필러 내부의 경로, 값을 거부한 규칙을 명시하는 메시지로 드러납니다. 예를 들어 개발자가 >=1024를 요구하는 스키마 규칙에 대해 포트를 80으로 설정한 경우입니다.
재선언된 usesSchema 또는 featuresSchema 항목은 합성 실패를 일으키지 않습니다. 이 두 범위는 이름으로 덮어씁니다. 자식의 항목이 기반의 항목을 스키마와 선택자까지 통째로 대체하므로, 보고할 기반 항목과 자식 항목 사이의 충돌이 없습니다.
계층 3 — Provider 합성 모드 기능
범위. 바인딩된 프로바이더의 합성 모드 기능 게이트가 관할합니다:
- 합성 모드(
workload:) 지원은workloadSchema의 존재 여부가 아니라 바인딩된 프로바이더의 기능에 따라 허용됩니다. 합성할 수 없는 프로바이더에 바인딩된workload:Recipe는 여기서 거부됩니다. 표준 라이브러리 카탈로그는 관례에 따라 합성 가능한 프로바이더에 — 프로바이더 렌더링 Plugin의spec.provider.workloadSchema에 — 문서화된 변환 계약으로서workloadSchema를 선언합니다. 이workloadSchema본문 자체는 Plugin이 로드될 때 JSON Schema 2020-12로 컴파일되며, 이는 잘못된 스키마를 렌더링 시점이 아니라 로드 시점에 거부하는 구조적 수용 게이트입니다.
검증 시점. 기본 렌더링 단계에서, Recipe 자체의 valuesMapping이 해석된 후에 실행됩니다. 계층 3은 프로바이더 기능에 따라 합성 모드 디스패치를 허용합니다.
오류 형태. 기능 거부는 카탈로그 작성 도메인에 귀속되므로, 보고서는 해당 범주와 문제가 된 인스턴스를 담은 대괄호 헤드로 시작합니다. 메시지는 조건을 기술하는 고정 문장으로 시작하고, 이어서 노드, 프로바이더, 그리고 해당 프로바이더가 지원하는 종류를 명시합니다:
[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesized[CATALOG_ERROR] 헤드는 개발자의 Aggregate가 아니라 카탈로그 엔티티에 문제가 있음을 나타냅니다. 터미널에서는 헤드에 조건의 짧은 코드도 함께 표시되며 — 이 조건의 경우 E0265로, 모든 조건의 표에서 찾을 수 있습니다 — 메시지는 들여쓴 별도의 줄로 이동합니다. 위의 한 줄 형태는 로그에 기록되는 형태입니다. 첫 문장은 조건별로 고정되어 있으므로 텍스트를 기준으로 작업할 때 일치시킬 부분이며, 그 뒤의 내용은 문제가 된 노드에 따라 달라집니다.
관련된 안전장치가 프로바이더 디스패치 자체를 보호합니다. 둘 이상의 프로바이더 렌더링 Plugin이 같은 대상을 처리하는 경우, 워크스페이스는 .aggrega-config.yaml의 프로바이더 바인딩으로 모호성을 해소하며, 이 바인딩은 aggrega pull 시점에 선택되어 lockfile에 기록됩니다. 바인딩이 없고 후보 Plugin이 정확히 하나이면 그 후보가 사용되며, 바인딩이 없고 후보가 둘 이상이면 빌드는 후보 플러그인을 명시하며 명확하게 중단됩니다. 모호성은 카탈로그 전체의 고유성 규칙이 아니라 사용 시점에 워크스페이스별로 해소됩니다.
provider별 Workload 내용 검증. provider를 렌더링하는 Plugin의
spec.provider.workloadSchema는 provider가 Workload를 어떻게 변환하는지 문서화하고 그 provider가 Workload를 합성할 수 있음을 표시할 뿐, 아무것도 검증하지 않습니다. 모든 Workload 본문은 provider와 관계없이 플랫폼의 Workload 스키마에 대해 검증됩니다.
계층 4 — 어노테이션 바인딩 값 검증
범위. mappings.features.annotations.<key> 아래의 Manifest 바인딩이 maps.infra 및/또는 maps.values 점 표기 경로 목록을 통한 라우팅을 선언할 때, Release 경계 / 경계 컴포넌트 또는 Aggregate 서브시스템 / 컴포넌트 인스턴스에 작성된 어노테이션 값입니다. 선언된 각 경로는 대상 Feature의 spec.schema.<pillar>를 따라 리프 속성까지 탐색하며, 해당 리프에 대한 어노테이션 값의 기여분은 Feature 스키마에 선언된 타입에 대해 검증됩니다. 검증은 Feature 자체의 JSON Schema 2020-12 선언을 통해 이루어지며, 바인딩은 라우팅만 선언하고 검증 조각은 선언하지 않습니다.
검증 시점. 해석의 어노테이션 확장 하위 단계에서, Manifest 바인딩 대상 검증(선언된 각 경로가 참조된 Feature 스키마에 존재하는지 확인하는 카탈로그 로드 검사) 이후, 그리고 명시적 연결에 대한 계층 2 스키마 검증과 함께 실행됩니다. 컴포넌트별로 유효한 각 어노테이션에 대해: 값을 스칼라, 구조화된 맵 또는 명시적 null로 파싱하고, 측면 대 필러 강제(Aggregate 측은 maps.values를, Release 측은 maps.infra를 실행)를 적용하여 바인딩의 필러별로 그룹화된 maps 선언을 통해 하위 키별로 라우팅하며, 라우팅된 필러에서 Feature 스키마에 선언된 타입에 대해 리프별 런타임 값을 검증합니다. 여러 하위 키 오류는 중단하기 전에 모두 수집되어 출력됩니다.
오류 형태. 이 계층의 스키마 검증 오류는 계층 2의 형태 — 엔티티, 경로(어노테이션 키와 하위 키 라우트), 제약 세부 정보 — 를 따릅니다. 측면 대 필러 구분 위반과 모호한 라우팅 실패는 어노테이션 값이 작성된 문서에 귀속되므로, Aggregate가 담은 오류는 [DEVELOPER_ERROR] 헤드로, Release가 담은 오류는 [OPS_ERROR] 헤드로 시작하며, 둘 다 어노테이션 키, 라우팅된 필러, 작성 측면, 소스 위치를 명시합니다.
계층 전반에 걸친 하나의 오류 형식 관례
네 계층은 관찰 가능한 하나의 관례를 공유합니다: Aggrega에 귀속되는 모든 검증 실패는 경로와 근거로 이루어진 형태를 가지며, 문제가 된 필드와 그 값을 거부한 제약 조건을 명시합니다.
- 계층 1(엔벨로프)과 계층 2(필러 스키마) 오류는 같은 대괄호 머리로 시작합니다. 이는 문제가 있는 문서의 범주와 조건의 짧은 코드로, 예를 들어 카탈로그 엔티티의 엔벨로프 불일치는
[CATALOG_ERROR E0215], 필러 스키마가 거부하는 Aggregate 값은[DEVELOPER_ERROR E0168]입니다. 그 뒤에 필드 경로와 위반된 스키마 규칙이 이어집니다. - Layer 3(Provider 소스 / Workload) 오류는 정의상 카탈로그 엔터티에 귀속됩니다. 개발자의 입력을 거부한 스키마를 작성한 것이 Recipe + Provider 쌍이기 때문입니다. 이 오류들은 카탈로그 작성 도메인에 귀속되며, 이 귀속은 메시지에 입력된 단어가 아니라 진단의 대괄호 헤드를 통해 전달됩니다: 중단 보고서는
[CATALOG_ERROR E0nnn]로 시작하며, 여기서 범주는 도메인을, 짧은 코드는 조건을 나타냅니다. 한 번 발급되면 고정되는 짧은 코드로 일치 여부를 판단하십시오. - Layer 4(어노테이션 바인딩 값 검증) 오류는 Layer 2의 형태를 따릅니다. 검증하는 Feature 스키마는 참조된 Feature의
spec.schema에 있으며, 런타임 값은 Manifest 바인딩의maps라우팅을 거쳐 해당 스키마로 전달되어 리프별 타입 검사를 받습니다.
Aggrega 접두사가 붙는 센티널과 이를 생성하는 표면의 전체 목록은 errors/error-translation.md를 참조하십시오. 오류별 카탈로그(조건별 [CATALOG_ERROR] Recipe 형태 규칙)는 errors/fatal-halts.md를 참조하십시오.
필드가 겹칠 때의 레이어 간 상호작용
작성된 같은 필드가 둘 이상의 계층의 적용을 받을 수 있습니다. Workload의 containers.<name>.ports.<port>는 Workload 스키마의 구조적 형태의 일부로 계층 1에서 검사됩니다. Workload 내용은 Component 필러가 아니라 Recipe 내부 구조이므로 계층 2는 여기에 닿지 않으며, provider의 workloadSchema는 아무것도 검사하지 않습니다. 따라서 1024 미만의 포트를 거부하는 것과 같은 제약은 Component의 스키마나 어설션에 두어야 하며, 그러면 발동한 계층이 이를 명시합니다.
파이프라인 배치 요약
| 계층 | 범위 | 실행 시점 | 오류 접두사 |
|---|---|---|---|
| 1 — JSON Schema 엔벨로프 | 구조적 형태 (apiVersion, kind, metadata, 최상위 spec) | 해석 (로드) | 문서의 범주와 E0215 — 카탈로그 엔티티는 [CATALOG_ERROR E0215] |
2 — 필러 스키마 (schema: / featuresSchema / usesSchema) | 필러별 데이터 검증 (values, infra, secrets, uses) | 해석 (엔벨로프 이후) | 작성 문서의 범주와 조건의 짧은 코드 — Aggregate 값은 [DEVELOPER_ERROR E0168] |
| 3 — Provider 기능 게이트 | 합성 모드 지원 (provider 기능) | 기본 렌더링 | [CATALOG_ERROR] |
| 4 — 어노테이션 바인딩 값 검증 | Manifest 바인딩의 maps 경로를 통해 대상 Feature의 spec.schema로 라우팅되는 어노테이션 값 기여 | 해석 단계 중 어노테이션 확장 하위 단계 (Layer 2와 함께) | 스키마 검증 오류. side 대 필러 / 모호한 라우팅 표면은 작성 문서 자체의 도메인으로 열립니다 — Aggregate에서는 [DEVELOPER_ERROR], Release에서는 [OPS_ERROR] |
상호 참조
errors/error-translation.md— Aggrega 접두사가 붙은 센티널 목록과 이를 생성하는 표면.errors/fatal-halts.md— 컴파일러가 내보내는 모든 치명적 중단에 대한 오류별 카탈로그.vocabulary/data-pillars.md— Layer 2가 검증하는 데이터 필러(values,infra,parameters,locals,features:,uses:,provides).entities/component.md—schema:/featuresSchema/usesSchema에 대한 Component 작성 표면.entities/plugin.md—spec.provider.workloadSchema에 대한 provider 렌더링 Plugin 작성 표면.entities/manifest.md— Manifest의features.annotations바인딩 표면(Layer 4).providers/well-known-annotations.md— Layer 4가 검증하는 어노테이션 값 파싱, 구조화된 값의 하위 키 라우팅, 하위 키별 null 옵트아웃, 그리고 측면 간 합성.