Define & Validate APIsValidation RulesetsOpenAPI Rulesets
OpenAPI v3 Linting for Agentic Tools
Linting checks APIMatic performs on OpenAPI v3 files to make sure they follow practices that improve the output of agentic tools and the overall clarity of the API.
| Property | Value |
|---|---|
| Ruleset ID | openapi-v3-agentic-tools-linting |
| Code prefix | OPENAPI3AGENTICTOOLS_L |
| Type | Linting |
| Default severity | Warning |
| Rule system | Semantic |
| Rules | 10 |
OpenAPI Root Information
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3AGENTICTOOLS_L001 | unique-tags | Warning | The 'tags' array in the OpenAPI root must contain unique tag names. Duplicate tags create ambiguity in documentation, code generation, and agentic tools. Ensuring tag name uniqueness improves categorization, clarity, and tool-generated outputs. |
OPENAPI3AGENTICTOOLS_L002 | required-tag-description | Warning | Every tag defined in the 'tags' array should contain a meaningful description. Clear descriptions help developers and AI agents understand grouping and intent. Well-documented tags improve agentic tool reasoning and enhance generated outputs. |
OpenAPI Info
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3AGENTICTOOLS_L040 | required-info-description | Warning | The 'info' object should contain a clear and informative description that explains the API's purpose, domain, and features. A detailed description significantly improves agentic tools' ability to reason about API behavior and generate accurate guidance or code. |
OPENAPI3AGENTICTOOLS_L041 | required-environment-information | Warning | To optimize agentic tools output, provide environment-specific details for each server defined in the OpenAPI document. This is best achieved using APIMatic's x-server-configuration extension, which helps distinguish production, staging, and other environments. |
OpenAPI Operations
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3AGENTICTOOLS_L230 | required-operation-summary | Error | Agentic tools heavily rely on operation summaries to understand API intent. Ensure every operation object includes a concise, meaningful summary to improve AI reasoning and tool output quality. |
OPENAPI3AGENTICTOOLS_L231 | required-operation-description | Error | A detailed operation description enables agentic tools to infer behavior, side effects, and constraints. Ensure each operation includes a complete and meaningful description. |
OpenAPI Parameters
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3AGENTICTOOLS_L330 | required-parameter-description | Error | Parameter descriptions help both developers and AI agents understand the purpose, expected format, and constraints of inputs. Provide a meaningful description for every parameter. |
OPENAPI3AGENTICTOOLS_L331 | at-least-one-parameter-example | Error | Examples significantly improve agentic tools' ability to infer parameter usage, constraints, and expected values. Define at least one valid example for every parameter. |
OpenAPI Schemas
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3AGENTICTOOLS_L660 | required-schema-description | Warning | Schema descriptions help agentic tools understand the purpose and structure of models. Include meaningful descriptions to improve generated code and AI reasoning. |
OPENAPI3AGENTICTOOLS_L661 | required-description-for-enum-item | Error | Enum values often carry domain-specific meaning. Use APIMatic's x-enum-elements extension to define readable names and descriptions for each enum item to improve clarity for agentic tools. |
Learn more
OpenAPI v3 Syntax Linting for APIMatic Portal Generation
Syntax linting checks performed by APIMatic on provided OpenAPI v3 file to check its conformance to recommended practices for a more user-friendly API documentation.
Swagger v2.0 APIMatic Linting
Linting checks performed by APIMatic on provided Swagger v2.0 file to check its conformance to recommended practices for better API consumption.