Copy page

Concepts

JSON representation

Bodies are boring on purpose, and the two rules worth internalising are these: every name is snake_case, everywhere — path segments, fields, query parameters, enum values, custom-method verbs — and an unset field is absent, never null. A response you can predict is a response you can parse once.

The other half of this page is what every resource carries whatever it is: its name and id, when it was made and last changed, and the etag that makes a safe write possible. Each field also declares its behavior — required, output-only, immutable — and that declaration is in the reference, on the field, not in a paragraph somebody has to remember to update.

11. JSON representation

• Naming. snake_case for every field, query parameter and enum value (D1). No abbreviations that are not already in the domain vocabulary.
• Absent vs null. In a response, an unset optional field is omitted; null is never emitted. In a request, null means "clear this field" and is only honoured together with update_mask (§7).
• Booleans are true/false. Never 1/0, never "true".
• Numbers are JSON numbers. An int64 that can exceed 2^53 is a string — none exist today, and if one appears it MUST be documented.
• Enums are UPPER_SNAKE_CASE strings, never integers. Every enum reserves a zero-value <NAME>_UNSPECIFIED and clients MUST tolerate an unknown value rather than failing (AIP-126) — that is what lets us add one without a version bump.
• Timestamps are RFC 3339 UTC strings: "2026-08-24T10:15:30Z". Not epoch milliseconds.
• Durations are strings with a unit suffix ("3.5s"), per AIP-142.
• Dates without a time are "2026-08-24".
• Money takes the google.type.Money shape — { "currency_code": "BRL", "units": "12", "nanos": 500000000 }. Never a float, on the wire or behind it: the AI platform's balances and charges are int64 nanos of a currency all the way down, and the one place a fraction of a cent would be rounded away is named where it happens.
• Empty arrays are emitted, empty objects are omitted. visible_view_ids: [] is meaningful (it means "all views") and must survive a round trip.

12. Standard fields

Every resource MUST carry:

Field	Behavior	Notes
name	OUTPUT_ONLY	Full resource name (§5).
id	OUTPUT_ONLY	Final segment of name (D3). Absent on a singleton, which has no such segment (§9).
create_time	OUTPUT_ONLY	RFC 3339. Renamed from created_at.
update_time	OUTPUT_ONLY	RFC 3339. Renamed from updated_at.
etag	OUTPUT_ONLY	Required on any resource with concurrent editors (§14).

And SHOULD use these names when the concept applies (AIP-148): display_name, title, description, parent, delete_time, expire_time, uid, labels, annotations. A resource MUST NOT invent a synonym for one of them.

Field behavior (AIP-203)

Every field is exactly one of:

• REQUIRED — Create fails INVALID_ARGUMENT without it.
• OPTIONAL — the default.
• OUTPUT_ONLY — server-set; ignored if sent (D5).
• IMMUTABLE — settable on Create, rejected with INVALID_ARGUMENT on Update.
• INPUT_ONLY — accepted, never echoed (passwords, one-time tokens).

The behavior is part of the contract and MUST appear in the generated OpenAPI document. It is not a comment.