llm-wiki/raw/official-docs/google-aip-148-standard-fields.md

title, source_type, url, archive_url, vendor, related_branches, related_projects, tags, created

title	source_type	url	archive_url	vendor	related_branches	related_projects	tags	created
official-doc / Google AIP-148 — Standard Fields (name · uid · display_name · parent)	official-doc	https://google.aip.dev/148		Google	feature-resource-identifier-contract	ca-skeleton	official-doc ca-skeleton api-design google-aip api-contract	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 (Resource names), AIP-202 (Field formats), AIP-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 예정)