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 (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.

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

  • 2019-09-13: Added the prohibition on uint and fixed types.