102 lines
9.3 KiB
Markdown
102 lines
9.3 KiB
Markdown
---
|
|
title: "official-doc / Google AIP-148 — Standard Fields (name · uid · display_name · parent)"
|
|
source_type: official-doc
|
|
url: https://google.aip.dev/148
|
|
archive_url:
|
|
vendor: Google
|
|
related_branches: [feature-resource-identifier-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, api-design, google-aip, api-contract]
|
|
created: 2026-05-31
|
|
---
|
|
|
|
# official-doc / Google AIP-148 — Standard Fields
|
|
|
|
> Layer: `raw/official-docs/` — Google API Improvement Proposal 148 의 원문 발췌·출처 기록.
|
|
> 검증된 요약은 `/ingest` 후 `wiki/concepts/` 에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-resource-identifier-contract]] | D5 (ID generation layer) — `name` 은 server-assigned 가 기본 관례임을 AIP-122 참조로 명시; D6 (prefix 정책) — Google-style 은 typed prefix 없이 flat `name` 필드 단일 식별자; D8 (PII/GDPR) — `uid` 는 opaque system-assigned 로 `display_name` 과 명확히 분리됨; D13 (multi-tenancy) — `parent` 필드로 계층적 resource name 패턴(`collection/{id}/sub-collection/{id}`) 공식화 |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://google.aip.dev/148
|
|
- 아카이브 URL: (미등록)
|
|
- 저자 / 조직: Google LLC (AIP editors)
|
|
- 발행일: 최초 발행일 미명시; Changelog 기준 최신 수정 2023-10-05
|
|
- 마지막 확인일: 2026-05-31
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
Google AIP-148 은 Google Cloud API 전반에 적용되는 **표준 필드 명명 규범**이다. `name`(resource identifier) · `uid`(system-assigned opaque UUID4) · `display_name`(사람 친화 가변 필드) · `parent`(계층 resource name) 의 정의와 의무(`MUST`/`SHOULD`) 를 직접 기술하며, ca-skeleton 의 D5/D6/D8/D13 결정의 타사 선례 근거로 보관한다.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim, 3~5문장)
|
|
|
|
Self-Grep 통과 확인: `/tmp/source-fetch-1780197218.txt` 기준.
|
|
|
|
> [§Resource names and IDs / name] "Every resource must have a string name field, used for the resource name (AIP-122), which should be the first field in the resource."
|
|
> (line 15 in fetched text)
|
|
|
|
> [§Well known string fields / uid] "The output only string uid field refers to a system-assigned unique identifier for a resource. When provided, this field must be a UUID4 and must specify this format via the UUID4 format extension (see AIP-202). Declarative-friendly resources should include this field."
|
|
> (line 95 in fetched text)
|
|
|
|
> [§Other names / display_name] "The string display_name field must be a mutable, user-settable field where the user can provide a human-readable name to be used in user interfaces. Declarative-friendly resources should include this field."
|
|
> (line 27 in fetched text)
|
|
|
|
> [§Other names / display_name — uniqueness] "Display names should not have uniqueness requirements, and should be limited to <= 63 characters."
|
|
> (line 29 in fetched text)
|
|
|
|
> [§Resource names and IDs / parent] "The string parent field refers to the resource name of the parent of a collection, and should be used in most List (AIP-132) and Create (AIP-133) requests."
|
|
> (line 21 in fetched text)
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| AIP148-C1 | 모든 resource 는 `string name` 필드를 가져야 한다 (MUST). 이 필드는 resource name 용도로 사용되며 첫 번째 필드여야 한다 (SHOULD). | [§name] "Every resource must have a string name field, used for the resource name (AIP-122), which should be the first field in the resource." | `official-vendor-doc` | Google Cloud API 스타일을 따르는 REST/gRPC API | `name` 이 server-assigned 임을 직접 명시하지 않음 (AIP-122 위임) |
|
|
| AIP148-C2 | `uid` 는 시스템이 할당한 output-only UUID4 필드로, 변경 불가·opaque 한 단일 식별자다 | [§uid] "The output only string uid field refers to a system-assigned unique identifier for a resource. When provided, this field must be a UUID4 and must specify this format via the UUID4 format extension (see AIP-202)." | `official-vendor-doc` | Google Cloud API 스타일 resource | `uid` 가 삭제 후 재생성 시 재사용 금지임을 이 AIP 가 직접 명시하지 않음 (AIP-164 위임); ULID/TSID 등 타 형식의 우열을 판단하지 않음 |
|
|
| AIP148-C3 | `display_name` 은 mutable·user-settable 이며 UI 표시용 human-readable name 이다 (MUST). uniqueness 요건이 없어야 하며 (SHOULD NOT) 63자 이하로 제한해야 한다 (SHOULD). | [§display_name] "The string display_name field must be a mutable, user-settable field where the user can provide a human-readable name to be used in user interfaces." / "Display names should not have uniqueness requirements, and should be limited to <= 63 characters." | `official-vendor-doc` | Google AIP 스타일 resource | `display_name` 이 PII 해당 여부를 판단하지 않음; 길이 63자 제한이 모든 도메인에 적용되는지 증명하지 않음 |
|
|
| AIP148-C4 | `parent` 필드는 collection 의 부모 resource name 을 참조하며, 대부분의 List·Create 요청에 사용해야 한다 (SHOULD). 이는 계층적 resource naming 패턴을 공식화한다. | [§parent] "The string parent field refers to the resource name of the parent of a collection, and should be used in most List (AIP-132) and Create (AIP-133) requests." | `official-vendor-doc` | 다단계 계층 구조를 가진 Google AIP 스타일 API | `parent` 의 구체적인 path 형식(`collection/{id}/sub-collection/{id}`) 을 이 AIP 가 직접 정의하지 않음 (AIP-122 위임) |
|
|
| AIP148-C5 | Standard fields 는 해당 개념 설명에만 사용해야 하며 (SHOULD), 다른 목적으로 사용해서는 안 된다 (SHOULD NOT). | [§Guidance] "Standard fields should be used to describe their corresponding concept, and should not be used for any other purpose." | `official-vendor-doc` | AIP-148 이 정의하는 모든 standard field | 이 원칙이 Google 외부 API 설계에 의무 적용된다는 것을 증명하지 않음 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `AIP148-C1`: Google AIP 스타일 API 에서 resource name 필드 이름은 `name` 이어야 한다.
|
|
- `AIP148-C2`: `uid` 는 UUID4 형식의 system-assigned output-only 필드다. client 가 할당하지 않는다.
|
|
- `AIP148-C3`: `display_name` 은 `uid`/`name` 과 별개의 mutable UI 표시용 필드이며, uniqueness 는 요구하지 않는다.
|
|
- `AIP148-C4`: 계층 resource 간 부모 참조는 `parent` 필드로 표현한다.
|
|
- `AIP148-C5`: standard field 명칭은 해당 개념 외 다른 목적에 재사용 금지.
|
|
|
|
- 이 자료가 증명하지 않는 것:
|
|
- `uid` 가 삭제·재생성 후에도 재사용 금지인지 (AIP-164 로 위임됨).
|
|
- `name` 이 반드시 server-assigned 인지 (AIP-122 로 위임됨 — AIP-148 자체는 server-assigned 를 직접 강제하지 않음).
|
|
- ULID / UUID v7 / KSUID 등 Google이 사용하지 않는 형식의 우열.
|
|
- Google Cloud 외부 팀(예: ca-skeleton) 이 AIP-148 을 준수해야 할 의무.
|
|
- `uid` UUID4 형식이 Java `java.util.UUID` 의 `randomUUID()` 와 동일한지 (구현 세부사항은 AIP-202 위임).
|
|
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- AIP-122 (`name` 의 resource naming 형식 및 server-assigned 여부) 별도 raw 보관 필요.
|
|
- AIP-164 (`uid` 재사용 금지 / soft-delete 후 ID 영구성) 별도 raw 보관 필요.
|
|
- ca-skeleton 이 `parent` 패턴을 multi-tenancy 에 실제로 적용할지 (D13 결정 시 AIP-122 + 실제 path 설계 병행 필요).
|
|
|
|
## 메모 / Notes
|
|
|
|
- AIP-148 은 Google 내부 convention 을 공개한 문서이며, IETF RFC 나 ISO 표준이 아니다. `official-vendor-doc` 강도로 취급한다.
|
|
- `uid` 의 UUID4 강제는 ca-skeleton D1 (format 결정) 에 직접 영향을 주지는 않는다 — ca-skeleton 의 `TicketId` 가 Google AIP `uid` 와 동일 역할은 아니기 때문. 단, *server-assigned opaque UUID4 가 industry 표준 패턴임* 을 뒷받침하는 선례로 사용 가능.
|
|
- D6 (prefix 정책): AIP-148 은 typed prefix(`tk_`, `usr_`) 를 정의하지 않는다. `name` 단일 필드로 flat 식별. Stripe-style prefix 와의 비교 근거로 "Google 은 flat" 사실을 사용 가능.
|
|
- D8 (PII): AIP-148 이 `uid` ↔ `display_name` 분리를 정의하나, PII 여부 판단은 이 AIP 범위 밖. GDPR Article 4(1) raw 별도 보관 필요.
|
|
- 추가로 봐야 할 동일 출처 페이지: [AIP-122](https://google.aip.dev/122) (Resource names), [AIP-202](https://google.aip.dev/202) (Field formats), [AIP-164](https://google.aip.dev/164) (Soft delete).
|
|
|
|
## Related / 관련
|
|
|
|
- 동일 주제 다른 official-doc: [[raw/official-docs/api-versioning-google-aip-180]] (같은 AIP 계열 기보관)
|
|
- AIP-122 (Resource names, server-assigned naming): 미보관 — 별도 `raw/official-docs/google-aip-122-resource-names.md` 로 수집 권고
|
|
- AIP-164 (Soft delete, uid 영구성): 미보관 — 별도 수집 권고
|
|
- 이 자료를 인용한 wiki 요약: (미생성 — `/ingest` 후 `wiki/concepts/resource-identifier-conventions.md` 예정)
|