Skip to main content

Improved Validation Messages

· 3 min read

We have significantly revamped the content of our validation messages shown when importing/transforming API specifications or generating artifacts like SDKs/Portal, etc. in order to make it easier for our end-users to quickly understand issues and apply relevant fixes.

Details​

Here are some of the improvements made to the validation messages content:

1. More messages now contain source information to trace root of issue.​

For API specifications, where line information may not be available, we have introduced breadcrumb paths to give an approximate location of the problematic component:

Before:

Trace - Before

After:

Trace - After

For messages where line information is available, we have additionally introduced JSON reference paths to give an exact location of problematic component. This makes it easier to locate a component even when line numbers change if the input document is updated:

Before:

JSON Path - Before

After:

JSON Path - After

2. Improved structure of messages.​

We have greatly increased the user-friendliness of messages by firstly simplifying the wording, making the messages clearer and easier to understand. We have enhanced readability by making them more concise and by removing any inconsistencies or ambiguities. Moreover, we have tried to ensure consistency in the tone and language used across all messages to improve experience further.

Before:

Message Structure - Before

After:

Message Structure - After

3. Messages are now more organized so you can focus on what matters first.​

Related messages will be grouped together and not scattered all over the place:

Before:

Grouped - Before

After:

Grouped - After

Validation/linting messages will be at the top while any informational logs will be placed at the end:

Logs

4. Documentation for all validation/linting messages available now.​

Reference documentation for each validation/linting message is now available as part of our ruleset collection which can be viewed here. Against each message, a View Details hyperlink will be shown which will point to the relevant documentation for that message and include a detailed description of the issue, external links that can help provide more information and tips/hints that can be followed to resolve the issue, etc. No need to hunt FAQs and troubleshooting sections for relevant answers.

Logs

5. Ability to toggle between stricter and more flexible validation.​

By default, the import/transformation feature is quite tolerant i.e. it may ignore certain issues in your API specification document or apply a lower severity for them during validation. However, if you wish to strictly validate your API specification documents to get an optimal output, we now provide an ability to enable stricter validation using the UseStrictValidation import setting. This will require you to upload a APIMatic Metadata file with the flag enabled in the ImportSettings object as follows:

{
    "ImportSettings": {
        "UseStrictValidation": true
    }
}

Note, that this may enforce additional checks or increase severity of some issues. You can, however, choose to configure validation and tune it as per your needs.