Configuration Reference

Configuration shape

rules:
  <custom-rule-id>:
    severity: error | warn | off
    type: metadata | parameters | operations | security | schema | examples
    maturity: baseline | bronze | silver | gold | platinum
    message: <text>
    reference: <URL>
    fix:
      - <suggestion>
    on:
      type: <node-type>
      property: <name-or-list>
      filterInParentKeys: [<key>]
      filterOutParentKeys: [<key>]
      matchParentKeys: <regex>
    when:
      - on: <subject>
        must: <assertions>
    must: <assertions>

profiles:
  <profile-name>:
    extends: [<profile-name>]
    types: [<rule-category>]
    rules:
      extends: [starter | lenient | recommended | strict | complete]
      include: [<rule-id>]
      exclude: [<rule-id>]
      override:
        <rule-id>: <severity-or-rule-settings>

Valid rule IDs contain lowercase letters, digits, dots, and hyphens, with optional / followed by letters, digits, dots, underscores, or hyphens. Example: company/operation-summary.

Custom-rule assertions

Assertion	Value
pattern, notPattern	Regex string, or /pattern/ims form
enum	Allowed values
defined	Boolean; defaults to true
required	Required property names
disallowed	Forbidden values/property names
nonEmpty	Boolean; defaults to true
minLength, maxLength	Integer
casing	camelCase, kebab-case, snake_case, PascalCase, MACRO_CASE, COBOL-CASE, or flatcase
sortOrder	asc or desc
mutuallyExclusive	Property names; zero or one may exist
mutuallyRequired	Property names; all or none must exist
requireAny	Property names; at least one must exist
ref	Boolean or regex matched against $ref
const	Required value
contains	Values required in a list

Regex flags: i case-insensitive, m multiline, s dot matches newline. g, u, and y are accepted in slash-form syntax but do not change Kotlin regex evaluation.

Custom-rule node types

Use any to inspect all indexed nodes. Available named types depend on OpenAPI version:

• Core: Root, Info, License, Contact, ExternalDocs, Tag, TagList.
• Servers: Server, ServerList, ServerVariable, ServerVariablesMap.
• Paths: Paths, PathItem, Operation, CallbacksMap, Callback, WebhooksMap.
• Inputs: Parameter, ParameterList, RequestBody, Encoding, EncodingMap.
• Outputs: Responses, Response, Header, HeadersMap, Link, LinksMap.
• Content: MediaType, MediaTypesMap, Example, ExamplesMap.
• Schemas: Schema, SchemaList, SchemaProperties, SchemaOrBoolean, BooleanLiteral, Discriminator, DiscriminatorMapping, DiscriminatorMappingValue, Xml.
• Components: Components, NamedSchemas, NamedResponses, NamedParameters, NamedRequestBodies, NamedHeaders, NamedExamples, NamedPathItems, NamedSecuritySchemes, NamedLinks, NamedCallbacks.
• Security: SecurityScheme, SecurityRequirement, SecurityRequirementList, SecurityRequirementValue, OAuth2Flows, OAuth2Flow, ScopesMap, ScopeDescription.
• Extensions: SpecExtension.

Unknown node types are rejected when linting starts.

Report model

JSON reports contain:

Field	Meaning
version	Linter version
problems	Ordered list of violations
totals.errors	Error count
totals.warnings	Warning count
totals.ignored	Ignored count
maturity.level	Assessed maturity, when configured
notes	Informational messages

Each problem may contain ruleId, severity, message, type, location, from, reference, requiredForMaturity, and suggest. Locations may contain source reference, JSON Pointer, line, and column.