address comment by updating problem schema (#855)

Author: ktsypkina

chapters/http-status-codes-and-errors.adoc

@@ -461,16 +461,16 @@ proper guidance for handling batch/bulk requests and responses, we herewith
 define the following approach:
 
 * A batch or bulk request *always* responds with HTTP status code {207}
-  unless a non-item-specific failure occurs.
+unless a non-item-specific failure occurs.
 
 * A batch or bulk request *may* return {4xx}/{5xx} status codes, if the
-  failure is non-item-specific and cannot be restricted to individual items of
-  the batch or bulk request, e.g. in case of overload situations or general
-  service failures.
+failure is non-item-specific and cannot be restricted to individual items of
+the batch or bulk request, e.g. in case of overload situations or general
+service failures.
 
 * A batch or bulk response with status code {207} *always* returns as payload
-  a multi-status response containing item specific status and/or monitoring
-  information for each part of the batch or bulk request.
+a multi-status response containing item specific status and/or monitoring
+information for each part of the batch or bulk request.
 
 **Note:** These rules apply _even in the case_ that processing of all
 individual parts _fail_ or each part is executed _asynchronously_!
@@ -529,23 +529,23 @@ providing further details to the client. There are two approaches a service
 can take for header information:
 
 * Return a {Retry-After} header indicating how long the client ought to wait
-  before making a follow-up request. The Retry-After header can contain a HTTP
-  date value to retry after or the number of seconds to delay. Either is
-  acceptable but APIs should prefer to use a delay in seconds.
+before making a follow-up request. The Retry-After header can contain a HTTP
+date value to retry after or the number of seconds to delay. Either is
+acceptable but APIs should prefer to use a delay in seconds.
 * Return a trio of `X-RateLimit` headers. These headers (described below) allow
-  a server to express a service level in the form of a number of allowing
-  requests within a given window of time and when the window is reset.
+a server to express a service level in the form of a number of allowing
+requests within a given window of time and when the window is reset.
 
 The `X-RateLimit` headers are:
 
 * `X-RateLimit-Limit`: The maximum number of requests that the client is
-  allowed to make in this window.
+allowed to make in this window.
 * `X-RateLimit-Remaining`: The number of requests allowed in the current
-  window.
+window.
 * `X-RateLimit-Reset`: The relative time in seconds when the rate limit window
-  will be reset. **Beware** that this is different to Github and Twitter's
-  usage of a header with the same name which is using UTC epoch seconds
-  instead.
+will be reset. **Beware** that this is different to Github and Twitter's
+usage of a header with the same name which is using UTC epoch seconds
+instead.
 
 The reason to allow both approaches is that APIs can have different
 needs. Retry-After is often sufficient for general load handling and
@@ -568,63 +568,21 @@ number of requests made within a given window for each named entity.
 errors in API responses. It serves several purposes:
 
 * Developers: to debug, diagnose and resolve issues during API integration or
-  operation
+operation
 * Client applications: to inform users about errors (in user interface) and to
-  support automated processing and error handling when appropriate.
+support automated processing and error handling when appropriate.
 
-==== Problem schema members, suppported by the API guidelines
-Problem detail objects can have the following members.
+==== Problem schema members, supported by the API guidelines
+Problem detail objects can have the following members described in the OpenAPI
+schema definition
+https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml[on
+GitHub].
 
 **Note:** If a member's value type does not match the specified type,
 the member MUST be ignored -- i.e., processing will continue as if
 the member had not been present.
 
-===== status (integer)
-The HTTP status code generated by the origin server for occurrences of the problem.
-Example:
-
-    `"status": 400`
-
-===== title (string)
-A short, human-readable summary of the problem type. It *SHOULD NOT* change
-from occurrence to occurrence of the problem, except for purposes of
-localization.
-Example:
-
-    `"title": "Invalid parameter"`
-
-===== detail (string)
-A human-readable explanation specific to this occurrence of the problem.
-Provides additional context or specifics about the error for debugging
-or display to the user.
-Example:
-
-    `"detail": "The 'color' parameter is invalid"`
-
-===== type and instance (URI references)
-The standardized Problem JSON object also allows for the following optional
-members:
-
-- type: a URI identifying the problem type, typically more specific than the
-  HTTP status code. In many cases, an error code can be placed in the type
-  property. It may support automated client decisions in certain failure modes.
-  If the `type` doesn’t provide additional information, it can be omitted
-  (defaulting to `"about:blank"`).
-- instance: a URI reference that identifies specific occurrence of the problem.
-  This field should serve the purpose of defining a clear error instance from
-  which the developer can determine the source location of the error.
-  Additionally, it may include relevant contextual information, such as parameters
-  associated with the error and optionally `Flow-ID` for debugging purposes.
-
-Examples:
-
-`"type": "https://example.com/errors/invalid-parameter"`
-
-`"type": "https://example.com/errors/ERR12345" (with error code)`
-
-`"instance": "/errors/12345"`
-
-*Note:* {RFC-9457}[RFC 9457] encourages that problem types are URI
+{RFC-9457}[RFC 9457] encourages that problem types are URI
 references that point to human-readable documentation, *but* we deliberately
 decided against that, as all important parts of the API must be documented
 using <<101, OpenAPI>> anyway. In addition, URLs tend to be fragile and not
@@ -644,7 +602,7 @@ identifiers in `type` and `instance` fields:
 *Hint:* The use of https://tools.ietf.org/html/rfc3986#section-4.3[absolute
 URIs] is not forbidden but strongly discouraged. If you use absolute URIs,
 please reference
