Field Syntax/Format Validation

[jasmingacic]

As an API user I often need to implement syntax or semantic validation for email or password fields.

      /validated:
        post:
          requestBody:
            content:
              application/json:
                schema:
                  properties:
                    email:
                      type: string
                  required:
                  - email
                  type: object

I want the required field email to be in the form of /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/ (probably not working regex).

      /validated:
        post:
          requestBody:
            content:
              application/json:
                schema:
                  properties:
                    email:
                      x-kusk:
                         validate:
                           regex: ....
                      type: string
                  required:
                  - email
                  type: object

One possible option would be to write an NPM module that would validate an HTLM form against what's defined in the OpenAPI. Note: NPM module is important as FE doesn't need to issue a request to the backend to validate requests so having it integrated into JS app would streamline it.

This would make the OpenAPI single source of truth for application developers. A CD pipeline deploy the NPM module with the newest application which does the same field validation as BE.

[jasmingacic]

Very often app developers do the same checks in two places and forget to sync them up. This way by deploying it from the single source it would ensure that both FE and BE are doing the same.

[fivenp]

I would like to add two thoughts here...

1 Validation

What currently happens in the App/Product development lifecycle is:

1. You build a product consisting of multiple parts (Frontend, Backend, CLI, Some other micro service/interface)
2. You start having the need to validate payloads/forms (stupid ones like email)
3. You copy paste the same regex for validation across all parts of your product.
4. You want to change the validation behaviour for e.g. emails to ban @gmail.com
5. You're basically lost.... And it will be a nightmare

If you take this example to a higher level there will be even more complex cases of validation you can 4 sure see the real life issues.

Now the problem kusk could solve is to enable ALL consumers to have ONE single source of validation truth. (The API Spec) Of course the API will implement the validation differently (right on the gateway most likely) to the Frontend (they will need to do validation on the client side without doing a request at all)

As @jasmingacic said – we can solve this by providing helper libraries for all possible frameworks/programming languages which do the OpenAPI extraction work for you and potentially return a valid/invalid for any given payload/input

2 Error messages

A similar problem to validation are error messages. They are not only inconsistent across e.g. an API – but even across the Frontend or other Interfaces (CLIs, etc)

Having error messages in one single place enable you to make them WAY more helpful and implement them consistently across ALL your user interfaces (Frontend, API, CLI, etc)

Same as above – we could create helper libraries which help you extract the error message from the OpenAPI Spec (or just return it straight away)

A good pattern of error messages (and we should allow for this format – e.g. title, message, etc):