experience-usability.html

Developer-experience details that make the API easy to learn and consume.

123 rules experience: usability 112 in the file · 11 built-in or validator-only

Run this ruleset

Lint any matching artifact against this ruleset with the OpenLint CLI (the Spectral CLI gives the same results):

npx openlint lint api.yaml \
  --ruleset https://apicommons.org/assets/rulesets/experience-usability.yaml

Or run every rule, including the 11 that are engine built-ins or need the validator's own functions, in the API Commons validator. The other 112 are inlined in the file below.

Ruleset definition

Download YAML 

Loading…

Rules in this ruleset (123)

Skill Body Length Agent Skill
Skill Description Length Agent Skill
Skill Description Single Line Agent Skill
Skill Name Max Length Agent Skill
API Property Require Go SDK APIs.json
API Property Require Java SDK APIs.json
API Property Require Node SDK APIs.json
API Property Require Python SDK APIs.json
API Property Require Sandbox APIs.json
API Property Require SDK APIs.json
API Property Require Signup APIs.json
API Property Require Support Email APIs.json
API Property Require Support Issues URL APIs.json
API Property Require Support Page APIs.json
API Require Base URL APIs.json
Schema Include API Plan APIs.json
Schema Include Developer Portal APIs.json
Schema Include Discussion Forum APIs.json
Schema Include Documentation APIs.json
Schema Include Examples APIs.json
Schema Include Feedback Email APIs.json
Schema Include Feedback Issues URL APIs.json
Schema Include Getting Started APIs.json
Schema Include Insomnia Collection APIs.json
Schema Include Mock Server APIs.json
Schema Include Postman Collection APIs.json
Schema Include Postman Public Workspace APIs.json
Schema Include Pricing APIs.json
Schema Include Production Environment APIs.json
Schema Include Questions Issues URL APIs.json
Schema Include Staging Environment APIs.json
Arazzo Step OperationPath Arazzo engine
Asyncapi 3 Server Not Example Com AsyncAPI engine
Asyncapi Operation OperationId AsyncAPI engine
Asyncapi Server Not Example Com AsyncAPI engine
Asyncapi Servers AsyncAPI engine
Document Require Instructions MCP
Channel Parameter Require Examples OpenAPI
Component Message Require Examples OpenAPI
Document Require Realistic Examples OpenAPI
Document Require Server Defined OpenAPI
Document Require Server Defined (Swagger 2.0) OpenAPI
Header Require Examples OpenAPI
Limit Nested Sub Resources OpenAPI
Limit Path Length OpenAPI
Limit Path Parameter OpenAPI
Message Examples Form Complete Mocks OpenAPI
Message Require Examples OpenAPI
OAS3 API Servers OpenAPI engine
OAS3 API Servers (Swagger 2.0) OpenAPI engine
OAS3 Server Not Example.com OpenAPI engine
OAS3 Server Not Example.com (Swagger 2.0) OpenAPI engine
Operation Collection Support Filtering OpenAPI
Operation Collection Support Sorting OpenAPI
Operation Collection Support Sparse Fieldsets OpenAPI
Operation Examples Form Complete Mocks OpenAPI
Operation Get Support If Modified Since OpenAPI
Operation Get Support If None Match OpenAPI
Operation OperationId OpenAPI engine
Operation OperationId Valid In URL OpenAPI engine
Operation Post Not For Retrieval OpenAPI
Operation Put Require Request Body OpenAPI
Operation Require ID OpenAPI
Operation Require Identifier OpenAPI
Operation Write Support If Match OpenAPI
Operation Write Support If Unmodified Since OpenAPI
Parameter Collection Limit Param Default OpenAPI
Parameter Filter Param Only On Get OpenAPI
Parameter No Hybrid And Root Filtering OpenAPI
Parameter No ID Query OpenAPI
Parameter Optional Include Examples OpenAPI
Parameter Query Must Be Optional OpenAPI
Parameter Require Examples OpenAPI
Parameter Required Require Examples OpenAPI
Parameter Sort Param Only On Get OpenAPI
Path CORS Support Options Preflight OpenAPI
Path Max Nesting Depth OpenAPI
Path Parameter Not Empty OpenAPI
Path Require Query Parameter OpenAPI
Request Body Must Use JSON Content Type OpenAPI
Request Body Must Use JSON Content Type (Swagger 2.0) OpenAPI
Request Content Require Examples OpenAPI
Request Delete No Body OpenAPI
Request Get No Body OpenAPI
Request Support Accept Encoding OpenAPI
Request Support Accept Language OpenAPI
Request Support Baggage OpenAPI
Request Support Correlation ID OpenAPI
Request Support Form Urlencoded Media Type OpenAPI
Request Support JSON Media Type OpenAPI
Request Support JSON Media Type 2 OpenAPI
Request Support Multipart Media Type OpenAPI
Request Support Text Plain Media Type OpenAPI
Request Support Tracestate OpenAPI
Request Support XML Media Type OpenAPI
Response 202 Location Header OpenAPI
Response 202 Retry After OpenAPI
Response Collection Support Paging OpenAPI
Response Collection Support Paging (Swagger 2.0) OpenAPI
Response Content Require Examples OpenAPI
Response Default Content Language En Us OpenAPI
Response Get Cache Control OpenAPI
Response Get Document 304 Not Modified OpenAPI
Response Get ETag OpenAPI
Response Get Last Modified OpenAPI
Response Get Link Header OpenAPI
Response Get Vary OpenAPI
Response Include Hypermedia Links OpenAPI
Response Must Use JSON Content Type OpenAPI
Response Must Use JSON Content Type (Swagger 2.0) OpenAPI
Response Ratelimit Header OpenAPI
Response Ratelimit Policy OpenAPI
Response Return Correlation ID OpenAPI
Response Write Document 412 Precondition Failed OpenAPI
Response Write ETag OpenAPI
Schema Collection Require Pagination Params OpenAPI
Schema Property Require Examples OpenAPI
Server Must Not Specify Port OpenAPI
Document Require Currency Plans
Plan Require Description Plans
Plan Require Features Plans
Plan Require Interval Plans
Plan Require Price Plans

← All experience rulesets