fix: 하네스 제거 및 keycloak 문서 보강
This commit is contained in:
DongHyeonka
@@ -1 +0,0 @@
|
||||
../../vault/20-evidence/official-docs/schema-avro-evolution-rules.md
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: Apache Avro — Schema resolution & evolution rules
|
||||
source_type: official-doc
|
||||
url: https://avro.apache.org/docs/1.11.1/specification/
|
||||
archive_url:
|
||||
status: raw
|
||||
confidence: high
|
||||
tags: [ca-tmpl, schema, serialization, avro, schema-evolution, kafka]
|
||||
related_projects: [ca-tmpl]
|
||||
related_branches: [feature-schema-serialization-contract, feature-domain-event-outbox-contract]
|
||||
created: 2026-05-22
|
||||
last_reviewed: 2026-05-27
|
||||
---
|
||||
|
||||
# Apache Avro — Schema resolution & evolution rules
|
||||
|
||||
> Layer: `raw/official-docs/` — Apache Avro 1.11.1 공식 spec 의 Schema Resolution 규칙 verbatim 발췌. ca-tmpl 의 `null/empty/missing 의미 분리`·`unknown field strict inbound / tolerant outbound` 결정의 대안 모델 근거.
|
||||
|
||||
## Parent / 활용 branch (필수)
|
||||
|
||||
| Branch | 이 자료가 정당화하는 결정 |
|
||||
|---|---|
|
||||
| [[raw/branch-notes/feature-schema-serialization-contract]] | G-F 대안 3 (Avro schema registry + compatibility level enforcement) 의 1차 근거 — Avro 의 자동 schema resolution 이 ca-tmpl 의 manual OpenAPI drift 검증과 무엇이 다른지 비교 기준 |
|
||||
| [[raw/branch-notes/feature-domain-event-outbox-contract]] | outbox event 의 evolution 경로로 Avro+Schema Registry 채택 시 default-fill / unknown-ignore 시맨틱이 outbox consumer 호환성을 어떻게 보장하는지 평가 근거 |
|
||||
|
||||
## 컨텍스트
|
||||
|
||||
Avro 는 **schema registry 기반 backward/forward/full compatibility** 를 명시적으로 분류·강제. ca-tmpl 이 OpenAPI drift 검증으로 수동적으로 흉내내는 것을 Avro 는 schema resolution 알고리즘으로 기계적으로 보장. Kafka·outbox event 와 함께 검토할 가치 있는 대안.
|
||||
|
||||
## 출처 / Source
|
||||
|
||||
- 원본 URL: https://avro.apache.org/docs/1.11.1/specification/
|
||||
- 아카이브 URL: (미수집)
|
||||
- 저자 / 조직: Apache Software Foundation
|
||||
- 발행일: 1.11.1 spec (continuously maintained)
|
||||
- 마지막 확인일: 2026-05-27
|
||||
|
||||
## 핵심 인용 / Key quotes (verbatim)
|
||||
|
||||
> [§Schema Resolution — record fields] "if the reader's record schema has a field that contains a default value, and writer's schema does not have a field with the same name, then the reader should use the default value from its field."
|
||||
|
||||
> [§Schema Resolution — record fields] "if the writer's record contains a field with a name not present in the reader's record, the writer's value for that field is ignored."
|
||||
|
||||
> [§Schema Resolution — record fields] "the ordering of fields may be different: fields are matched by name."
|
||||
|
||||
> [§Schema Resolution — record fields] "if the reader's record schema has a field with no default value, and writer's schema does not have a field with the same name, an error is signalled."
|
||||
|
||||
## Claims Extracted / 추출된 주장
|
||||
|
||||
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
||||
|---|---|---|---|---|---|
|
||||
| SAER-C1 | reader schema 에 default value 가 있고 writer schema 에 동명 field 가 없을 때, reader 는 자신의 default value 를 사용 | [§Schema Resolution] "if the reader's record schema has a field that contains a default value, and writer's schema does not have a field with the same name, then the reader should use the default value from its field." | `official-standard` | Avro record schema resolution | JSON / OpenAPI 환경에서 동일 default-fill 시맨틱이 자동 적용된다는 뜻 아님 — Avro reader/writer 모델 한정 |
|
||||
| SAER-C2 | writer record 에 reader schema 에 없는 field 가 포함되면, writer 의 그 field 값은 reader 측에서 무시됨 (unknown field 자동 drop) | [§Schema Resolution] "if the writer's record contains a field with a name not present in the reader's record, the writer's value for that field is ignored." | `official-standard` | Avro reader 측 처리 | 이 시맨틱이 ca-tmpl 의 "request unknown field → fail-fast" 결정과 일치한다는 뜻 아님 — Avro 는 정반대로 자동 ignore |
|
||||
| SAER-C3 | field ordering 은 reader/writer 간 달라도 무관 — field 는 name 으로 매칭됨 | [§Schema Resolution] "the ordering of fields may be different: fields are matched by name." | `official-standard` | Avro record schema 매칭 | wire-format 의 byte 순서가 무의미하다는 뜻 아님 — schema resolution 단계에서의 매칭 규칙 |
|
||||
| SAER-C4 | reader field 에 default 가 없고 writer schema 에 동명 field 가 없으면 error 발생 (호환성 깨짐 검출) | [§Schema Resolution] "if the reader's record schema has a field with no default value, and writer's schema does not have a field with the same name, an error is signalled." | `official-standard` | Avro reader 처리 | error 의 정확한 형태 (예외 / null 반환 / build 실패) 는 라이브러리 구현 따라 다를 수 있음 |
|
||||
|
||||
### 미확인 / 후속 확인 필요
|
||||
|
||||
- **backward / forward / full compatibility 의 정의**: 1.11.1 specification page (위 URL) 의 추출 범위에서는 명시적 정의가 발견되지 않았음. Confluent Schema Registry 문서 등 보조 페이지 추가 인용 필요 — 본 raw 에서는 **claim 으로 등록하지 않음**.
|
||||
|
||||
## Usage Boundaries / 적용 경계
|
||||
|
||||
- **이 자료가 직접 증명하는 것**:
|
||||
- `SAER-C1` ~ `C4`: Avro schema resolution 의 4가지 매칭 규칙 (default-fill / unknown-ignore / name-match / no-default-error)
|
||||
- **이 자료가 증명하지 않는 것**:
|
||||
- backward / forward / full compatibility 의 공식 정의 (본 page 추출 범위 밖 — Confluent Schema Registry 또는 별도 spec page 필요)
|
||||
- Avro 의 resolution 규칙이 JSON over HTTP 환경에서도 동일하게 적용된다는 뜻 (Avro 는 Avro 디코더 한정)
|
||||
- Schema Registry 의 compatibility level enforcement 가 CI 단계에서 어떻게 강제되는지의 도구별 동작
|
||||
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
||||
- ca-tmpl outbox event 의 schema 가 Avro 로 직렬화될 경우 producer/consumer 의 schema 등록 시점 / 버전 관리 정책
|
||||
- OpenAPI 3.1 의 `nullable` + JSON Schema `null` 통합이 Avro union `["null", "string"]` 과 동일한 시맨틱을 갖는지 (인터페이스 표현은 다름)
|
||||
- REST/JSON 외부 API 노출 환경에서 Avro 대신 채택할 수 있는 schema registry 등가물
|
||||
|
||||
## 메모 / Notes (내 프로젝트 해석)
|
||||
|
||||
> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
|
||||
|
||||
- Avro 의 null/missing 의미 처리:
|
||||
- `null` 은 union 타입 (`["null", "string"]`) 으로만 표현. nullable 이 schema 에 명시.
|
||||
- missing field 는 reader 가 default 값으로 채움 (또는 SAER-C4 에 따라 error).
|
||||
- **ca-tmpl 결정과 정합 방향**: "null/empty/missing 의미를 mapper 가 owns" 는 Avro 의 union+default 모델과 같은 의도.
|
||||
- ca-tmpl JSON 환경에서 Avro 수준 강제를 흉내내려면:
|
||||
- OpenAPI schema 에 `nullable: true` vs missing field 를 명시 (OpenAPI 3.1 은 JSON Schema `null` 타입과 통합).
|
||||
- 모든 optional response field 에 default 또는 nullable 표시 의무화 → ca-tmpl table 의 `optional field documented nullable` 결정과 일치.
|
||||
- Trade-off:
|
||||
- Avro 채택: schema registry + compatibility level 자동 검사. CI 통합 강력.
|
||||
- Avro 단점: REST/JSON 외부 노출에 부적합. 클라이언트가 Avro 디코더 필요. 주로 Kafka/이벤트 내부 통신.
|
||||
- 적용 가능성:
|
||||
- ca-tmpl outbox/domain event branch 와 결합 시 Avro+Schema Registry 도입은 합리적. 단 외부 HTTP API 는 JSON 유지.
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 같은 주제 다른 official-doc:
|
||||
- [[raw/official-docs/schema-protobuf-vs-json-evolution]] (Protobuf 측 동일 주제)
|
||||
- [[raw/official-docs/protobuf-reserved-vs-json-openapi-extension]] (Protobuf reserved 의 JSON 흉내)
|
||||
- [[raw/official-docs/schema-jackson-unknown-field-handling]] (Jackson 측 unknown field 처리)
|
||||
- 인용하는 branch:
|
||||
- [[raw/branch-notes/feature-schema-serialization-contract]] (G-F 대안 3)
|
||||
- [[raw/branch-notes/feature-domain-event-outbox-contract]]
|
||||
- 인용하는 wiki: (미작성)
|
||||
Reference in New Issue
Block a user