Feat: Programatically interpretable validation errors

Sorting

• I’m submitting a …

  • bug report
  • feature request
  • support request

• I confirm that I

  • used the search to make sure that a similar issue hasn’t already been submit

Expected Behavior

tsoa yields validation errors that aren’t necessarily useful to interpret programatically A simple example:

/**
* @param limit Number of records to fetch
* @minimum limit 1
* @maximum limit 50
*/

Request: https://api.example.com/list?limit=200

Result:

fields: {
    limit: {
       message: "max 50",
       value: "200",
    }
},

The above error is by all means correct but it is not very useful if you want to interpret it. Looking at the templateHelpers where (I think) the error data stems from, tsoa knows quite a bit about what the error really is and should be able to provide a more program friendly format.

An example of the above error, where the validation that fails is the maximim value of an integer. The parameter also happens to be in the query:

fields: [
  {
    parameter: 'limit',
    pointer: '/query/limit', // Not sure if the source/path of the parameter information is contextually available?
    validationType: 'maximum',
    providedValue: 200,
    properties: {
       maxValue: 50,
    },
  }
  ...
],

Other examples:

Enum:

fields: [
  {
    parameter: 'myEnum',
    pointer: '/query/myEnum',
    validationType: 'enum',
    providedValue: 'BAZ',
    properties: {
       allowedValues: ['FOO', 'BAR'],
    },
  },
  ...
],

Pattern:

fields: [
  {
    parameter: 'stringPatternParam',
    pointer: '/body/someArray[1].stringPatternParam',
    validationType: 'pattern',
    providedValue: 'foo',
    properties: {
       pattern: "^bar$,
    },
  },
  ...
],

And so on.

The general idea is this:

1. The error tells you what parameter failed, preferably with a pointer to it to disambiguate if you happen to have the same parameter name in query and body, for example. Preferably it would be the complete path to the offending property. A request body for example might be nested, or an array and if the pointer indicates the exact path that’d be amazing.
2. validationType indicates what type of validation that failed and…
3. … the properties are contextually populated based on the validation type providing as much context as is relevant to the particular validation in a succinct and precise manner.
4. The provided value is handed back for clarity (I just renamed the property to avoid ambiguity: “What does value reference?” vs “I know what providedValue references!”
5. Notably, the fields property has been changed to an array rather than an object to allow for multiple errors on the same property - this is a breaking change so I would suggest to create a new parallell property and keep fields as-is.

The discussion that went on in #416 kind of relates given statements such as “tsoa does validation”. I like that it does, I just want to extract useful information from the validation errors instead of having tsoa hide all the information it sits on.

Thoughts? Perhaps I am overlooking something in the error handling that isn’t documented?

Context (Environment)

Version of the library: 3.6.1. Version of NodeJS:

• Confirm you were using yarn not npm: [ ]

Breaking change?

No, probably not. Depends on how it’s implemented.

---

Edit: Clarified the structure and corrected a couple of typos

[WoH]

I see this as quite an important change and would really like to see it being released as a minor rather than a major as I’d assume releasing as a major would increase the time to release quite a bit?

As it is an important change, I’d release the change without delay as a major bump.

I am a big fan of AJV myself and currently use it. I took it from the conversation in #416 that introducing a third-party library wasn’t an option but maybe that has changed since?

My opinion has not changed, but my willingness to act on it 😉 The upside (performance, shared effort, better errors) outweigh the downside (new dependency). Also, since the initial discussion, ajv has become an OpenJS foundation project and is the de-facto go to project for JSON-Schema validation in the JavaScript ecosystem. On top, we would be able to replace the 2 existing runtime deps (which we already have, but don’t tell anyone, namely moment and validator) with one.

[WoH]

In order to keep custom error messages, ajv-errors seems like a reasonable choice.