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

문서 간 `$ref:` 해석

이 페이지는 Aggrega의 스키마 작성 영역에서 문서 간 $ref: 참조가 해석되는 방식을 설명합니다. 즉 $ref:가 문서 경계를 넘어 라이브러리로 이어질 때 Components, Features, SchemaLibrary 항목의 작성자가 보게 되는 동작과, 어떤 작성 형식이 문서 간 확장과 문제없이 동작하는지를 정하는 구문별 required: 규칙을 다룹니다.

$ref:는 JSON Schema 2020-12 네이티브입니다. schema: 콘텐츠(Component, Feature, SchemaLibrary 항목) 안, 축약형 스키마 안, 그리고 usesSchema:와 featuresSchema:가 생성하는 합성된 JSON Schema 계층 안에 나타납니다. 이 페이지는 $ref:가 별도 파일이나 OCI 아티팩트에 있는 SchemaLibrary 항목을 대상으로 하는 문서 간 참조의 경우를 중점적으로 다룹니다.

카탈로그 엔터티 상속(Component가 Component를 확장하는 경우)은 inheritance-and-interface.md를 참조하십시오. Release가 Release를 확장하는 것은 카탈로그에 색인되지 않는 문서에 대한 별개의 메커니즘이며, entities/release.md에 설명되어 있습니다.

$import:는 문서 밖의 내용에 접근하는 또 하나의 키워드이며, 두 키워드는 서로 다른 질문에 답합니다. $ref:는 SchemaLibrary의 항목을 식별자로 지정하며(카탈로그가 이를 해석하고 lockfile이 버전을 제공합니다), 어느 노드에서든 합성됩니다. $import:는 엔터티 옆의 파일을 지정하며, 내용 전체를 그 파일이 담고 있는 내용으로 대체합니다. $import:는 스키마 영역뿐 아니라 valuesMapping:, workload:, artifacts:, parameters:에서도 적용됩니다. 스키마에서의 $import:는 compact-form-authoring.md §“Importing a contract from a file”을 참조하십시오.

$ref: 해석 의미론

$ref:는 JSON Schema 2020-12 표준 해석을 따릅니다. 실제로는 다음과 같은 참조 형태가 사용됩니다.

  • 같은 문서 내의 로컬 프래그먼트: { $ref: "#/$defs/PodResources" } — 스키마의 $defs 아래에 있는 PodResources 항목으로 해석됩니다.
  • 식별자로 지정하는 SchemaLibrary 항목 참조: { $ref: "WebPrimitives#/schemas/URL" } — 이름만 쓰는 <Library>#/schemas/<Entry> 형식입니다. 라이브러리 이름은 해석된 카탈로그를 기준으로 해석되고, #/schemas/<Entry> JSON Pointer 프래그먼트가 항목을 선택합니다. 버전은 참조가 아니라 lockfile이 제공합니다. 참조에는 레지스트리 호스트가 포함되지 않습니다. 호스트를 포함한 oci://<host>/… 형식은 컴파일 시 거부되며, 작성자를 식별자 형식으로 안내하는 진단이 출력됩니다. 따라서 물리적 레지스트리 위치는 작성된 소스에 들어가지 않습니다. 라이브러리의 바이트를 어디에서 제공하는지(로컬 카탈로그 디렉터리, 콘텐츠 캐시 또는 원격 레지스트리)는 해석 시점에 결정되는 리졸버의 관심사이며, 참조의 일부가 되지 않습니다.
  • 파일 경로는 참조 대상이 아닙니다: { $ref: "./schemas/foo.yaml#/definitions/Foo" }는 스키마를 컴파일할 때 거부되며, <Library>#/schemas/<Entry> 형식을 안내하는 진단이 출력됩니다. 엔터티 옆의 파일에 둔 스키마 내용은 대신 $import:로 가져오며, 이는 엔터티가 읽는 모든 파일과 마찬가지로 엔터티 자신의 디렉터리로 범위가 제한됩니다.

참조는 컴파일 시점에 해석됩니다. 확장기는 참조된 내용을 소비자의 스키마에 인라인으로 삽입하며, 렌더링된 IR에는 간접 참조가 아니라 인라인된 내용이 담깁니다.

$ref:는 JSON Schema의 합성 키워드와 자연스럽게 조합됩니다.

secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }
- description: "Replication-mode secondary instances."

allOf는 참조된 NodePool 형태를 추가 제약 조건과 합성합니다.

문서 간 $ref:에서의 required: 구문

카탈로그 작성자는 Component 또는 Feature에 필수 속성을 선언할 때 두 가지 작성 형태 중 하나를 선택합니다. 리프 수준 마커(각 속성에 required: true) 또는 상위 수준 배열(객체 범위에 required: [name1, name2, ...])입니다. 두 형태 모두 JSON Schema 2020-12에서 유효하며, 이 섹션에서 보여 주는 위치에 작성하면 문서 간 $ref: 확장에서도 둘 다 반영됩니다.

