Terminology Contracts for APIs and Data Models: Canonical Names, Alias Mapping, Deprecation Windows, and Migration-Safe Validation

API와 데이터 모델의 용어 변경은 단순한 “필드명 rename”이 아니라 계약 변경(contract change) 으로 다뤄야 한다. 안전한 방식은 새 용어를 canonical name 으로 정하고, 기존 용어는 일정 기간 alias 로 수용하며, 문서·스키마·검증 로직·이벤트 처리·클라이언트 SDK가 동일한 용어 계약을 따르도록 관리하는 것이다. 핵심 패턴은 다음과 같다. 1. canonical term registry 를 둔다: 현재 공식 명칭, 과거 명칭

Summary#

API와 데이터 모델의 용어 변경은 단순한 “필드명 rename”이 아니라 계약 변경(contract change) 으로 다뤄야 한다. 안전한 방식은 새 용어를 canonical name 으로 정하고, 기존 용어는 일정 기간 alias 로 수용하며, 문서·스키마·검증 로직·이벤트 처리·클라이언트 SDK가 동일한 용어 계약을 따르도록 관리하는 것이다.

핵심 패턴은 다음과 같다.

canonical term registry 를 둔다: 현재 공식 명칭, 과거 명칭, 허용 alias, 소유 bounded context, 상태, 제거 예정일을 명시한다.
rename은 즉시 교체하지 않고 additive migration 으로 처리한다: 새 필드를 추가하고, 기존 필드는 deprecated로 표시하며, 일정 기간 양쪽을 읽는다.
validation은 migration-safe 해야 한다: 입력에서는 canonical 또는 alias를 허용하되, 내부 모델과 출력은 가능하면 canonical로 정규화한다.
deprecation window를 계약화한다: 제거 시점, 경고 방식, telemetry 기준, breaking-change 조건을 명확히 한다.
이벤트·API·DB 모델의 용어는 동일하지 않아도 되지만, 변환 경계에서 mapping rule을 명시해야 한다.

Key Points#

Terminology contract의 기본 단위
canonical name: 현재 공식 용어 또는 필드명.
aliases: 과거 이름, 외부 파트너별 이름, legacy client가 보내는 이름.
lifecycle state: active, deprecated, removed, reserved 등.
owner: 해당 용어를 관리하는 팀 또는 bounded context.
compatibility rule: read 허용 여부, write 허용 여부, response 노출 여부.
removal policy: 제거 가능 조건과 최소 deprecation 기간.
API field rename의 안전한 순서 1. 새 canonical field를 추가한다. 2. 구 필드는 deprecated로 문서화한다. 3. 요청 payload에서는 구 필드와 새 필드를 모두 허용한다. 4. 내부 처리에서는 canonical field로 normalize한다. 5. 응답에서는 일정 기간 둘 다 제공하거나, 새 필드만 제공하되 구 필드 의존 클라이언트 영향도를 측정한다. 6. telemetry로 alias 사용량을 관찰한다. 7. deprecation window 종료 후 breaking-change 릴리스나 명시된 major version에서 제거한다.
alias mapping rule
alias는 단순 문자열 치환이 아니라 방향성을 가져야 한다.
- legacy_name -> canonical_name
- partner_specific_name -> canonical_name
- event_v1_name -> event_v2_name
같은 요청 안에 canonical field와 alias field가 동시에 존재할 수 있다. 이 경우 우선순위를 명시해야 한다.
- 권장: 값이 동일하면 허용, 값이 다르면 validation error.
- 또는 canonical field 우선, alias 무시. 단, 이 정책은 명확히 문서화해야 한다.
alias는 무기한 유지하지 않는다. 그렇지 않으면 데이터 모델이 “동의어 쓰레기장”이 된다.
migration-safe validation
입력 validation은 전환 기간 동안 alias를 허용해야 한다.
정규화 이후의 내부 validation은 canonical model에 대해 수행한다.
출력 validation과 schema generation은 canonical field를 기준으로 해야 한다.
deprecated field는 schema에 표시하되, 새 구현이 이를 사용하지 않도록 lint rule이나 contract test를 둔다.
JSON Schema에는 deprecated annotation이 존재하지만, 이것만으로 런타임 거부나 경고가 자동 수행되는 것은 아니다. 검증기·문서 생성기·클라이언트 생성기의 동작을 별도로 확인해야 한다.
schema evolution 관점
Avro는 field alias를 지원하여 reader schema가 writer schema의 과거 이름을 해석할 수 있게 한다.
이벤트 스키마에서는 producer와 consumer가 서로 다른 배포 주기를 가지므로, field rename은 특히 보수적으로 다뤄야 한다.
이벤트에서는 기존 필드를 제거하기보다 새 필드를 추가하고 consumer migration을 기다리는 방식이 일반적으로 안전하다.
backward compatibility는 “새 producer가 낸 데이터를 구 consumer가 읽을 수 있는가”와 “구 producer가 낸 데이터를 새 consumer가 읽을 수 있는가”를 구분해 검토해야 한다.
도메인 모델과 ubiquitous language
DDD의 ubiquitous language는 팀과 코드, 문서가 같은 의미의 용어를 쓰도록 돕는다.
그러나 실제 시스템에서는 bounded context마다 같은 단어가 다른 의미를 가질 수 있다.
따라서 전사 단일 glossary만으로는 부족하다. 각 bounded context별 canonical term과 context 간 translation map이 필요하다.
예: customer, account, user, member는 조직마다 다르게 쓰일 수 있으므로 API 계약에서 의미와 식별자 범위를 명확히 해야 한다.
deprecation window 설계
deprecation은 “언젠가 제거”가 아니라 “언제, 어떤 조건에서, 어떤 방식으로 제거”인지 명시해야 한다.
최소 포함 항목:
- deprecated date
- earliest removal date
- affected endpoints/events/schemas
- replacement field
- conflict behavior
- telemetry threshold
- client communication plan
public API라면 removal은 보통 major version 또는 명시된 breaking-change 정책과 연결하는 것이 안전하다.
contract test와 governance
API schema, event schema, SDK, documentation, validation code가 같은 alias map을 사용하는지 테스트해야 한다.
권장 테스트:
- legacy field only 요청이 성공하는가
- canonical field only 요청이 성공하는가
- 둘 다 같은 값이면 성공하는가
- 둘 다 다른 값이면 정의된 방식으로 실패하는가
- 응답에 deprecated field가 포함되는 정책이 지켜지는가
- deprecated field 사용 시 warning/metric이 기록되는가
glossary 변경은 PR template이나 architecture decision record와 연결하면 추적성이 좋아진다.
권장 contract 형태 예시

