-
Notifications
You must be signed in to change notification settings - Fork 5
/
problem-v1.yaml
154 lines (154 loc) · 5.81 KB
/
problem-v1.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
openapi: 3.0.0
info:
title: problem types
version: ${project.version}
servers: []
paths: {}
components:
responses:
ProblemResponse:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
description: a problem
InputValidationProblemResponse:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/InputValidationProblem"
description: A problem caused by invalid input
schemas:
Problem:
description: A Problem Details object (RFC 7807)
type: object
properties:
type:
type: string
format: uri
description: An absolute URI that identifies the problem type
default: about:blank # kept for backwards-compatibility, type will be mandatory in problem-v2
href:
type: string
format: uri
description: An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML).
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: Service Unavailable
status:
type: integer
format: int32
description: The HTTP status code generated by the origin server for this occurrence of the problem.
minimum: 400
maximum: 600
exclusiveMaximum: true
example: 503
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem
instance:
type: string
format: uri
description: An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
example:
{
"type": "urn:problem-type:belgif:payloadTooLarge",
"href": "https://www.belgif.be/specification/rest/api-guide/problems/payloadTooLarge.html", # location of linked doc will change in the future to recommended URI structure
"title": "Payload Too Large",
"status": 413,
"detail": "Request message must not be larger than 10 MB",
"instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000",
"limit": 10485760 # additional properties specific to the problem type are allowed
}
InvalidParamProblem:
deprecated: true # deprecated by InputValidationProblem
description: Problem details for invalid input parameter(s)
type: object
allOf:
- $ref: "#/components/schemas/Problem"
properties:
invalidParams:
type: array
description: An array of parameter OpenAPI violations
items:
$ref: "#/components/schemas/InvalidParam"
InvalidParam:
deprecated: true # deprecated by InputValidationIssue (within an InputValidationProblem)
type: object
properties:
in:
description: The location of the invalid parameter (cfr Swagger parameters)
type: string
enum:
- body
- path
- query
- header
name:
description: The name of the invalid parameter
type: string
value:
description: The value of the erroneous parameter
# no type specified, allowing any type. This is valid OpenAPI 3.0 even though some editors may indicate an error (issue #25)
InputValidationProblem:
type: object
allOf:
- $ref: "#/components/schemas/Problem"
properties:
issues:
type: array
items:
$ref: "#/components/schemas/InputValidationIssue"
example:
type: urn:problem-type:belgif:badRequest
href: https://www.belgif.be/specification/rest/api-guide/problems/badRequest.html
title: Bad Request
status: 400
detail: "The input message is incorrect"
instance: urn:uuid:123456-1234-1235-4567489798
issues:
- type: urn:problem-type:belgif:input-validation:schemaViolation #mandatory
# href: TODO: foresee dereferenceable link for belgif input validation problems
title: "Input isn't valid with respect to schema"
detail: enterpriseNumber abc should be numeric # recommended, if more detail can be provided
in: path
name: enterpriseNumber
value: abc
- type: urn:problem-type:cbss:input-validation:replacedSsin # example of custom input validation issue defined by organization "CBSS"
href: https://api.ksz-bcss.fgov.be/problems/replacedSsin
title: "SSIN has been replaced. Use new ssin."
detail: "SSIN 12345678901 has been replaced by 23456789012"
in: body
name: parent[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: period
value:
startDate: "2020-12-31"
endDate: "2020-01-01"
- type: urn:problem-type:cbss:input-validation:invalidSsin
title: "There is no person with the given SSIN"
in: path
name: ssin
value: "12345678911"
InputValidationIssue:
type: object
allOf:
- $ref: "#/components/schemas/Problem"
# status property of Problem is usually not used for input validation issues
properties:
in:
type: string
enum:
- body
- header
- path
- query
name:
type: string
value: {} # any type allowed