Improvements and Changes to Validation Messages

Based on internal and customer feedback, we have revamped our validation messages shown to users during import or generation of artifacts like SDKs/Portal, etc. This release improves message content, introduces a couple of new validation messages and changes severity of some of the older messages.

Heads-up! Breaking Change

It is recommended to especially make note of the messages for which severity has been upgraded. If you were previously running into those messages, you may no longer be able to generate SDKs, Docs/DX Portal or export to the chosen format unless you make the required fixes to your API.

Changes to Severity of Validation Messages

We've upgraded severity of a few messages which are given below:

1. If an enumeration model field is set to an array, the validation message thrown will now be an Error instead of a Warning.
2. If the default value of a server template parameter is invalid, the validation message thrown in this case will now be an Error instead of a Warning.

New Validation Messages

The following new validation messages have been added. Their corresponding severity is also mentioned:

1. Error: If a model of type Exception is used for a component which is not an error response.

2. Error: If a model of type Enumeration has a base type set.

3. Error: If a model of type Enumeration has duplicate values.

4. Error: If the required name for a component is missing e.g. a parameter name.

5. Error: If an Authentication header is also added in the Additional Headers list with the same name.

6. Error: If a component is marked as constant/read-only but no default value is set.

7. Warning: If the value of the maximum limit type restriction attribute is less than the value specified for the minimum limit. This applies to the following cases:

   • If, for arrays, the value of Maximum Items is less than the value for Minimum Items.
   • If, for objects, the value of Maximum Properties is less than the value for Minimum Properties.
   • If, for numbers, the value of Maximum is less than the value for Minimum.
   • If, for strings, the value of Maximum Length is less than the value for Minimum Length.

8. Information: If an Authorization header is found in an endpoint when no global authentication mechanism is set up for the API, then the user is recommended to set up a global authentication instead.

While an API specification file is imported, some fixes are automatically made to the file to prevent a user from facing any issues in output generation. However, end-users were not being informed about those fixes. We have now added validation messages that let users know when an issue is detected and automatically fixed. The severity of all these messages is set to Warning.

9. Warning: If a server parameter is declared as an array, it is converted to a non-array entity.
10. Warning: If a server parameter is declared as a map or object it is converted to a primitive type entity.
11. Warning: If a server parameter is declared as constant/read-only, it is marked as a non-constant entity.
12. Warning: If the global or endpoint level errors are not sorted in increasing order of their error status codes, they are automatically sorted.
13. Warning: If a component uses primitive type Dynamic and is also declared as an array, it is changed to a non-array component.
14. Warning: If a custom type has a Discriminator declared but a corresponding discriminator field is not declared in the same custom type, it is automatically added.
15. Warning: If an example/sample value has leading or trailing white-space characters, the example is automatically trimmed from the start and end.
16. Warning: If the example/sample value is of boolean type and the value uses some other variant than true and false, the variant is converted to one which is supported.
17. Warning: If the name of a component has leading or trailing white-space characters, the name is automatically trimmed from the start and end.
18. Warning: If the user-friendly description of a component has leading or trailing white-space characters, the description is automatically trimmed from the start and end.
19. Warning: For Code generation purposes, the endpoint parameters should be sorted in order of their optional characteristic i.e. required parameters should be placed first while optional parameters should be placed at the end. If this is not the case by default, the parameters are automatically sorted accordingly.

Improvements to Message Content

We have improved the message content so that it gives more information than before in order to help you trace the issue more quickly. The message content will now be more consistent in structure and easier to read.

An example of an old validation message is:

The same message now looks like:

Here, [APIMATICPRE_V404] is the unique Id assigned to the message against which you can find more details about the issue which caused the message to be logged.

Detailed Documentation for Each Validation Message

We have added reference documentation for you to find more details about each and every validation message you run into. The details can range from a detailed description of the issue, external links that can help provide more information, tips/hints that can be followed to resolve the issue and any contextual tags, etc. Links to the documentation are given below:

• APIMatic Post-Processing Validation
• APIMatic Post-Processing Validation for Code-Generation
• APIMatic Preliminary Validation
• APIMatic Preliminary Linting
• APIMatic Validation for Code Generation
• APIMatic Linting for Portal Generation