diff --git a/aip/general/0140.md b/aip/general/0140.md index 5001987304..759ea1f2b5 100644 --- a/aip/general/0140.md +++ b/aip/general/0140.md @@ -77,11 +77,8 @@ This is particularly true regarding "with": a field named `book_with_publisher` likely indicates that the book resource may be improperly structured and worth redesigning. -**Note:** The word "per" is an exception to this rule, particularly in two -cases. Often "per" is part of a unit (e.g. "miles per hour"), in which case the -preposition must be present to accurately convey the unit. Additionally, "per" -is often appropriate in reporting scenarios (e.g. "nodes per instance" or -"failures per hour"). +**Note:** The word "per" is an exception to this rule. See [AIP-141][] for +guidance in the case where "per" is used as part of a unit (e.g. "miles per hour"). ### Abbreviations diff --git a/aip/general/0141.md b/aip/general/0141.md index 48f4270262..51f27a4b57 100644 --- a/aip/general/0141.md +++ b/aip/general/0141.md @@ -16,8 +16,8 @@ number of miles, number of nodes, etc.). 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`). +**should** use generally accepted abbreviations, and abbreviations **should not** +be pluralized (for example, `distance_km` rather than `distance_kilometers`). ```proto // A representation of a non-stop air route. @@ -49,6 +49,36 @@ message Cluster { **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`][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 @@ -65,6 +95,9 @@ 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.