Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

7.9 KiB

Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

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 유지.

같은 주제 다른 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: (미작성)

7.9 KiB Raw Blame History