Skip to main content

JSON

Notation follows the APIs index.

  1. Dates MUST be formatted in ISO 8601 format, such as 2026-01-01T00:00:00Z, and MUST include a time zone indicator and SHOULD standardize on UTC.
  2. Field values that are constrained to a fixed set of values SHOULD enumerate the valid values in all caps, such as OWNER, ADMIN, and USER, restricted to only ASCII characters, in both the OpenAPI spec and in example JSON to help distinguish these fields from free-text string fields. At runtime, however, APIs MUST ignore case when validating these values.
  3. APIs SHOULD strip leading and trailing whitespace from all strings before processing them.
  4. APIs MUST treat an empty string the same as if the field is not present.
  5. APIs MUST treat a field that is not present the same as null, except in partial updates.
  6. APIs SHOULD NOT include null fields in responses.
note
  1. An empty string is treated as not present because a system where "" and null mean two different things requires every caller, every service, and every database column to agree on the distinction. This can be a challenge to preserve as data gets serialized to and from various representations across various languages and, in our experience, this is one class of bug that can be entirely eliminated by just treating them the same.