Updates AIP-140 and AIP-141 with guidance on naming quantity fields with compound and/or inverse units

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
 

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.
 
 <!-- prettier-ignore-start -->