$ref: 없는 추론 형식 작성 — 리프 수준 마커는 컴파일 시점에 누적됩니다. 컴파일러는 각 속성을 순회하며, 리프에 required: true가 있으면 합성된 상위 객체의 required: 배열에 해당 속성 이름을 추가합니다.

spec:
schema:
values:
database: { type: string, required: true }
display_name: { type: string, required: true }
default_locale: { type: string, default: "en-US" }

컴파일러는 상위 범위에 required: [database, display_name]을 출력합니다.

$ref:를 가진 소비자 — 문서 간 $ref: 옆에는 properties, required, description만 작성할 수 있으며, 소비자가 추가하는 필수 항목은 그곳에 작성한 것입니다. 즉 상위 수준의 required: 배열이거나, properties: 아래에 선언한 속성의 리프 수준 required: true 마커입니다. 참조된 항목 자체의 필수 항목(추론 형식의 리프 수준 마커 또는 자체 required: 배열)은 참조를 통해 그대로 적용됩니다. 상위 수준 배열은 항목이 이미 선언한 속성을 다시 선언하지 않고 필수 항목을 지정합니다.

spec:
schema:
values:
$ref: "Datastores#/schemas/PostgresPayload"
required: [database, display_name]

리프 수준 마커도 소비자가 참조 옆에 선언한 속성에 붙이면 유효합니다. 따라서 그곳에 properties: { database: { type: string, required: true } }를 작성하면 required: [database]와 똑같이 database가 필수가 됩니다. 소비자의 속성은 항목의 같은 이름 속성을 대체하므로(소비자가 라이브러리 항목을 좁히기 참조), 의도한 형태로 다시 선언하십시오.

라이브러리 간 체인 확장

SchemaLibrary 항목 자체가 다른 SchemaLibrary 항목을 가리키는 $ref:를 포함할 수 있으며, 이 경우 체인이 만들어집니다. 컴파일러는 컴파일 시점에 체인을 따라갑니다. 항목을 확장하는 중에 만나는 각 $ref:도 그것을 담고 있는 라이브러리의 맥락에서 확장됩니다.

# Library A
spec:
schemas:
DatabasePayload:
type: object
properties:
host: { type: string }
credentials: { $ref: "Credentials#/schemas/BasicAuth" }
# Library B (referenced from library A above)
spec:
schemas:
BasicAuth:
type: object
properties:
username: { type: string }
password: { type: string }

DatabasePayload를 참조하는 소비자 Component는 credentials가 라이브러리 B의 BasicAuth로 채워진, 완전히 확장된 형태를 받습니다. 체인이 추가한 제약을 위반하는 값은 검사 중인 문서에서 그 값 자체의 경로에서 거부되며, 이 거부는 제약이 비롯된 라이브러리 항목을 명시하지 않습니다. 이를 찾으려면 소비자에서부터 $ref: 체인을 따라가십시오.

소비자가 라이브러리 항목을 좁히는 경우

소비자 Component는 라이브러리 항목에서 가져온 속성과 이름이 같은 속성을 선언할 수 있습니다. 이 경우 병합된 형태에서 소비자의 컴파일된 속성이 라이브러리 항목의 속성을 완전히 대체합니다.

# Library entry
spec:
schemas:
ToolContract:
type: object
properties:
side_effects:
type: array
items: { type: string, enum: [read, write, delete] }
# Consumer Component
spec:
schema:
values:
$ref: "Tools#/schemas/ToolContract"
properties:
side_effects:
type: array
items: { type: string, enum: [read] }
default: [read]

병합된 형태에서 side_effects는 소비자의 더 좁은 계약(enum: [read], default 포함)을 반영하며, 라이브러리 항목의 더 넓은 enum: [read, write, delete]는 사라집니다. 이 속성은 소비자가 작성한 것입니다.

이는 예상된 동작입니다. 소비자가 라이브러리 항목의 속성을 정제하는 것은 표준적인 좁히기 패턴입니다. 좁히기는 아무 표시 없이 이루어지며, 소비자의 속성은 자체 출처를 가집니다.

교차 참조

  • 카탈로그 엔티티 상속(Component-extends-Component, Feature-extends-Feature)에 대해서는 inheritance-and-interface.md를 참조하십시오.
  • 참조가 카탈로그 엔티티가 아닌 파일을 가리키는 배포 측 문서 간의 상속에 대해서는, Release를 확장하는 Release는 entities/release.md에, Manifest를 확장하는 Manifest는 entities/manifest.md에 설명되어 있습니다.
  • 프로바이더별 소스 포인터(Recipe.spec.source.chart:, Recipe.spec.source.modulePath:)에 대해서는 엔티티별 Recipe 문서를 참조하십시오. Provider 소스 포인터는 $ref: 아래로 통합되지 않으며, 프로바이더 플러그인이 이를 직접 소비합니다.
  • OCI URI 축약형 확장 규칙(도메인 기본값, 문맥에 따른 엔터티 확장, 해석 우선순위, 버전 처리)에 대해서는 uri-grammar.md를 참조하십시오.