no-inline-complex-schema-definition
Overview
This rule belongs to the openapi-v3-apimatic-linting ruleset and states that:
A complex schema is one that may use one or more of the following constructs: allOf, anyOf, oneOf, not, properties. Such schema definitions must be added globally in the components/schemas section with a unique name and then referenced throughout the API document with that name. Inline definitions of such schemas are not recommended as for auto-generating SDKs/documentation the names of such schemas are deduced from the parent objects in which they are declared inline. The names deduced this way may not be user-friendly and can conflict with other definitions resulting in name duplication. This behavior can affect your output quality.
| Property | Value |
|---|---|
| Enabled | Yes |
| Maximum Severity | Warning |
| Message | Inline complex schema definition found. |
| Code | OPENAPI3APIMATIC_L662 |
| Type | Linting |
| Rule System | Semantic |
| Broad Category | OpenAPI Schemas |
| Products Impacted | API Transformer, Code Generation, Developer Experience Portal |
| Tags | openapi3 openapi apimatic semantic linting complex schema inline components |
Suggested Fixes
- Ensure you are not using any of these constructs in your schema if it is an inline schema definition:
allOf,anyOf,oneOf,not,properties. - Remove the inline schema definition and relocate it to the components/schemas section.
- Define the inline schema globally in the components/schemas section with a unique name. Then reference it using $ref in your current object with a path like '#/components/schemas/<global name>'.
- Ensure that no other inline schemas are defined.
- If you wish to retain the inline schema definition, try adding a
titleproperty in the Schema Object definition with a unique name to improve output.