State model contents

The model for a state includes all the information an API client would need to build a form (not necessarily an HTML form) to show the user. A state model should not include the text for messages to display to the user.

Defining messages for users, and localizing them if needed, is the responsibility of the API client. One of the reasons we avoid including messages in state models is that those messages will often end up including semantic content that the API client needs to drive its code. Following the rule that models do not include messages helps ensure that our models include all the fields that an API client needs to provide the desired user experience.

Sometimes following this rule requires you to add more states. This is preferable to embedding the state information inside of a message because it makes it easier for an API client to handle that state in the desired way.

The one exception we have to this rule is around error messages. API errors include error message text, and in some cases, API clients will display the message text directly to users. This avoids every API client having to write its own messages for every user-facing error the API can generate. For more information, see [pf_error_messages_localization].