API - JSON schema error

Are you getting this error when sending a request to our API?

“The request you submitted did not match the schema the API was expecting. Please be sure that you submitted your request with the correct Content-Type header and that your request body matches our schema. See the API documentation for the JSON schema to follow.”

This means that you have an error with the JSON data structure that you included in the body of your request and that it doesn't follow the format in which we expected to receive it. In order to know exactly what is wrong with your JSON data, you will need to validate it using a JSON schema.

What is a JSON schema?

Here's the definition of a JSON schema:

“JSON Schema specifies a JSON-based format to define the structure of JSON data for validation, documentation, and interaction control. It provides a contract for the JSON data required by a given application, and how that data can be modified.” Wikipedia

How to identify where is the error in my JSON schema?

To find out what is wrong in your JSON data structure, you will need to use a JSON Schema Validator.

Using a JSON Schema Validator consists in comparing two elements with each other. These elements are: our JSON schema and your JSON data structure. The validator will then indicate where your data structure doesn't match what is expected by our API.

Resolve JSON data structure errors in three steps:

• Get your JSON data structure
• Get our JSON schema
• Compare the schemas

Step 1: Get your JSON data structure

Normally, you should already have it since you tried to make a request to our API, which unfortunately failed with a JSON schema validation error.

Here's an example of a JSON data structure that contains an error and will serve as an example in the next steps:

{

    "batchType": "addMembers",

    "relationType": 28,

    "defaultConsentDate": "2014-06-15",

    "defaultConsentProof": "Bought on our website",

    "members": [

        {

            "firstname": "John",

            "lastname": "Doe",

            "company": "John Doe Company",

            "email": "john.doe@example.org",

            "gender": "m",

            "language": "fr_ca",

            "postalCode": "A0A 0A0",

            "country": "CA",

            "note": "John is the CEO",

            "birthdate": "1980-01-01",

            "customField1": "This is a test !"

        }

    ]

}

Step 2: Get our JSON schema

Our API currently allows you to submit two types of batch request (batches). A JSON schema is provided for each of them. In the case of the previous example, it's a batch request of type "addMembers". So here's how to proceed to get the right schema from our API documentation:

1. Access our API documentation here: https://cyberimpactapiv4.docs.apiary.io
    
2. In the left section, click on “Resources”.
   
   
3. In the “Resources” list that appears, click on “Batches”.
    
4. Scroll down the middle part of the page to the “Add a batch” section and click on it.
   
   
   
5. Scroll down the right-hand side to the section “Request – Add Members in a batch”.
   
   
    
6. Make sure that the two drop-down menus are on the values “Production” and “Raw”.
   
   
    
7. Click the button “Show JSON Schema” that appears under the “Try” button. If it doesn't appear, refresh your page (F5) to show the icon.
   
   
   
   You should obtain this:
   
   

Step 3: Compare the schemas

Now that we have everything you need, let’s navigate to the page of an online schema validator of your choice.

In this example, we have chosen to use https://www.jsonschemavalidator.net/, because this one automatically detects the schema version but there are other tools available like: JSON Schema Lint.

To use the validator, follow these steps:

1. Go to this page: https://www.jsonschemavalidator.net/
    
2. Copy and paste our JSON schema (which you recovered at the previous step) in the text zone on the left.
    
3. Copy and paste your JSON data structure in the text zone on the right.
    
4. The tool will then compare the two structures and errors will be indicated by a red X. All you will have to do is correct your pattern afterwards.

Example of erroneous JSON schema

You can see below that the validator has managed to find two errors.

If you bring your mouse pointer over the red "Xs" (for example, see the "X" to the right of the line #3 in the right part of the image above), you will see the cause of the error. Here, the first error is caused by the “relationType” line which would have an “Invalid type” problem. "Expected String but got Integer”, which means “Type invalid, a string was expected, but it is rather an integer number that was obtained".  

To correct the error, we will try to replace the integer "28" with a string, such as "this is a string". Here's the result after the correction:

We immediately notice that we still have an error on line #3, but that it's now another error.

• Value “this is a string” is not defined in enum.

What the validator tells us is that the schema doesn't accept the content of the string "this is a string" for the value of the "relationType" field. To solve the problem, please refer to the schema obtained from our API documentation, which can be found in the text box on the left side of the validator. Then scroll down to the "relationType" section, where you will find the list of accepted values:

 

"relationType": {

     "type": "string",

      "enum": [

          "express-consent",

          "active-clients",

          "information-request",

          "business-card",

          "web-contacts",

          "purchased-list",

          "contest-participants",

          "mixed-list",

          "inactive-clients",

          "association-members",

          "employees",

          "partners"

        ]

      }

Then replace “this is a string” with one of the values in the enum, such as “active-clients”:

 

The green check mark at the bottom of the image indicates that there are now no more errors with the schema.

You may also notice that our second mistake is no longer there either. This means that this error was caused by the first error we have just solved.

Indeed, in many cases, the JSON schema validation errors that appear to be the most complex are often the consequences of simpler errors. Thus, it's good, when trying to diagnose schema validation errors to start with the errors that seem the easiest to correct first.

Unless your JSON data structures contain a large number of errors, following the steps of this diagnostic procedure should, at least, put you on the right track to resolve them.