Custom Error Messages
You can also specify custom error messages for JSON schema validation rules, as explained in Custom Validation Rules and Error Messages.
A full list of options & usage scenarios could be found in the documentation of AJV errors.
One request body specification could contain multiple content types. Our
supported content types are json, urlencoded, and text. The client should
set Content-Type http header to application/json,
application/x-www-form-urlencoded, or text/plain. Its value is matched
against the list of media types defined in the requestBody.content object of
the OpenAPI operation spec. If no matching media types is found or the type is
not supported yet, an UnsupportedMediaTypeError (http statusCode 415) will be
reported.
Please note that urlencoded media type does not support data typing. For
example, key=3 is parsed as {key: '3'}. The raw result is then coerced by
AJV based on the matching content schema. The coercion rules are described in
AJV type coercion rules.
The qs is used to parse complex strings. For example, given the following request body definition:
const requestBodyObject = {
description: 'data',
content: {
'application/x-www-form-urlencoded': {
schema: {
type: 'object',
properties: {
name: {type: 'string'},
location: {
type: 'object',
properties: {
lat: {type: 'number'},
lng: {type: 'number'},
},
},
tags: {
type: 'array',
items: {type: 'string'},
},
},
},
},
},
};
The encoded value
'name=IBM%20HQ&location[lat]=0.741895&location[lng]=-73.989308&tags[0]=IT&tags[1]=NY'
is parsed and coerced as:
{
name: 'IBM HQ',
location: {lat: 0.741895, lng: -73.989308},
tags: ['IT', 'NY'],
}
The request body parser options (such as limit) can now be configured by
binding the value to RestBindings.REQUEST_BODY_PARSER_OPTIONS
(‘rest.requestBodyParserOptions’). For example,
server.bind(RestBindings.REQUEST_BODY_PARSER_OPTIONS).to({
limit: '4MB',
});
The options can be media type specific, for example:
server.bind(RestBindings.REQUEST_BODY_PARSER_OPTIONS).to({
json: {limit: '4MB'},
text: {limit: '1MB'},
});
The list of options can be found in the body-parser module.
By default, the limit is 1MB. Any request with a body length exceeding the
limit will be rejected with http status code 413 (request entity too large).
A few tips worth mentioning:
-
If a model property’s type refers to another model, make sure it is also decorated with
@modeldecorator. -
If you’re using API first development approach, you can also provide the request body specification in decorators like
route()andapi(), this requires you to provide a completed request body specification.
Extend Request Body Parsing
See Extending request body parsing for more details.
Specify Custom Parser by Controller Methods
In some cases, a controller method wants to handle request body parsing by
itself, such as, to accept multipart/form-data for file uploads or stream-line
a large json document. To bypass body parsing, the 'x-parser' extension can be
set to 'stream' for a media type of the request body content. For example,
class FileUploadController {
async upload(
@requestBody({
description: 'multipart/form-data value.',
required: true,
content: {
'multipart/form-data': {
// Skip body parsing
'x-parser': 'stream',
schema: {type: 'object'},
},
},
})
request: Request,
@inject(RestBindings.Http.RESPONSE) response: Response,
): Promise<object> {
const storage = multer.memoryStorage();
const upload = multer({storage});
return new Promise<object>((resolve, reject) => {
upload.any()(request, response, err => {
if (err) reject(err);
else {
resolve({
files: request.files,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
fields: (request as any).fields,
});
}
});
});
}
}
The x-parser value can be one of the following:
- Name of the parser, such as
json,raw, orstream
stream: keeps the http request body as a stream without parsingraw: parses the http request body as aBuffer
{
'x-parser': 'stream'
}
- A body parser class
{
'x-parser': JsonBodyParser
}
- A body parser function, for example:
function parseJson(request: Request): Promise<RequestBody> {
return new JsonBodyParser().parse(request);
}
{
'x-parser': parseJson
}
Localizing Errors
A body data may break multiple validation rules, like missing required fields,
data in a wrong type, data that exceeds the maximum length, etc…The validation
errors are returned in batch mode, and user can find all of them in
error.details, which describes errors in a machine-readable way.
Each element in the error.details array reports one error. It contains 4
attributes:
path: The path to the invalid field.code: A single word code represents the error’s type.message: A human readable description of the error.info: Some additional details that the 3 attributes above don’t cover.
In most cases path shows which field in the body data is invalid. For example,
if an object schema’s id field should be a string, while the data in body has
it as a number: {id: 1, name: 'Foo'}. Then the error entry is:
{
path: '/id',
code: 'type',
message: 'should be string',
info: {type: 'string'},
}
And in this case the error code is type. A reference of all the possible code
could be found in
ajv validation error keywords(codes).
In some exception scenarios, like a required field is missing, the path is
empty, but the field location is easy to find in message and info. For
example, id is a required field while it’s missing in a request body:
{name: 'Foo'}, the error entry will be:
{
// `path` is empty
path: '',
code: 'required',
message: "should have required property 'id'",
// you can parse the missing field from `info.missingProperty`
info: {missingProperty: 'id'},
},