---
title: Google AIP-180 — Backwards compatibility
source_type: official-doc
url: https://google.aip.dev/180
archive_url:
status: reviewed
confidence: high
tags: [ca-tmpl, api-compatibility, deprecation, aip-180, google, breaking-change]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-api-compatibility-deprecation-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Google AIP-180 — Backwards compatibility

> Layer: `raw/official-docs/` — Google API Improvement Proposals 의 backwards compatibility 정책. ca-tmpl breaking change catalog 7행 분류의 reference.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] | ca-tmpl breaking change catalog 7행 (remove field / rename / change type / narrow enum / add required request field / add optional response field / change error code) 분류의 표준 정합성 검증 근거 + Stripe / AIP 모델 비교 |
| [[raw/project-notes/ca-skeleton-operational-contract]] | API 호환성 정책 섹션 (catalog 7행 정당화 근거) |

## 컨텍스트 / 왜 저장했는지

ca-tmpl breaking change catalog 7행 분류 (`remove field`, `rename`, `change type`, `narrow enum`, `add required request field`, `add optional response field`, `change error code`) 가 AIP-180 의 분류와 어떻게 정합/차이가 있는지 검증하기 위함. canonical 승급 시 catalog 정당화에 필요. Google AIP 는 internal Google API 의 design guideline 이지만 외부 개발자에게도 reference 로 널리 인용됨.

## 출처 / Source

- 원본 URL: https://google.aip.dev/180
- 관련 AIP: AIP-181 (Stability levels), AIP-185 (Versioning)
- 아카이브 URL: (미수집)
- 저자 / 조직: Google (API Improvement Proposals working group)
- 발행일: continuously updated (AIP-180 자체에 fixed 발행일 없음)
- 마지막 확인일: 2026-05-27 (WebFetch 재검증 성공 — 5개 quote 모두 verbatim 일치, strength `needs-confirmation` → `official-vendor-doc` 으로 upgrade. [2026-05-25 capture] verbatim 보존본 유지). 현재 section headings: Guidance / Adding components / Removing or renaming components / Moving components between files / Moving into oneofs / Changing the type of fields / Changing string length / Changing resource names / Semantic changes / Further reading / Rationale / Changelog

## 핵심 인용 / Key quotes (verbatim)

> [§Removing components, captured 2026-05-22] "Existing components (interfaces, methods, messages, fields, enums, or enum values) must not be removed from existing APIs in the same major version."

> [§Renaming components, captured 2026-05-22] "Renaming a component is semantically equivalent to 'remove and add'."

> [§Default behavior, captured 2026-05-22] "Any field being populated by clients must have a default behavior matching the behavior before the field was introduced."

> [§Required fields, captured 2026-05-22] "New required fields must not be added to existing request messages or resources."

> [§Core principle, captured 2026-05-22] "Existing client code must not be broken by a service updating to a new minor or patch release."

> **[2026-05-27 verified — WebFetch 재검증 성공]**: 본 5개 quote (AIP180-C1 ~ AIP180-C5) 모두 https://google.aip.dev/180 live 페이지에서 FOUND VERBATIM. strength `needs-confirmation` → `official-vendor-doc` 으로 upgrade. [2026-05-25 capture] verbatim 본문 그대로 유지. AIP-181 / AIP-185 와의 cross-reference 는 별도 raw 작성 시 재확인.

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| AIP180-C1 | 같은 major version 안에서 기존 component (interface / method / message / field / enum / enum value) 를 제거하면 안 됨 (`must not`) | [§Removing or renaming components, captured 2026-05-22 + 2026-05-27 verified verbatim] "Existing components (interfaces, methods, messages, fields, enums, or enum values) must not be removed from existing APIs in the same major version." | `official-vendor-doc` [2026-05-27 verified] | Google API design (외부 reference 로 인용 가능) | 다른 major version (v1 → v2) 으로 이동 시 제거 정책은 별도 (AIP-181 / AIP-185 영역) |
| AIP180-C2 | component renaming 은 의미상 "remove + add" 와 동등 (즉 rename 은 breaking) | [§Removing or renaming components, captured 2026-05-22 + 2026-05-27 verified verbatim] "Renaming a component is semantically equivalent to 'remove and add'." | `official-vendor-doc` [2026-05-27 verified] | rename 결정의 breaking 분류 | alias / 양쪽 동시 노출 같은 mitigation 정책은 본 인용에 없음 — `C1` 과 함께 same major version 안에서는 사실상 금지 |
| AIP180-C3 | client 가 채우는 모든 field 는 도입 이전 동작과 일치하는 default behavior 를 가져야 함 (`must`) | [§Adding components / Default behavior, captured 2026-05-22 + 2026-05-27 verified verbatim] "Any field being populated by clients must have a default behavior matching the behavior before the field was introduced." | `official-vendor-doc` [2026-05-27 verified] | 새 optional field 추가 시 default 동작 정책 | 모든 새 field 가 optional 이어야 한다는 뜻은 아님 — `C4` 가 required field 별도 다룸 |
| AIP180-C4 | 기존 request message / resource 에 새 required field 를 추가하면 안 됨 (`must not`) | [§Adding components / Required fields, captured 2026-05-22 + 2026-05-27 verified verbatim] "New required fields must not be added to existing request messages or resources." | `official-vendor-doc` [2026-05-27 verified] | 새 field 추가 시 required vs optional 결정 | 새 endpoint / 새 message 에서는 required field 자유 — 본 인용은 기존 message 만 |
| AIP180-C5 | 서비스가 minor 또는 patch release 로 업데이트되었을 때 기존 client code 가 깨지면 안 됨 (`must not`, 핵심 원칙) | [§Guidance / Core principle, captured 2026-05-22 + 2026-05-27 verified verbatim] "Existing client code must not be broken by a service updating to a new minor or patch release." | `official-vendor-doc` [2026-05-27 verified] | semver 의 minor / patch release 호환성 | major version bump 시 breaking change 허용 여부는 본 인용 범위 밖 (AIP-185 영역) |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것** (2026-05-22 capture + 2026-05-27 WebFetch verbatim 재검증):
  - `AIP180-C1`: 같은 major version 안에서 component 제거 금지
  - `AIP180-C2`: rename = breaking
  - `AIP180-C3`: 새 field 의 default 동작은 이전과 일치해야 함
  - `AIP180-C4`: 기존 message 에 새 required field 추가 금지
  - `AIP180-C5`: minor/patch 에서 client breaking 금지
