feat(AIP-193): specify how to "change" messages. (#1098)

Introduces the concept that `LocalizedMessage` can be used to include a second error message aside from the debug message on `Status`. This message can be updated ongoingly. Further, explains how to use the `metadata` `map<string, string>` on `ErrorInfo` for dynamic variables found in error messages and otherwise.

Fixes: #1096

Author: shwoodard

aip/general/0193.md

@@ -32,6 +32,39 @@ Error messages **should** be brief but actionable. Any extra information
 necessary, you **should** provide a link where a reader can get more
 information or ask questions to help resolve the issue.
 
+
+A JSON representation of an error response might look like the
+following:
+
+<a name="sample"></a>
+
+```json
+{
+  "error": {
+    "code": 429,
+    "message": "The zone 'us-east-1' does not have enough resources available to fulfill the request. Try a different zone, or try again later.",
+    "status": "RESOURCE_EXHAUSTED",
+    "details": [
+      {
+        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+        "reason": "STOCKOUT",
+        "domain": "compute.googleapis.com",
+        "metadata": {
+          "zone": "us-east1-a",
+          "vmType": "e2-medium",
+          "attachment": "local-ssd=3,nvidia-t4=2"
+         }
+       },
+       {
+        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
+        "locale": "en-US",
+        "message": "A e2-medium with local-ssd=3,nvidia-t4=2 is currently unavailable in the us-east1-a zone.\nCapacity changes frequently, so try your request in a different zone, with a different VM hardware configuration, or at a later time. For more information, see troubleshooting documentation."
+       }
+    ]
+  }
+}
+```
+
 ### Details
 
 Google defines a set of [standard detail payloads][details] for error details,
@@ -62,11 +95,117 @@ a [`PreconditionFailure`][PreconditionFailure].
 **Note:** `ErrorInfo` represents a special case. There **must** be exactly one
 `ErrorInfo`. It is required.
 
-### Localization
+### Error messages
+
+For each error, the service **must** populate the `message` field on
+[`google.rpc.Status`][Status]. This error message,
+
+- is a developer-facing, human-readable "debug message"
+- is presented in the service's native language
+- both explains the error and offers an actionable resolution to it
+  ([citation](https://cloud.google.com/apis/design/errors#error_model))
+
+**Note:** Sometimes a service will elect to always present
+`Status.message` in English rather than the application's native
+language so that messages are easily searchable in common knowledge
+bases, such as StackOverflow&trade;.
+
+When introducing an error that represents a failure scenario that did
+not previously occur for the service, the payload **must** include
+`ErrorInfo` and any variables found in dynamic segments of the error
+message **must** be present in `ErrorInfo.metadata`. See, "[Dynamic
+variables](#dynamic-variables)".
+
+#### Changing error messages
+
+<a name="status-message-warning"></a>
+
+`Status.message` **may** change. However, **use extreme caution** when
+doing so.  API consumers often treat this error message as **part of the
+API contract**. Clients perform string matches on the text to
+differentiate one error for another and even parse the error message to
+extract variables from dynamic segments.
+
+There is a safer alternative. The service can chose to include an error
+message by adding [`google.rpc.LocalizedMessage`][LocalizedMessage] to
+[`Status.details`][Status details].
+
+The error message presented in `LocalizedMessage.message` **may** be the
+same as `Status.message` or it **may** be an alternate message.
+
+Reasons to present the same error message in both locations include the
+following:
+
+- The service plans to localize either immediately or in the near
+  future.  See, "[Localization](#localization)".
+- It affords clients the ability to find an error message consistently
+  in one location, `LocalizedMessaage.message`, across all methods of
+  the API Service.
+
+Reasons to present an error message in `LocalizedMessage.message` that
+differs from `Status.message` include the following:
+
+- The service requires an end-user facing error message that differs
+  from the "debug message".
+- Ongoing, iterative error message improvements are expected.
 
-Error messages **must** be in English. If a localized error message is also
-required, the service **should** use [`google.rpc.LocalizedMessage`][details]
-in the `details` field.
+When including `LocalizedMessage`, both fields, `locale` and `message`,
+**must** be populated.  If the service is to be localized, the value of
+`locale` **must** change dynamically. See,
+"[Localization](#localization)". Otherwise, `locale` **must** always
+present the service's default locale, e.g. "en-US".
+
+When adding an error message via `LocalizedMessage`, `ErrorInfo`
+**must** be introduced either before or at the same time. If there are
+dynamic segments found in the text, the values of these variables
+**must** be included in `ErrorInfo.metadata`.  See, "[Dynamic
+variables](#dynamic-variables)".
+
+**Warning:** If `LocalizedMessage` is released without `ErrorInfo`, the
+same [concerns](#status-message-warning) regarding client misuse of
+textual error messages apply.
+
+#### Dynamic variables
+
+The best, actionable error messages include dynamic segments. These
+variable parts of the message are specific to a particular request.
+Consider the following example:
+
+> The Book, "The Great Gatsby", is unavailable at the Library, "Garfield
+> East". It is expected to be available again on 2199-05-13.
+
+The preceding error message is made actionable by the context, both that
+originates from the request, the title of the Book and the name of the
+Library, and by the information that is known only by the service, i.e.
+the expected return date of the Book.
+
+All dynamic variables found in error messages **must** also be present
+in the `map<string, string>`, `ErrorInfo.metadata` (found on the
+*required* `ErrorInfo`).  For example, the `metadata` map for the sample
+error message above will include *at least* the following key/value
+pairs:
+
+```yaml
+bookTitle: "The Great Gatsby"
+library: "Garfield East"
+expectedReturnDate: "2199-05-13"
+```
+
+Dynamic variables that do not appear in an error message **may** also be
+included in `metadata` to provide additional information to the client
+to be used programmatically.
+
+Once present in `metadata`, keys **must** continue to be included in the
+map for the error payload to be backwards compatible, even if the value
+for a particular key is empty. Keys **must** be expressed as lower
+camel-case.
+
+#### Localization
+
+The value of `Status.message` **should** be presented in the service's
+native language. If a localized error message is required, the service
+**must** include [`google.rpc.LocalizedMessage`][LocalizedMessage] in
+`Status.details`.
 
 ### Partial errors
 
@@ -96,16 +235,26 @@ does not exist, the service **must** error with `NOT_FOUND` (HTTP 404).
 
 ## Rationale
 
-`ErrorInfo` is required because it further identifies an error. The
-`Status` field, with under 20 [allowed values][Code], is rarely enough
-to disambiguate one error from another accross an entire API Service.
-Error messages often contain dynamic segments that express values, such
-as project numbers or locations, and these values are often read from
-the string message using brittle extraction methods, like RegExp. There
-needs to be a machine readable component of *every* error response that
-enables clients to pull such information programatically--without
-parsing the string error message. For these reasons, `ErrorInfo` is
-required for *every* error response.
+### Requiring ErrorInfo
+
+`ErrorInfo` is required because it further identifies an error. With
+only approximately twenty [available values][Code] for `Status.status`,
+it is difficult to disambiguate one error from another across an entire
+[API Service][API Service].
+
+Also, error messages often contain dynamic segments that express
+variable information, so there needs to be machine readable component of
+*every* error response that enables clients to use such information
+programmatically.
+
+### LocalizedMessage
+
+`LocalizedMessage` was selected as the location to present alternate
+error messages. This is desirable when clients need to display a crafted
+error message directly to end users. `LocalizedMessage` can be used with
+a static `locale`. This may seem misleading, but it allows the service
+to eventually localize without having to duplicate or move the error
+message, which would be a backwards incompatible change.
 
 ## Further reading
 
@@ -115,6 +264,9 @@ required for *every* error response.
 
 ## Changelog
 
+- **2023-05-17**: Change the recommended language for `Status.message`
+  to be the service's native language rather than English.
+- **2023-05-17**: Specify requirements for changing error messages.
 - **2023-05-10**: Require [`ErrorInfo`][ErrorInfo] for all error
   responses.
 - **2023-05-04**: Require uniqueness by message type for error details.
@@ -133,8 +285,11 @@ required for *every* error response.
 [ErrorInfo]: https://github.com/googleapis/googleapis/blob/6f3fcc058ff29989f6d3a71557a44b5e81b897bd/google/rpc/error_details.proto#L27-L76
 [PreconditionFailure]: https://github.com/googleapis/googleapis/blob/6f3fcc058ff29989f6d3a71557a44b5e81b897bd/google/rpc/error_details.proto#L139-L166
 [BadRequest]: https://github.com/googleapis/googleapis/blob/477a59d764428136ba1d857a9633c0d231de6efa/google/rpc/error_details.proto#L168-L218
+[LocalizedMessage]: https://github.com/googleapis/googleapis/blob/e9897ed945336e2dc967b439ac7b4be6d2c62640/google/rpc/error_details.proto#L275-L285
 [grpc status code documentation]: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
 [Code]: https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto
 [Status]: https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto
+[Status details]: https://github.com/googleapis/googleapis/blob/aeae5ea2b01ece6c0cee046ae84b881cdc62b95d/google/rpc/status.proto#L46-L48
 [long-running operations]: ./0151.md
+[API Service]: https://cloud.google.com/apis/design/glossary#api_service
 <!-- prettier-ignore-end -->