AIP-141

Quantities

Many services need to represent a discrete quantity of items (number of bytes, number of miles, number of nodes, etc.).

Guidance

Quantities with a clear unit of measurement (such as bytes, miles, and so on) must include the unit of measurement as the suffix. When appropriate, units should use generally accepted abbreviations, and abbreviations should not be pluralized (for example, distance_km rather than distance_kilometers). 

// A representation of a non-stop air route.
message Route {
  // The airport where the route begins.
  string origin = 1;

  // The destination airport.
  string destination = 2;

  // The distance between the origin and destination airports.
  // This value is also used to determine the credited frequent flyer miles.
  int32 distance_miles = 3;
}

If the quantity is a number of items (for example, the number of nodes in a cluster), then the field should use the suffix _count (not the prefix num_):

// A cluster of individual nodes.
message Cluster {
  // The number of nodes in the cluster.
  int32 node_count = 1;
}

Note: Fields must not use unsigned integer types, because many programming languages and systems do not support them well.

Compound units

Quantities with compound units of measurement may use separating underscores between units as needed for clarity. Unabbreviated units must be separated. Abbreviated units should not be separated unless otherwise ambiguous. Compound units should be in plural form, with all component units in singular form except for the final component unit, which should be in plural form unless abbreviated.

  • energy_kwh (not energy_kw_h)
  • energy_kw_fortnights (not energy_kwfortnight or energy_kw_fortnight)

Note: Metric prefixes must not be separated from their base unit.

Inverse units

Quantities with units of measurement that are or include inverse units should indicate all inverse units as a compound unit after a compound of any non-inverse units, separated by the word "per". The inverse compound unit should be in singular form.

  • speed_miles_per_hour (not speed_mph)
  • speed_meters_per_second (not speed_meters_per_seconds or speed_meter_per_second)
  • event_count_per_hour (not events_per_hour, event_counts_per_hour, or hourly_events)
  • price_per_kwh (using google.type.Money)

Note: This guidance does not apply in cases where generally accepted derived units with special names and symbols exist for inverse quantities. For example, the derived unit 'hertz' should be used when appropriate for reciprocal time.

Specialized messages

It is sometimes useful to create a message that represents a particular quantity. This is particularly valuable in two situations:

APIs may create messages to represent quantities when appropriate. When using these messages as fields, APIs should use the name of the message as the suffix for the field name if it makes intuitive sense to do so.

Changelog

  • 2025-07-09: Added guidance for compound units.
  • 2025-07-09: Clarified guidance to not pluralize abbreviated units.
  • 2025-07-09: Clarified guidance to use per_ prefix to represent inverse units.
  • 2019-09-13: Added the prohibition on uint and fixed types.