We've added new validation and linting rules that flag API entity names exceeding 100 characters in OpenAPI specifications. Names exceeding 100 characters now produce an Error-severity violation that blocks Code Generation, Docs Generation, and Portal Generation.
Details
Entity names in API specifications are used to generate class names, method names, file names, and documentation titles across multiple SDK languages. When these names are excessively long, they can cause failures during SDK generation and degrade the developer experience in generated portals.
Based on our analysis of real-world customer specifications and SDK generation constraints across 7 programming languages, we've set the maximum allowed name length at 100 characters. This threshold provides sufficient flexibility for descriptive naming while preventing the issues described below.
Why This Matters
Using entity names longer than 100 characters in your API specification can lead to the following issues:
SDK Generation Failures
- File path length errors: SDK generators create files and directories derived from entity names. Excessively long names combined with nested directory structures can exceed the operating system's maximum path length (e.g., 260 characters on Windows), resulting in
PathTooLongExceptionerrors that block SDK generation entirely. - Compilation errors: Some programming languages and compilers impose limits on identifier lengths. Names that are too long may cause generated code to fail to compile.
Poor Developer Experience
- Unreadable code: Generated class names, method names, and variable names derived from overly long entity names become difficult to read and use in application code.
- Truncated display: Documentation portals, IDE tooltips, and auto-complete suggestions may truncate long names, making it harder for developers to discover and understand API entities.
- Inconsistent naming across languages: Different SDK languages apply different naming conventions (PascalCase, snake_case, camelCase). Long names combined with these transformations can produce inconsistent or unwieldy identifiers.
Documentation and Portal Issues
- Layout problems: Extremely long names can break the layout of generated developer portals, causing overflow in navigation menus, table of contents, and endpoint listings.
- Reduced searchability: Long, compound names are harder to search for and remember, reducing the overall usability of the API documentation.
Affected Entities
The following entities are now validated against the 100-character limit:
OpenAPI 3.0 (13 new rules in openapi-v3-codegen-linting)
| Entity | Rule ID |
|---|---|
| Info Title | OPENAPI3CODEGEN_L051 |
| Environment Name | OPENAPI3CODEGEN_L099 |
| Server Name | OPENAPI3CODEGEN_L100 |
| Server Variables Key | OPENAPI3CODEGEN_L101 |
| Server Parameter Name | OPENAPI3CODEGEN_L102 |
| Schema Component Key | OPENAPI3CODEGEN_L138 |
| Path Item Parameter Name | OPENAPI3CODEGEN_L174 |
| Operation ID | OPENAPI3CODEGEN_L205 |
| Operation Tag Name | OPENAPI3CODEGEN_L206 |
| Operation Parameter Name | OPENAPI3CODEGEN_L207 |
| Tag Name | OPENAPI3CODEGEN_L585 |
| Schema Title | OPENAPI3CODEGEN_L624 |
| Schema Property Name | OPENAPI3CODEGEN_L625 |
The existing 50-character Warning-severity rules remain unchanged. Names between 51 and 100 characters will still produce a warning, while names exceeding 100 characters will now produce a blocking error.
What You Should Do
If your API specification contains entity names longer than 100 characters, you will see new Error-severity messages during validation. To resolve these:
- Shorten the affected names to 100 characters or fewer while keeping them descriptive.
- Use the rule ID from the validation message to locate the exact entity in your specification.
- If you need to temporarily bypass these rules, you can adjust your Validation Configuration to change the severity or skip specific rules.