---
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: (미작성)