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

SchemaLibrary

SchemaLibrary는 재사용 가능한 JSON Schema 2020-12 정의와 선택적인 매개변수화된 헬퍼를 담는 카탈로그 엔터티입니다. 스키마 형태(URL, 기간, 공통 프로브 구조, 반복되는 리소스 제한)를 공유하는 Components와 Features는 그 형태를 라이브러리에 한 번 선언하고 정규 $ref URI로 참조합니다. 이 라이브러리 엔터티는 Tier 3에 해당하며, Component 간 스키마 재사용이 필요한 카탈로그가 선택적으로 사용합니다. 반복되는 스키마 내용이 없는 카탈로그는 SchemaLibrary 없이 배포됩니다.

SchemaLibrary의 역할

플랫폼 아키텍트는 카탈로그 전반에서 반복되는 스키마 형태를 한곳에 모으기 위해 SchemaLibraries를 작성합니다. 라이브러리는 배포 가능한 구성 요소가 아니라 정의 네임스페이스입니다. Component / Feature 작성자는 라이브러리 항목을 정규 $ref URI로 참조하며, 이 항목은 한 번 정의되고 참조가 해석되는 모든 곳에서 검증됩니다.

“라이브러리”와 “소비자”를 분리한 것은 의도된 설계입니다. Components는 인스턴스가 채우는 계약(그 values, infra, provides, 소켓, 자격 증명 슬롯)을 선언합니다. Features는 동작상의 부착 요소를 표현합니다. SchemaLibraries는 스키마 내용, 즉 값이 충족해야 하는 구조적 규칙만 표현합니다. 세 역할을 구분해 두면 각 엔티티 종류가 각자의 주기로 발전할 수 있으며, 공유 스키마 정의가 필요 없는 작성자는 라이브러리 엔티티를 접할 일이 없습니다.

엔티티 엔벨로프

SchemaLibrary 엔티티는 표준 카탈로그 엔벨로프를 가집니다. apiVersion: aggrega.ai/v1beta1과 kind: SchemaLibrary는 엔티티 종류를 나타내고, metadata.name은 PascalCase 식별자이며, metadata.version은 엄격한 시맨틱 버전 관리를 따릅니다. 라이브러리의 내용은 spec 아래에 위치합니다. spec.schemas는 필수이며(라이브러리는 최소 하나의 항목을 선언해야 합니다), spec.templates는 선택 사항입니다(라이브러리가 매개변수화된 헬퍼를 사용할 때만 존재합니다).

apiVersion: aggrega.ai/v1beta1
kind: SchemaLibrary
metadata:
name: WebPrimitives
version: 1.0.0
spec:
schemas:
URL:
type: string
pattern: "^https?://"
HTTPMethod:
type: string
enum: [GET, POST, PUT, PATCH, DELETE]

스키마 항목 작성

스키마 항목은 세 가지 형식 중 하나로 작성합니다. 간결 형식은 짧고 흔한 형태 — type, pattern, enum, min, max 및 이와 비슷한 한 줄 제약 — 를 위한 기본 표면입니다. JSON Schema 2020-12 YAML은 JSON Schema의 전체 표면(조합 키워드, 조건부 형태, 복잡한 $defs)이 필요한 항목을 위한 동등한 작성 방식입니다. 한 항목 안에서 두 형식을 섞는 것은 간결 형식 컴파일러의 노드별 내용 형태 디스패치를 통해 지원되며, 간결 형식으로 의도를 표현할 수 없을 때는 $jsonschema: 탈출구로 어느 노드에든 전체 JSON Schema 내용을 삽입할 수 있습니다.

항목 안의 format은 어떤 스키마에서든 검사하는 것을 똑같이 검사합니다. email, uri, hostname, ipv4, ipv6, uuid, date-time, date 중 하나를 지정하며, 소비자가 해당 필드에 제공하는 값은 그 형식이 아니면 거부됩니다. vocabulary/compact-form-authoring.md를 참조하십시오. 그 밖의 형식을 지정하는 항목은 — password도 포함하여 — 라이브러리를 로드할 때 거부됩니다. 따라서 카탈로그 전체에 대한 aggrega validate는 아직 그 항목을 참조하는 것이 있든 없든 이를 거부하면서 라이브러리, 항목, 형식 이름을 밝히고 지원되는 형식을 나열하며, Release가 그 라이브러리에 도달하는 빌드나 풀은 이 지점에서 중단됩니다. 다른 라이브러리를 참조하는 항목은 Component 또는 Feature 필러가 그 항목을 소비하는 곳에서 판정됩니다. 비밀 정보를 담는 필드는 형식 대신 sensitive: true를 선언합니다.