-https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.0.yaml#/Problem[problem-1.0.0.yaml#/Problem]
+https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml#/Problem[problem-1.0.1.yaml#/Problem]
 instead.
 
 ==== Usage of Problem Object
@@ -654,9 +612,9 @@ properties being present or having specific values.
 The examples of such cases are:
 
 - response might be created by infrastructure components (and have a different
-  response format, comparing to the guidelines)
+response format, comparing to the guidelines)
 - response might be created by a service that is unable to comply with the
-  guidelines due to certain error situations
+guidelines due to certain error situations
 
 In cases where the Problem Object lacks the required information, clients must
 implement fallback mechanisms, defaulting to reasonable behavior similar to
@@ -694,21 +652,21 @@ The following guidelines offer best practices for utilizing type in automated
 processing:
 
 1. Property `type` may be used by clients to make automatic decisions in
-  certain failure modes. The `title` property serves as a concise,
-  human-readable summary of the type. It is particularly helpful for debugging
-  and serves as an engineer-readable shorthand for the problem type.
+certain failure modes. The `title` property serves as a concise,
+human-readable summary of the type. It is particularly helpful for debugging
+and serves as an engineer-readable shorthand for the problem type.
 
 2. Clients may use these fields to drive automated actions if the API
-  explicitly defines the semantics of `type` and `instance` and enumerates
-  stable values. This can be achieved by extending the Problem JSON object and
-  associating an x-extensible-enum with the type property.
+explicitly defines the semantics of `type` and `instance` and enumerates
+stable values. This can be achieved by extending the Problem JSON object and
+associating an x-extensible-enum with the type property.
 
 3. Clients must handle scenarios where the type is absent or unrecognized and
-  fallback to default behaviors.
+fallback to default behaviors.
 
 4. For collections of related APIs, using shared type values for similar errors
-  and distinct values for different errors simplifies automated processing and
-  error handling for clients working across APIs.
+and distinct values for different errors simplifies automated processing and
+error handling for clients working across APIs.
 
 *Note:* Include descriptions for each known error that can happen directly in
 the specification or reference external documentation to clarify their meanings
@@ -788,9 +746,9 @@ redirection to migrate clients to a new service location. However, this is
 better accomplished by one of the following.
 
 1. Changing the clients to use the new location in the first place, avoiding
-   the need for redirection.
+the need for redirection.
 2. Redirecting the traffic behind the API layer (e.g. in the reverse proxy or
-   the app itself) without the client having to be involved.
+the app itself) without the client having to be involved.
 3. Deprecating the endpoint and removing it as described in <<deprecation>>.
 
 For idempotent {POST} cases, where you want to inform the client that a resource

models/problem-1.0.1.yaml

@@ -5,19 +5,23 @@ Problem:
       type: string
       format: uri-reference
       description: >
-        A URI reference that uniquely identifies the problem type only in the
-        context of the provided API. Opposed to the specification in RFC-9457,
-        it is neither recommended to be dereferenceable and point to a
-        human-readable documentation nor globally unique for the problem type.
+        An optional member, URI identifying the problem type, typically more
+        specific than the HTTP status code. In many cases, an error code can be
+        placed in the type property. It may support automated client decisions
+        in certain failure modes. If the type doesn’t provide additional 
+        information, it can be omitted (defaulting to `"about:blank"`).
       default: 'about:blank'
-      example: '/some/uri-reference'
+      examples:
+        - 'https://example.com/errors/invalid-parameter'
+        - 'https://example.com/errors/ERR12345'  # with error code
     title:
       type: string
       description: >
-        A short summary of the problem type. Written in English and readable
-        for engineers, usually not suited for non technical stakeholders and
-        not localized.
-      example: some title for the error situation
+        A short, human-readable summary of the problem type. It *SHOULD NOT*
+        change from occurrence to occurrence of the problem. Written in English
+        and readable for engineers, usually not suited for non-technical
+        stakeholders and not localized.
+      example: 'Invalid parameter'
     status:
       type: integer
       format: int32
@@ -27,19 +31,24 @@ Problem:
       minimum: 100
       maximum: 600
       exclusiveMaximum: true
+      example: 400
     detail:
       type: string
       description: >
         A human readable explanation specific to this occurrence of the
         problem that is helpful to locate the problem and give advice on how
         to proceed. Written in English and readable for engineers, usually not
         suited for non technical stakeholders and not localized.
-      example: some description for the error situation
+      example: 'The \"color\" parameter is invalid'
     instance:
       type: string
       format: uri-reference
       description: >
         A URI reference that identifies the specific occurrence of the problem,
         e.g. by adding a fragment identifier or sub-path to the problem type.
-        May be used to locate the root of this problem in the source code.
-      example: '/some/uri-reference#specific-occurrence-context'
+        This field should serve the purpose of defining a clear error instance 
+        from which a developer can determine the source location of the error.
+        Additionally, it may include relevant contextual information, such as 
+        parameters associated with the error and optionally `Flow-ID` for 
+        debugging purposes.
+      example: '/errors/12345'