donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
docs/ca-skeleton-frontend-runtime-adapter-features
llm-wiki/raw/official-docs/protobuf-reserved-vs-json-openapi-extension.md
T

13 KiB
Raw Permalink 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 tags related_projects related_branches created last_reviewed
Protobuf reserved Semantics vs JSON/OpenAPI Equivalents official-doc https://protobuf.dev/programming-guides/proto3/#reserved needs-confirmation medium
ca-tmpl
ca-schema
protobuf
openapi
json-schema
reserved-fields
ca-tmpl
feature-schema-serialization-contract
feature-api-compatibility-deprecation-contract
2026-05-22 2026-05-27

Protobuf reserved Semantics vs JSON/OpenAPI Equivalents

Layer: raw/official-docs/ — Protobuf reserved 키워드 verbatim + OpenAPI 3.1 / JSON Schema 의 등가 시맨틱 부재 비교. ca-tmpl (JSON 기반) 이 schema 호환성을 강제하려면 무엇을 자체적으로 정의해야 하는지 평가하기 위한 보강 자료.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-schema-serialization-contract G-F follow-up — JSON 환경에서 Protobuf reserved 시맨틱 흉내 메커니즘 (OpenAPI x- extension vs 별도 markdown catalog vs JSON Schema deprecated) 비교 근거
raw/branch-notes/feature-api-compatibility-deprecation-contract "removed field name 재사용 차단" 정책의 표준 도구 부재 사실 — 자체 lint / code review 강제 결정의 1차 근거

컨텍스트 / 왜 저장했는지

Protobuf 의 reserved 키워드는 schema 호환성의 핵심 장치 — field number / name 재사용을 컴파일러 단계에서 영구 차단한다. ca-tmpl 은 JSON over HTTP 기반이라 reserved 를 직접 흉내낼 수 없고, OpenAPI / JSON Schema 에는 등가 시맨틱이 부재. G-F (raw/branch-notes/feature-schema-serialization-contract) 외부 근거 조사에서 "Protobuf reserved 가 JSON 환경에서 ca-tmpl 이 가장 크게 보강할 부분" 으로 식별됐으나, 어떤 메커니즘으로 보강할지 (OpenAPI x- extension / 자체 markdown catalog / lint tool) 는 미정. 본 raw 는 후속 결정을 위한 시맨틱 비교 근거.

출처 / Source

핵심 인용 / Key quotes (verbatim)

Protobuf 공식 (proto3 guide §Reserved)

[§Reserved] "If you update a message type by entirely deleting a field, or commenting it out, future developers can reuse the field number when making their own updates to the type."

[§Reserved] "you must reserve the deleted field number. If you do not reserve the field number, it is possible for a developer to reuse that number in the future."

[§Reserved — Risks of reuse] "Reusing a field number makes decoding wire-format messages ambiguous." Identified risks include "Developer time lost to debugging", "A parse/merge error (best case scenario)", "Leaked PII/SPII", "Data corruption".

[§Reserved — name reuse] "Reusing an old field name later is generally safe, except when using TextProto or JSON encodings where the field name is serialized."

OpenAPI 3.1 / JSON Schema (보조 인용 — 보조 URL 출처)

[OpenAPI 3.1 §4.9 Specification Extensions, 보조 인용] "Specification Extensions... allow vendor specific extensions. The extensions properties are implemented as patterned fields that are always prefixed by x-."

