Skip to main content

main-file-known-format

Overview​

This rule belongs to the import-validation ruleset and states that:

When providing a single or multi-file input, the input must contain a main API definition file in one of the following formats: OpenAPI/Swagger, RAML, API Blueprint, Postman, Insomnia, WSDL, WADL, Google Discovery, I/O Docs, APIMATIC. If no main API description file is found, the first recognizable data description file like JSON, JSON Schema, YAML, XML, XML Schema, etc. may be chosen as the main file.

PropertyValue
EnabledYes
Maximum SeverityBlocking
MessageMain API definition file could not be identified as provided file(s) are either invalid or are in an unrecognized/unsupported format.
CodeIMPORT_V102
TypeValidation
Rule SystemSemantic
Broad CategoryFile I/O Content
Tagsimport api specification api file validation main file format api description format data description format

Suggested Fixes​

  • If you've uploaded a single file, ensure that it is in one of the supported formats.
  • Supported API definition formats include: OpenAPI/Swagger, RAML, API Blueprint, Postman, Insomnia, WSDL, WADL, Google Discovery, I/O Docs, APIMATIC.
  • The main file must either be a supported API description format (preferred) or a data description format (not recommended). API description files are given precedence over data description files.
  • Make sure that the file contents are not incomplete as that can hinder identification.
  • Ensure that your files use valid JSON/YAML/XML/Markdown.
  • Ensure that the main file has required metadata to help us identify it e.g. OpenAPI files must have the openapi or swagger property, API Blueprint files must have the FORMAT metadata section defined and so on.
  • Ensure that the main file uploaded is not a partial definition e.g. avoid uploading RAML fragment files directly. ZIP them along with a main RAML file.
  • If you are providing the file via a URL, ensure that the URL is publicly accessible and points to a raw API specification file.
  • For multi-file cases, use only ZIP files. .RAR and .7zip files are not supported.
  • If you are uploading a ZIP of multiple files, try placing the main file in the root directory to avoid any issues.
  • The first file encountered in the directory whose format is recognizable is picked up as the main file. Therefore, make sure that the main file is discoverable.
  • The main file identifier first looks for the main file in the files of the root directory. If the main file is not found there, it then looks within the sub-directories of the root directory. The same process goes on for the sub-directories as well until a main file is found or no other files/directories are available for searching.

For More Information​