Skip to main content

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 or should define title property alongside the properties property. Inline definitions of such schemas aren't recommended as for auto generating SDKs/documentation the names of such schemas are deduced from the parent objects in which they're 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.

PropertyValue
EnabledYes
Maximum SeverityWarning
MessageInline complex schema definition found.
CodeOPENAPI3APIMATIC_L662
TypeLinting
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 aren't using any of these constructs in your schema if it's an inline schema definition: allOf, anyOf, oneOf, not, properties.
  • Add title property alongside the properties property in the schema definition.
  • 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​