Skip to main content



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.

Maximum SeverityWarning
MessageInline complex schema definition found.
Rule SystemSemantic
Broad CategoryOpenAPI Schemas
Products ImpactedAPI Transformer, Code Generation, Developer Experience Portal
Tagsopenapi3 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 title property in the Schema Object definition with a unique name to improve output.

For More Information