What Are The Supported API File Types And Formats?
To test APIs, we recommend that you provide API documentation associated in a machine readable format. This will allow Edgescan to know what the good and bad look like when it comes to requests.
Version Number: v1.0.0
Published Date: 17 Oct 2025
____________________________________________________________________________
Requirements
Users can upload API files in order to populate the API Descriptors on their assets. In order for Edgescan to correctly read these files and extract the required information they must meet the following minimum requirements.
1. UTF8 Encoded
The files must be UTF8 encoded, only containing valid UTF8 characters.
While we make some effort to try and convert files to UTF8 format, we cannot guarantee that this will always be successful.
2. Supported file type
The files must be either valid JSON, YAML or HAR files. Please ensure that the files are correctly formatted as such, and are named with the appropriate extension accordingly (e.g. .json, .yml, or .yaml etc)
Supported file Types
- Swagger v2.0 (in .json or .yaml format)
- OpenAPI v3.0 (in .json or .yaml format)
- Postman Collection v2.0+ (in .json format)
- Insomnia Export (in .har format)
Conform to correct swagger specification (Swagger V2.0 or OpenAPI 3.0)
The requirements are slightly different depending on the Swagger/OpenAPI version of the file. At the time of writing this document we only validate certain fields for each version (specified below), however it can be helpful to debug your files using a description validation tool before uploading to ensure it meets the standards according to the specification.
OpenAPI provide a detailed list recommending such tools. We like the swagger-cli tool which, at the time of writing, is open source and free to use under the MIT licence.
Detailed here are the required fields and their supported types. This validation is run to ensure the info we need is present in the swagger file, and in the correct format.
Swagger/OpenAPI v3.0 files
| Top-level field | Nested field | Required Field | Required data type |
| openapi | Yes | String | |
| info | Yes | Hash | |
| info | title | Yes | String |
| info | version | Yes | String |
| paths | No | Hash | |
| servers | No | Array[Hash, Hash, etc.] | |
| servers | url | Yes (if servers present) | String |
| security | No | Hash | |
| components | No | Hash | |
| components | securitySchemes | No | Hash |
| tags | No | Array[Hash, Hash, etc.] | |
| tags | name | Yes (if tags present) | String |
| tags | description | No | String |
| api_location | No | null or String |
Swagger v2.0 files
| Top-level field | Nested field | Required Field? | Required data type (if present) |
| swagger | Yes | String | |
| info | Yes | Hash | |
| info | version | Yes | String |
| paths | Yes | Hash | |
| host | No | String | |
| securityDefinitions | No | Hash | |
| tags | No | Array[Hash, Hash, etc.] | |
| tags | name | Yes (if tags present) | String |
| tags | description | No | String |
| schemes | No | Array[String, String, etc.] | |
| api_location | no | null or String |
Postman Collections v2.0+
To conform to the Postman Collection standard (v2.1), files must meet a minimum schema and field definition requirement. Validation ensures that all key metadata, collection structure, and request details are correctly defined and conform to the expected Postman JSON schema.
Postman collections can be validated against the Postman Collection Schema v2.1. Postman also provides a command-line validator via newman and several open-source JSON schema validation tools.
| Top-level field | Required Field | Required Data Type |
| info | Yes | Object |
| info.name | Yes | String |
| info.schema | Yes | String (must reference Postman v2.1 schema) |
| item | Yes | Array (of Objects) |
| item[].name | Yes | String |
| item[].request | Yes | Object |
| item[].request.method | Yes | String (e.g. GET, POST, PUT, DELETE) |
| item[].request.header | No | Array[Object] |
| item[].request.url | Yes | Object or String (depending on structure) |
| item[].response | No | Array[Object] |
| variable | No | Array[Object] |
| event | No | Array[Object] (for pre-request or test scripts) |
| auth | No | Object (defines collection-level authentication) |
| _postman_id | No | String (UUID) |
Insomnia Export
To conform to the Insomnia Collection (Export) Schema, files must contain all mandatory metadata and object definitions used by Insomnia to represent requests, environments, and workspaces.
The Insomnia format is a JSON document that contains one or more resource objects, each defined by a type, parentId, and data structure.
Validation should confirm the presence and correct typing of all required fields in each object.
Schema validation can be performed using the Insomnia Export Schema or general-purpose JSON validation tools.
|
Top-level field
|
Required Field | Required Data Type |
| _type | Yes | String (must match known Insomnia entity type, e.g. workspace, request, request_group, environment) |
| _id | Yes | String (unique identifier) |
| parentId | Yes (except for workspace root) | String or null |
| name | Yes | String |
| modified | No | Integer (timestamp) |
| created | No | Integer (timestamp) |
| data | No | Object (depends on _type) |
| url | Yes (for _type: request) | String |
| method | Yes (for _type: request) | String (e.g. GET, POST, PUT, DELETE) |
| body | No | Object |
| parameters | No | Array[Object] |
| headers | No | Array[Object] |
| _environment | No | Object (defines variable values for environment contexts) |
| resources | Yes (in full export) | Array[Object] containing workspace, request, and related entities |