A dictionary, or map, stores key-value pairs. Keys identify associated values and can be defined dynamically. Unlike a custom data type with a predefined schema, a map suits arbitrary data whose structure is not known in advance. section 5.7
Choose between a map and a schema-based structure deliberately:
- Use a custom data type to group known, related fields while preserving explicit names and value types. section 5.7
- Use a map for arbitrary, dynamic data with no expected structure, such as user-defined attributes or measurements. section 5.7
- Bound the number of entries, key lengths, and value lengths; otherwise, a map can grow like an unbounded list. section 5.7.1
- Avoid using a total-character limit as the default solution, because it can encourage moving increasingly large data into the map instead of a better structure. section 5.7.1
Ingredient measurements
A grocery item can keep known fields such as name and calories while storing variable ingredient measurements in ingredientAmounts. Keys such as fat, sodium, and sugar map to values such as 9 g, 150 mg, and 1 g.
Maps can also appear inside resources. Partial retrievals and updates can address nested map entries through field masks: separate path components with dots, quote nonliteral keys with backticks, and treat map keys as strings. section 8.3.2
Table 8.3 A resource representation with corresponding field mask entries for each field (view table figure)
Use the field-mask table to compare nested interface paths, wildcard map selections, quoted numeric keys, escaped backticks, and keys containing dots. section 8.3.2