템플릿과 $instantiate:

반복되는 구조가 많은 라이브러리는 spec.templates 아래에 매개변수화된 헬퍼를 선언합니다. 템플릿은 $params: 맵(이름과 타입이 지정된 매개변수 선언)과 본문(매개변수를 $<paramName> 스칼라 토큰으로 참조하는 compact form 또는 JSON Schema 콘텐츠)을 가집니다. 스키마 항목은 $instantiate: + $args: 바인딩으로 템플릿을 인스턴스화합니다. 치환 엔진은 매개변수 자리 표시자를 리터럴 스칼라 값으로 바꾸고, 해석된 항목의 본문을 생성합니다.

spec:
schemas:
LivenessProbe:
$instantiate: ProbeTemplate
$args:
port: 8080
path: /healthz
ReadinessProbe:
$instantiate: ProbeTemplate
$args:
port: 8081
path: /ready
templates:
ProbeTemplate:
$params:
port:
type: integer
path:
type: string
type: object
properties:
port:
type: integer
const: $port
path:
type: string
const: $path

치환은 리터럴 스칼라에 대해서만 이루어집니다. 치환 엔진은 Go 템플릿 구문을 해석하지 않으며, 조건문을 평가하거나 루프를 실행하지 않습니다. 더 표현력 있는 헬퍼가 필요한 작성자는 라이브러리 항목을 소비하면서 자체적인 변형을 더하는 Components 또는 Features를 구성합니다.

명명 관례

라이브러리 이름, 스키마 항목 키, 템플릿 이름은 PascalCase를 따릅니다. 엔티티 엔벌로프의 JSON Schema는 패턴 제약을 통해 세 위치에서 이 관례를 강제합니다:

  • metadata.name은 ^[A-Z][A-Za-z0-9]*$와 일치해야 합니다.
  • spec.schemas 맵 키는 propertyNames를 통해 같은 패턴과 일치해야 합니다.
  • spec.templates 맵 키는 propertyNames를 통해 같은 패턴과 일치해야 합니다.

