The Swagger Schema Validation Data Operation The Swagger Schema Validation Data Operation

The Swagger Schema Validation Data Operation

Juan Jose Juan Jose

Overview

Within Connection Builder, there is a Data Operation step that can perform a Swagger validation. The Validate a Swagger Schema Data Operation validates a Swagger file from the content that is passed in. 

Use Cases

  • Validate incoming requests with a Swagger file.
  • Ensure that incoming data is valid before proceeding into further application logic.

If you're unfamiliar with the specifics of Swagger you can read more here: https://swagger.io/

Data Operation Properties

Swagger API: 

This is the schema that defines how valid data should be structured. It is the definition to which data will be checked against
The input for this value is a json Swagger schema. Usually Swagger schemas are built in yaml; if you have a yaml Swagger schema you can translate it to json using a tool like this: https://onlineyamltools.com/convert-yaml-to-json

Object to Validate 

The data (a variable or result of variable operations) that should be checked and validated.

Object Schema: 

The specific namespace or level within the Swagger Schema that should be used for validation.

Example input 

Paste the following example Swagger schema into the field "Swagger API":

{
     "openapi":
       "3.0.1",
     "info":
       {
         "title":
           "AirKit Swagger Schema validation example",
         "description":
           "A simple Swagger Schema example to validate against and learn how to use Swagger validation within Connection Builder",
         "contact":
           { "name": "Airkit Support", "url": "https://www.airkit.com/", "email": "support@airkit.com" },
         "version":
           "1.0.4"
       },
     "components":
       {
         "schemas":
           {
             "UserData":
               {
                 "required":
                   \[ "username", "email" \],
                 "type":
                   "object",
                 "properties":
                   {
                     "name":
                       { "type": "string", "description": "the name of the user" },
                     "username":
                       { "type": "string", "description": "the username of the user" },
                     "email":
                       { "type": "email", "description": "the email of the user" }
                   }
              }
           }
       }
    }

 Paste the following example object to validate into the field "Object to Validate":

{
"username": "dlerner",
   "name": "Daniel", 
    "email": "daniel@airkit.com" 
}

Paste the following value within the "Object Schema" field:

"UserData"

Click  "Play" on the Data Operation step and you should see the following result:

{
   "isValid": true,
   "errors": null
}

The object defined in "Object to Validate" gets validated against the schema on "Swagger API". This is done using the namespace that's defined on "Object Schema". In the  example, an object with username, name and email gets validated against the definition of the "UserData" that lives in the Swagger definition on components.schemas.UserData
Since the object has all the required fields (username, email) then the result given is that the object is valid. We can remove the field "name" from the object to validate and we won't get an error, since it's not a required field.

For invalid responses, paste this object into the field "Object to Validate":


{
   "username": "dlerner", 
   "name": "Daniel"
}

Now run the Data Operation step... you should see the following error:

{
 "isValid": false,
   "errors": [{
       "keyword": "required",
       "dataPath": "",
       "schemaPath": "spec#/components/schemas/UserData/required",
       "params": {
           "missingProperty": "email"
       },
       "message": "should have required property 'email'"
   }]
}

The result from this operation has 2 main results:

  • If there is any error on the validation, isValid is false;
    otherwise isValid is true.
  • The errors object holds a list with the details of all the errors found

Further Reading