- **이 자료가 증명하지 않는 것**:
  - 다른 major version (v1 → v2) 으로의 migration 정책 — AIP-185 영역
  - deprecation 통지 / window / sunset 정책 — AIP-180 본문에 부분만 있을 수 있음 (재확인 필요)
  - error code (status code / error enum) 변경의 정확한 분류 — AIP-180 은 enum value 제거 금지 원칙으로 같은 결론에 도달하지만 명시적 "error code change" 행은 본 인용에 없음
  - CI breaking diff 자동 차단 같은 운영 메커니즘
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - 2026-05-27 시점 AIP-180 본문 재확인 (continuously updated)
  - ca-tmpl 의 `migration window 90d/30d` 가 AIP-180 의 "절대 제거 금지" (`C1`) 와 다른 정책임을 명시
  - ca-tmpl 의 `narrow enum 을 new version 으로` 정책이 AIP-180 의 "enum value 제거 금지" 와 호환 가능한지 (new version 도입 시점에서는 호환)

## ca-tmpl 함의 (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용이 아닌 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 source-summary 로 옮겨야 함.

### AIP-180 과 ca-tmpl catalog 정합

| catalog 행 | AIP-180 분류 (인용 근거) | 일치 여부 |
|---|---|---|
| remove response field | breaking — `AIP180-C1` ("must not be removed") | 일치 |
| rename response field | breaking — `AIP180-C2` ("remove and add") | 일치 |
| change field type/format | breaking — `AIP180-C5` (client code breaks) | 일치 (간접) |
| narrow enum values | breaking — `AIP180-C1` (enum values 도 component) | 일치 |
| add required request field | breaking — `AIP180-C4` (명시적 금지) | 일치 |
| add optional response field | additive — `AIP180-C3` (default 동작 보장 시) | 일치 |
| change error code | breaking for clients — `AIP180-C1` (enum value 제거 금지) | 일치 (간접) |

### ca-tmpl 이 AIP-180 보다 **약한** 부분

- AIP-180 은 same major version 안에서 component 제거 사실상 영구 금지 (`C1`).
- ca-tmpl 은 `migration window 90d/30d` 후 제거 허용 — internal-first skeleton 에 합리적 trade-off (Google 의 Stripe / public API 보다 운영 부담 낮음).

### ca-tmpl 이 AIP-180 보다 **강한** 부분

- ca-tmpl: `migration window 90d/30d` **의무화** (AIP-180 은 사실상 무기한이라 명시적 window 없음).
- ca-tmpl: CI breaking diff release-blocking (AIP-180 은 정책만 명시, 강제 메커니즘 별도).

### Trade-off

- AIP-180 전면 도입: 사실상 영구 호환. Stripe 모델과 유사. 운영비용 큼.
- ca-tmpl: window 후 제거 허용. internal-first skeleton 에 합리적.

## 메모 / Notes

- **AIP vs RFC vs Google internal**: AIP 는 Google internal API design guideline 이지만 외부에 공개되어 reference 로 인용 가능. 정식 IETF/W3C 표준이 아님 — 외부 인용 시 "Google AIP" 로 명시, "공식 표준" 표현 금지.
- **재검증 완료**: 2026-05-27 google.aip.dev WebFetch 재검증 성공 (5/5 verbatim). continuously updated 특성상 다음 검토 시 재확인 권장.
- **관련 AIP**: AIP-181 (Stability levels), AIP-185 (Versioning) — 별도 raw 작성 후 통합 분석 권장.

## Related / 관련

- 같은 주제 다른 official-doc / 표준:
  - AIP-181 (Stability levels) — 별도 raw 작성 후보
  - AIP-185 (Versioning) — 별도 raw 작성 후보
- 인용하는 branch:
  - [[raw/branch-notes/feature-api-compatibility-deprecation-contract]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 인용한 wiki 요약: (미작성)