term: displayName
status: active
owner: identity-profile-context
meaning: Human-readable name shown in profile surfaces.
aliases:
  - name: fullName
    status: deprecated
    direction: input_only
    deprecated_since: 2026-01-01
    earliest_removal: 2026-07-01
    conflict_rule: canonical_wins_or_error
replacement_for:
  - fullName
validation:
  canonical_required_after_normalization: true
  allow_alias_input_until: 2026-07-01
  reject_conflicting_values: true
output:
  emit_canonical: true
  emit_alias: false
telemetry:
  metric: api.request.field_alias.fullName

Cautions#

deprecated 표시는 도구마다 의미가 다르다. JSON Schema나 OpenAPI 문서에 deprecated를 표시해도, 실제 runtime validation이나 client SDK가 자동으로 차단·경고한다고 가정하면 안 된다.
field alias 지원은 포맷별로 다르다. Avro는 alias 개념을 명시적으로 제공하지만, JSON/REST API에서는 보통 애플리케이션 레벨 mapping이 필요하다.
alias를 장기간 유지하면 compatibility는 좋아지지만 모델의 의미가 흐려지고 validation 복잡도가 증가한다.
canonical name을 정할 때 단순히 “더 예쁜 이름”을 선택하면 안 된다. 도메인 의미, bounded context, 외부 API 계약, analytics/event consumers의 의존성을 함께 검토해야 한다.
모든 rename이 backward compatible한 것은 아니다. 이름만 바꾸는 경우라도 generated client, typed SDK, query language, analytics pipeline, event consumer에는 breaking change가 될 수 있다.
deprecation window의 적정 기간은 API의 공개 범위, client 배포 통제 가능성, 규제 요구사항, 이벤트 보존 기간에 따라 달라진다.

Sources#

https://google.aip.dev/180
https://avro.apache.org/docs/1.12.0/specification/#aliases
https://json-schema.org/draft/2020-12/json-schema-validation.html#name-deprecated
https://martinfowler.com/bliki/UbiquitousLanguage.html
https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html
https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design#versioning-a-restful-web-api

Sagwan Revalidation 2026-09-03T11:28:14Z#

verdict: ok
note: API 용어 변경을 계약으로 다루는 권장안은 현재도 유효하다.

Sagwan Revalidation 2026-09-09T12:55:09Z#

verdict: ok
note: [chatgpt HTTP 404] {

Sagwan Revalidation 2026-09-12T04:05:15Z#

verdict: ok
note: additive migration·alias mapping·deprecation window 패턴은 2026년 현재 API 설계 표준과 완전히 일치하며 낡은 주장 없음.

Sagwan Revalidation 2026-09-15T21:35:18Z#

verdict: ok
note: 필드 rename·alias·deprecation 계약화 권장은 현재도 유효하다.