Problem type example could be less specific

[jpraet]

Often, a default problem response will be added to REST API's, referencing the belgif/problem/v1/problem-v1.yaml#/components/responses/ProblemResponse type.

In the generated swagger doc this becomes:

This example feels a bit out of place, as it is a very specific type of problem.

An alternative more generally applicable example could be:

{
  "type": "urn:problem-type:belgif:internalServerError",
  "href": "https://www.belgif.be/specification/rest/api-guide/problems/internalServerError.html",
  "title": "Internal Server Error"
  "status": 500,
  "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000"
}

[pvdbosch]

Discussed in WG: OK to change the problem example.
Similar for InputValidationProblem.

Having a response for status 500 when specifying generic Problem type for a 4xx code may be confusing as well.

To try out if it's possible to override example per explicit response status code; and if it's manageable. If not we can fall back to a generic example problem type that's clearly not used in practice.

[pvdbosch]

We could also add a link in the OpenAPI documentation of a Problem or ProblemResponse to the standardized belgif URNs on https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types .
Especially for a default ProblemResponse type, users need to be able to find the list of problem types that can be returned.

Alternatively, in OpenAPI 3, examples could be added for each of these types, but this would become more difficult to maintain.

[pvdbosch]

Example from schema can be overridden in response object:

       "409":
         description: Conflict
         content:
           application/problem+json:
             schema:
               $ref: "./types.yaml#/components/schemas/Problem"
             example: {
               "custom": "example"
             }

However, it cannot be overridden when $ref-fing the response object:

$ref: "./belgif/openapi-problem.yaml#/components/responses/ProblemResponse".

PR created for more generic examples: https://github.com/belgif/openapi-problem/pull/13/files

[pvdbosch]

Reviewed by WG. Some changes will be made.

          "type": "urn:problem-type:exampleOrganization:exampleProblem", #exampleOrganization should be the organization that defines the problem type. "belgif" is used for problem types standardized in the Belgif REST guide
   "href":  "..." # should refer to documentation of the problem type, either a belgif standardized problem, or to documentation of a custom problem type

In input validation issue, add comment "additional properties are allowed"

move the input validation issue with replaced ssin to example of InputValidationProblem in the REST guide, in order to show an example with additional properties

[pvdbosch]

#13 for openapi-problem adapted and ready for last review pass.

belgif/rest-guide#155 also ready for review:

• adapted request and problem example to be coherent and stay in "enterprises" domain
• three issue types are now in the example input validation problem response:
  • one 'normal' schemaViolation issue
  • a custom "replacedSsin" issue type to illustrate the use of additional properties in an issue
  • a custom "invalidPeriod" issue type to illustrate that "value" can be of object type

[pvdbosch]

changes merged, I'll create a patch release