When you upload an OpenAPI specification to the Cequence platform, it goes through a validation process before being accepted. This guide explains what the platform checks and how to ensure your spec passes validation.
Supported Spec Versions
The platform supports the following OpenAPI specification versions:
- Swagger 2.0
- OpenAPI 3.0.x (e.g., 3.0.0, 3.0.1, 3.0.2, 3.0.3)
OpenAPI 3.1 is not currently supported. If your spec uses version 3.1, you will need to downgrade it to 3.0.x before uploading.
Stage 1: Format and Structure Validation
The platform first checks that your spec is a structurally valid OpenAPI document. Your spec will be rejected at this stage if:
- The JSON or YAML syntax is malformed
- The spec version is missing or unsupported
-
$refreferences are broken or cannot be resolved - Required OpenAPI fields are missing (e.g.,
info,paths) - Schema definitions contain structural errors
Tip: Before uploading, validate your spec using an external tool such as Swagger Editor to catch these issues early.
Stage 2: Platform Requirements
Once the spec passes structural validation, the platform checks the following requirements. If any of these fail, the upload will be rejected with a specific error message.
1. Title is Required
The info.title field must be present and non-empty.
2. Title Must Be Unique
No other spec already uploaded to the platform can share the same info.title. If you need to replace an existing spec, either delete the old one first or use a different
title.
3. All Parameters Must Have Names
Every parameter defined across all operations must have a non-empty name field. This applies to query, header, path, and cookie parameters.
4. Paths Must Not Conflict With Other Specs
The combination of server URL + path + HTTP method must not already be defined in a different spec on the platform. This prevents two specs from claiming ownership of the same endpoint.
How to resolve: Change the server URL or base path in your spec to differentiate it from the existing one.
5. At Least One Server is Required
The servers array must contain at least one entry. Specs without servers cannot be mapped to real API traffic.
6. Server URLs Must Be Valid
Each server URL must be a valid HTTP or HTTPS URL with a recognizable hostname. Relative paths or malformed URLs are not accepted.
7. WebSocket Schemes Are Not Supported
Server URLs must use http:// or https://. WebSocket schemes (ws:// and wss://) are not supported.
Pre-Upload Checklist
- Spec version is Swagger 2.0 or OpenAPI 3.0.x
- Spec validates cleanly in Swagger Editor (no syntax or structural errors)
-
info.titleis filled in with a meaningful, non-empty name -
info.titleis unique — no other spec on the platform uses the same title - All parameters across all operations have a
namefield defined -
serversarray contains at least one entry - All server URLs are valid HTTP/HTTPS URLs with a hostname
- No server URLs use
ws://orwss:// - Endpoints (server + path + method) do not overlap with an existing spec
Error Message Reference
All validation errors begin with Could not parse the spec followed by the specific reason:
| Error Message | Meaning | How to Fix |
|---|---|---|
| title is empty |
info.title is missing or blank |
Add a non-empty title to your spec |
| title already exists | Another spec with the same title is already uploaded | Use a unique title or delete the existing spec first |
| Found null or empty parameter name... | A parameter is missing its name field |
Add name to all parameters in the specified operation |
| Resource X already exists in spec Y... | An endpoint conflicts with another spec | Change the server URL or base path to avoid the conflict |
| servers not found | No servers defined in the spec | Add at least one server entry |
| invalid server found | A server URL is not a valid HTTP/HTTPS URL | Fix the URL to be fully qualified with a hostname |
| WS schemes are not supported | A server URL uses WebSocket protocol | Change to http:// or https://
|
| unknown spec version | The spec version is not recognized | Ensure spec uses Swagger 2.0 or OpenAPI 3.0.x |
Need Help?
If your spec is being rejected and you have verified all the above, please contact Cequence Support with:
- The exact error message you are seeing
- A copy of the spec file (with any sensitive data redacted)
- The name of the environment you are uploading to