[JSON Schema 2020-12 §9.3, 보조 인용] "The deprecated keyword applies to Schema Objects to indicate that this schema has been deprecated... but does not affect the validation of an instance."

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
PRVJ-C1 message type 에서 field 를 삭제/주석화하면 미래 개발자가 그 field number 를 재사용할 수 있다 (자동 차단 없음) [§Reserved] "If you update a message type by entirely deleting a field, or commenting it out, future developers can reuse the field number when making their own updates to the type." official-standard proto3 컴파일러 동작 다른 schema 시스템 (Avro / JSON Schema) 에서 동일 위험이 있다는 뜻 아님 — Protobuf 한정 사실
PRVJ-C2 삭제된 field number 는 반드시 reserved 처리 필요 — reserve 안 하면 미래 개발자가 재사용 가능 [§Reserved] "you must reserve the deleted field number. If you do not reserve the field number, it is possible for a developer to reuse that number in the future." official-standard proto3 schema 변경 워크플로 reserved 처리가 lint / pre-commit 으로 자동 추가된다는 뜻 아님 — 개발자 명시 작성 의무
PRVJ-C3 field number 재사용 시 wire-format 디코딩이 ambiguous — 결과로 (a) 디버깅 시간 손실, (b) parse/merge error (best case), (c) PII/SPII 누출, (d) 데이터 손상 가능 [§Reserved — Risks] "Reusing a field number makes decoding wire-format messages ambiguous." + risk list official-standard Protobuf wire-format 호환성 위 4가지 위험이 항상 모두 발생한다는 뜻 아님 — 시나리오별
PRVJ-C4 field name 재사용은 일반적으로 안전하나 TextProto / JSON encoding 사용 시 위험 — 해당 인코딩에서 field name 이 직렬화되기 때문 [§Reserved] "Reusing an old field name later is generally safe, except when using TextProto or JSON encodings where the field name is serialized." official-standard proto3 + JSON / TextProto encoding binary 환경에서 name 재사용이 완전 자유라는 뜻 아님 — 디버깅 / 로깅 / 코드 가독성 영향 별도
PRVJ-C5 OpenAPI 3.1 의 Specification Extensions 는 x- 접두 vendor-specific 키 허용 (어떤 정책도 정의하지 않음, 단순 확장 허가) [OpenAPI 3.1 §4.9, 보조 인용] "Specification Extensions... allow vendor specific extensions. The extensions properties are implemented as patterned fields that are always prefixed by x-." official-standard OpenAPI 3.1 spec 확장 메커니즘 x-removed-fields 같은 특정 확장이 표준이라는 뜻 아님 — 자체 lint 룰을 직접 작성해야 함
PRVJ-C6 JSON Schema 2020-12 의 deprecated 키워드는 비권장 신호만 제공 — instance validation 에는 영향 없음 (재사용 차단 아님) [JSON Schema 2020-12 §9.3, 보조 인용] "The deprecated keyword applies to Schema Objects to indicate that this schema has been deprecated... but does not affect the validation of an instance." official-standard JSON Schema deprecated 의미 deprecated: true 로 Protobuf reserved 의 재사용 차단을 흉내낼 수 있다는 뜻 아님 — 시맨틱 다름

미확인 / 후속 확인 필요

  • Stripe / GitHub 의 removed field name 재사용 정책: 공개 문서상 명시적 reserved-style 시맨틱 부재. 본 raw 에서는 claim 으로 등록하지 않음 (보조 URL 직접 verbatim 미수집).

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • PRVJ-C1 ~ C4: Protobuf reserved 의 정확한 시맨틱과 위험 (proto3 공식)
    • PRVJ-C5 ~ C6: OpenAPI 3.1 x- extension 메커니즘 존재 + JSON Schema deprecated 의 validation 비영향 (보조 인용)
  • 이 자료가 증명하지 않는 것:
    • JSON 환경에서 Protobuf reserved 와 1:1 등가인 표준 메커니즘이 존재한다 (오히려 부재 확인)
    • x-removed-fields 같은 특정 OpenAPI 확장이 공식 권장이라는 사실 (vendor-specific extension)
    • Stripe / GitHub 가 removed field name 재사용을 공식 정책으로 명시한다는 사실 (운영 정책으로 회피 추정)
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • ca-tmpl 이 채택할 lint tool (Spectral / Redocly CLI 등) 의 custom rule 작성 가능 여부
    • 별도 markdown catalog (docs/removed-fields-catalog.md) 와 OpenAPI diff 의 sync 자동화 방안
    • JSON Schema deprecated + OpenAPI x- extension 조합의 실무 운영 사례 (현재 부재)

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

Protobuf reserved vs JSON/OpenAPI 환경 비교