spec.schemas 또는 spec.templates에 PascalCase가 아닌 키가 있는 SchemaLibrary는 워크스페이스 로드 시 엔벌로프 검증에 실패합니다. 엔벌로프 수준의 강제는 중요한 역할을 합니다. 스키마 항목 키는 정규 $id URI(#/schemas/<name>)에 나타나고, 템플릿 이름은 인스턴스화 시점에 정규 URI를 참조합니다. 로드 시점에 PascalCase가 아닌 키를 잡아내면 그런 키가 카탈로그 생태계 전반으로 퍼지는 것을 막을 수 있습니다.

템플릿의 $params: 맵 안의 매개변수 이름은 템플릿 로컬입니다. 이 이름은 정규 $id URI에 나타나지 않으며 엔벌로프 수준에서 패턴 제약을 받지 않습니다. 작성자는 템플릿의 매개변수에 맞는 어떤 명명 관례든 따를 수 있으며, port, path, intervalSec처럼 소문자로 시작하는 매개변수 이름이 일반적입니다.

라이브러리, 스키마, 템플릿 수준에서 명명이 통일되어 있으므로 참조 식별자를 깔끔하게 훑어볼 수 있습니다. WebPrimitives#/schemas/URL은 한눈에 읽힙니다.

문서 간 $ref: 해석 의미론, 즉 $ref:가 SchemaLibrary 경계를 넘어 해석되는 방식, $ref:를 가진 소비자에 대한 required: 구문 구분, 라이브러리 간 체인 확장, 소비자가 라이브러리를 좁히는 동작에 대해서는 vocabulary/cross-document-ref.md를 참조하십시오.

라이브러리 항목 참조

Component / Feature 작성자는 라이브러리 항목을 식별자, 즉 이름만 쓴 형식인 <Library>#/schemas/<name>으로 참조합니다:

# Inside a Component schema:
spec:
schema:
values:
healthCheck:
$ref: "WebPrimitives#/schemas/URL"

라이브러리 이름은 해석된 카탈로그를 기준으로 해석되고, #/schemas/<name> 프래그먼트가 항목을 선택합니다. 참조에는 레지스트리 호스트가 포함되지 않습니다. 작성자는 선택적으로 최소 버전 하한을 <Library>:<version>#/schemas/<name>으로 지정할 수 있지만(버전 구분자는 :이며, recipe/feature 매핑 및 lockfile 고정과 일치합니다), 해석되는 버전은 Release별 lockfile이 제공합니다. 이 lockfile은 사용되는 각 라이브러리를 이름 + 버전 + 콘텐츠 다이제스트로 고정합니다. 레지스트리 호스트를 포함한 참조, 즉 oci://<host>/… 형식은 컴파일 시 거부되며, 작성자를 식별자 형식으로 안내하는 진단이 출력됩니다. 따라서 물리적인 레지스트리 위치는 작성된 소스에 들어가지 않습니다. 라이브러리의 바이트가 어디에서 제공되는지(로컬 카탈로그 디렉터리, 콘텐츠 캐시 또는 원격 레지스트리)는 리졸버가 다룰 문제이며 해석 시점에 결정됩니다. 레지스트리를 옮기는 것은 소스 변경이 아니라 리졸버 구성 변경입니다.

금지된 JSON Schema 키워드

JSON Schema 2020-12의 $dynamicAnchor 및 $dynamicRef 키워드는 SchemaLibrary 항목에서 금지됩니다. SchemaLibrary 파서는 워크스페이스 로드 시점에 스키마 항목과 템플릿 본문을 모두 검사하고, 게시 린터는 게시 시점에 중복 방어를 적용하며, 인스턴스화 엔진은 매개변수 치환 후 해석된 본문을 다시 검사하므로, 매개변수 값을 통해 금지된 키워드를 몰래 들여오는 템플릿도 실패합니다. 세 가지 검사가 함께 정적 도입 경로(스키마 항목이나 템플릿 본문의 리터럴 $dynamicAnchor), 매개변수 도입 경로($dynamicRef를 포함하는 $args: 값), 대역 외 도구를 통한 우회 경로(게시 시점 방어가 파서를 건너뛴 모든 것을 잡아냄)를 차단합니다.

거부가 발생하면 오류는 문제가 된 키워드와 파일 경로를 명시합니다. 작성자는 첫 인스턴스화 시점이 아니라 작성 시점에 오류를 확인하며, 템플릿 본문도 로드 시점 검사에서 제외되지 않습니다.

동적 참조 의미론은 컴파일러의 컴파일 시점 결정성 계약을 깨뜨리는 방식으로 런타임 평가와 결합됩니다. 동적 참조 동작이 필요한 작성자는 정적 $ref 해석을 사용하도록 스키마를 재구성합니다. 이 검사에는 예외 적용이 없습니다.

계층 배치

SchemaLibrary는 엔터티 계층 문서화 모델에서 Tier 3에 해당하며, Component 간 스키마 재사용이 필요한 카탈로그가 선택적으로 사용합니다. 반복되는 스키마 내용이 없는 카탈로그는 SchemaLibrary 엔터티 없이 배포됩니다. 계층 표시는 기능이 아니라 문서 탐색을 위해 “고급 항목이므로 필요하지 않으면 건너뛰어도 됨”을 알리는 것입니다. 컴파일러는 SchemaLibrary를 다른 카탈로그 엔터티 종류와 동일하게 취급합니다. 워크스페이스 로드 시 동일한 엔벌로프 검증을, 항목별 내용에는 동일한 JSON Schema 2020-12 파이프라인을, 릴리스 시에는 동일한 OCI 게시 파이프라인을 적용합니다.

Tier 3 안에서도 spec.templates 매개변수화 헬퍼 메커니즘 자체는 선택 사항입니다. 반복되는 구조가 많은 라이브러리(포트 + 경로로 매개변수화된 Probe 템플릿, 허용 출처로 매개변수화된 CORS 템플릿, 인증서 + 키 경로로 매개변수화된 TLS 템플릿)는 templates 재사용의 이점을 얻습니다. 일회성 항목이 다양한 라이브러리는 템플릿 블록을 완전히 생략하고 각 항목을 spec.schemas 아래에 인라인으로 작성합니다.