A schema formally defines a data structure’s expected keys and value types. In API resources, it makes related fields predictable and easier to organize as the resource grows. section 5.7
Choose between a predefined schema and a dynamic map based on whether the data structure is known:
- Use a custom data type or sub-resource when the keys and value types are known, especially for grouping related fields such as chat-room security settings. section 5.7
- Use a dynamic map when the data is arbitrary, changes over time, or has no expected structure. section 5.7
- Consider a separate sub-resource when grouped fields are meaningful beyond the containing resource rather than merely related configuration. section 5.7
Chat-room configuration and ingredient amounts
A ChatRoom can replace flat password and access fields with a typed securityConfig schema. A GroceryItem can instead use ingredientAmounts as a map when ingredient names and measurements vary. section 5.7
Listing 5.8 Storing data directly on a resource or in a separate structure
interface ChatRoomFlat {
id: string;
name: string;
password: string; #1
requirePassword: boolean; #1
allowAnonymousUsers: boolean; #1
allowChatBots: boolean; #1
}
interface ChatRoomReGrouped {
id: string;
name: string;
securityConfig: SecurityConfig; #2
}
interface SecurityConfig { #2
password: string;
requirePassword: boolean;
allowAnonymousUsers: boolean;
allowChatBots: boolean;
}
Compare flat resource fields with a nested SecurityConfig schema before deciding whether grouping improves the resource design. section 5.7