측면 Protobuf reserved OpenAPI 3.1 / JSON Schema
식별자 field number (int) + field name (string) property name (string)
재사용 차단 강제 컴파일러가 거부 (.proto 빌드 실패) 등가 없음 — deprecated: true 는 표시만, 재사용 차단 아님
표현 방식 reserved 3, 5; / reserved "foo", "bar"; (없음) → x-removed-fields 등 자체 extension 필요
위반 시 효과 wire format ambiguity, PII leak, parse error 명시적 차단 없으면 typo 또는 의도적 재사용으로 의미 충돌 가능
도구 지원 protoc 빌드 단계 별도 lint / OpenAPI diff 도구 필요 (표준 부재)

JSON 환경에서의 흉내 대안

  1. OpenAPI Specification Extension (x-removed-fields):

    • OpenAPI 3.1 §4.9 가 x- 접두 vendor extension 을 허용. schema object 에 x-removed-fields: ["legacyAmount", "obsoleteFlag"] 같은 배열을 두고 CI 에서 이 목록과 신규 추가 field 이름이 겹치면 빌드 실패시키는 방식.
    • 장점: schema SSOT (OpenAPI) 내부에 catalog 가 있어 표류 위험 ↓.
    • 단점: x- extension 은 vendor-specific 이라 표준 검증 도구 부재 — 자체 lint 룰을 직접 작성해야 한다.

  2. JSON Schema deprecated keyword:

    • JSON Schema 2020-12 와 OpenAPI 3.1 이 함께 정의하는 표준 키워드. deprecated: true 는 지금 사용 비권장 신호일 뿐 재사용 차단이 아니다.
    • field 가 완전히 사라진 뒤에는 schema 에서도 사라지므로 deprecated 만으로는 미래 재사용 방지가 불가.
    • 결론: deprecation marker 로는 적합, reserved 시맨틱 흉내로는 부적합.

  3. 자체 markdown / YAML catalog:

    • 별도 파일 (예: docs/removed-fields-catalog.md) 에 제거된 field name / 번호 / 제거 일자 / 사유를 기록하고, code review 나 CI 에서 신규 OpenAPI diff 와 cross-check.
    • 장점: tool 에 종속되지 않음, 사람이 읽기 쉬움.
    • 단점: schema 와 catalog 가 별도라 sync 실패 위험. 자동화하려면 결국 lint script 가 필요.

  4. GitHub / Stripe API 의 실제 처리 (보조 — 본 자료가 단정하지 않음):

    • Stripe: account 단위 version pin + freeze forever 정책으로 제거 보다는 구버전 영구 응답 을 택해 재사용 문제를 회피.
    • GitHub REST: 24개월 EOL + 410 Gone 응답. EOL 된 version 에서 제거된 field 이름의 신규 재사용 정책은 공개 문서상 명시되지 않음 (공식 reserved-style 시맨틱 부재).
    • 결론: 공개 API 사례에서도 field name 재사용 차단의 명시적 표준은 없다. 진영별로 운영 정책으로 회피하는 형태.

Trade-off

  • OpenAPI x- extension 채택: schema SSOT 에 catalog 가 통합되어 표류 ↓. 단 표준 검증 도구가 없어 자체 lint 필수, 도구 채택 자체가 코드 단계 결정.
  • 자체 markdown catalog: 가독성 ↑, tool-free. 단 schema 와 별도라 sync 실패 위험, code review 에 의존.
  • JSON Schema deprecated 단독: deprecation marker 로만 적합, reserved 시맨틱 흉내 불가.

결론

Protobuf reserved 의 wire-format 수준 강제력을 JSON 환경에서 1:1 흉내내는 표준 메커니즘은 존재하지 않는다. ca-tmpl 이 채택할 수 있는 현실적 옵션은 (a) OpenAPI x-removed-fields extension + 자체 lint, (b) 별도 markdown catalog + code review/CI, 두 가지. 둘 다 도구 선택이 따라오므로 코드 단계 (Phase C2 이후) 결정 사항.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink