This skill should be used when the user asks to "validate API spec", "check OpenAPI spec", "lint OAS", "review API specification", "convert RAML to OAS", or mentions validating, checking, or reviewing OpenAPI/OAS/Swagger/RAML specifications against best practices.
This skill validates OpenAPI Specification (OAS) files against a comprehensive set of rules designed to ensure API specifications are AI-agent-friendly and production-ready.
Every api specification should be organized as an Anypoint API Project with the following structure:
├── api.yaml
├── README.md
├── docs/
├── exchange.json
Exchange.json needs to have the following shape:
{
"main": "api.yaml",
"name": "<name-of-the-api>",
"organizationId": "8bfc8bbf-5508-419e-aadc-77dfe18a8172",
"groupId": "f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform",
"assetId": "<same-as-the-folder>",
"version": "<any-semver-version default 1.0.0>",
"apiVersion": "v1",
"classifier": "oas",
"dependencies": [],
"originalFormatVersion": "3.0"
}
Use this skill when:
All API specifications must be written in OpenAPI Specification (OAS) format in YAML. Supported versions:
Translation: All APIs should be written in OAS 3 or bigger and in YAML format.
The info.title field must end with the word "API" to ensure consistent naming across the portal.
Valid: Secrets Manager API, Object Store API, API Manager API
Invalid: Tokenization, ObjectStore, ARM REST services, Exchange - XAPI Service
The info.version field must use strict Semantic Versioning with three numeric components: MAJOR.MINOR.PATCH.
Valid: 1.0.0, 2.1.3, 0.7.0
Invalid: v1, V1, 1.0, 1, v1.0.0, v2
This ensures consistent version formatting across all API specifications, enabling reliable version comparison and tooling support.
Every endpoint operation must have an operationId that is:
get_data, update, post_item, fetchcalculateTaxRate, provisionCloudServer, getUserPreferences, cancelSubscriptionGood examples:
calculateTaxRate - specific action + specific domainprovisionCloudServer - clear verb + clear resourcegetUserPaymentHistory - specific action + specific dataBad examples:
get_data - too genericupdate - missing contextcreate - which resource?fetch - fetch what?Every endpoint operation must have a description field. Apply special handling for:
If a field name is cryptic or legacy (e.g., v1_status_code, legacy_tier, old_category), override its description with clear mapping: