Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve InputValidationProblem example #155

Merged
merged 2 commits into from
Jan 30, 2024
Merged

Improve InputValidationProblem example #155

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c69b9f5
Improve InputValidationProblem example
pvdbosch Nov 27, 2023
9832d3b
Align InputValidationProblem schema with latest
pvdbosch Nov 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions guide/src/main/asciidoc/errorhandling.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,20 +238,29 @@ InputValidationProblem:
$ref: "#/components/schemas/InputValidationIssue"
InputValidationIssue:
type: object
description: |
An issue detected during input validation.

`status` is usually not present.
`href`, if present, refers to documentation of the issue type.
Additional properties specific to the issue type may be present.
allOf:
- $ref: "#/components/schemas/Problem"
# status property of Problem is usually not used for input validation issues
properties:
in:
type: string
description: The location of the invalid input
enum:
- body
- header
- path
- query
name:
type: string
value: {} # any type allowed
description: The name of the invalid input
value:
description: The value of the erroneous input
# no type specified, allowing any type. This is valid in OpenAPI even though some editors may indicate an error
```

The possible `type` values used within `issues` should be documented for each API. They follow the same URN structure as problem types. It is RECOMMENDED to use `input-validation` as infix to distinguish them.
Expand Down
45 changes: 34 additions & 11 deletions guide/src/main/asciidoc/problems/badRequest.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,16 @@ The following issue types may be returned by any API:
POST /enterprises/abc

{
"mandator": {
"enterpriseNumber": "123456"
}
"name": "exampleEnterprise",
"boardMembers": [
{
"ssin": "12345678901",
"period": {
"startDate": "2020-12-31",
"endDate": "2020-01-01"
}
}
]
}
```

Expand All @@ -33,24 +40,40 @@ Content-Type: application/problem+json
{
"type": "urn:problem-type:belgif:badRequest",
"href": "https://www.belgif.be/specification/rest/api-guide/problems/badRequest.html",
"status": 400,
"title": "Bad Request",
"status": 400,
"detail": "The input message is incorrect",
"instance": "urn:uuid:123456-1234-1235-4567489798",
"issues": [
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not that important, but in practice a combination of schemaValidation and non-schemaValidation issues within the same Bad Request problem is very unlikely, as the schemaValidation typically is done on an API Gateway, and the other validations are done on application level.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, it's just an example to illustrate that it could be done.
There are cases that I know of where all types of validation or done by the backend (using generated classes with Jakarta Bean Validation). Clients shouldn't depend on order or grouping of validations.

{
"type": "urn:problem-type:belgif:input-validation:schemaViolation",
"title": "Input isn't valid with respect to schema",
"detail": "enterpriseNumber abc should be numeric",
"in": "path",
"name": "enterpriseNumber",
"value": "abc",
"detail": "value should be numeric"
"value": "abc"
},
{
"type": "urn:problem-type:belgif:input-validation:schemaViolation",
"type": "urn:problem-type:cbss:input-validation:replacedSsin",
"href": "https://example.cbss.be/problems/replacedSsin",
"title": "SSIN has been replaced. Use new SSIN.",
"detail": "SSIN 12345678901 has been replaced by 23456789012",
"in": "body",
"name": "boardMembers[0].ssin",
"value": "12345678901",
"replacedBy": "23456789012"
},
{
"type": "urn:problem-type:cbss:input-validation:invalidPeriod",
"title": "Period is invalid",
"detail": "endDate should be after startDate",
"in": "body",
"name": "mandator.enterpriseNumber",
"value": "123456",
"detail": "An enterprise number should be 10 digits long"
"name": "boardMembers[0].period",
"value": {
"startDate": "2020-12-31",
"endDate": "2020-01-01"
}
}
]
]
}
```