.spectral.yml

extends: [[spectral:oas, all]]

functionsDir: ./src/spectral/

functions:
  - ensureSimpleDescription
  - validateOperationIdFormat
  - ensurePropertiesExample
  - ensureAllOfOrder
  - ensureLocalReferencesInAllOf
  - ensureAllArraysHaveItemTypes
  - ensureCorrectVerbsInTitles
  - ensureNoArticlesInTitles
  - ensureTagExists
  - ensureSchemaHasType
  - ensureNoCircularReferences

rules:
  tag-description: false
  example-value-or-externalValue: false
  operation-summary-formatted: false
  oas3-unused-components-schema: false
  oas3-valid-oas-content-example: false
  
  ensure-endpoint-summary:
    description: Endpoints must have a summary.
    given: $.paths[*][*]
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      field: summary
      function: truthy

  ensure-response-description:
    description: Responses must have a description.
    given: $.components.schemas[*]
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      field: description
      function: truthy

  ensure-param-description:
    description: Parameters must have a description.
    given: $..*.parameters[*]
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      field: description
      function: truthy

  ensure-properties-description:
    description: Properties must have a description.
    given: $..*.properties[*]
    severity: error
    recommended: true
    resolved: true
    message: "{{error}}"
    then:
      function: ensureSimpleDescription

  ensure-operation-id-format:
    description: An operation ID must follow our required format
    given: $.paths[*][*]
    severity: error
    recommended: true
    resolved: true
    message: "{{error}}"
    then:
      function: validateOperationIdFormat

  ensure-param-examples:
    description: Parameters must have examples.
    given: $..*.parameters[*]
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      field: example
      function: truthy

  ensure-properties-example:
    description: Properties must have examples.
    given: $..*.properties[*]
    severity: error
    recommended: true
    resolved: true
    message: "{{error}}"
    then:
      function: ensurePropertiesExample

  ensure-additional-properties-example:
    description: Additional properties must have examples.
    given: $..*.additionalProperties
    severity: error
    recommended: true
    resolved: true
    message: "{{error}}"
    then:
      function: ensurePropertiesExample

  ensure-additional-properties-oneof-example:
    description: Additional properties (oneOf) must have examples.
    given: $..*.additionalProperties.oneOf[*]
    severity: error
    recommended: true
    resolved: true
    message: "{{error}}"
    then:
      function: ensurePropertiesExample

  ensure-allof-order:
    description: Ensures order of items in an allOf
    given: '$..*.allOf'
    severity: error
    recommended: true
    resolved: false
    message: "{{error}}"
    then:
      function: ensureAllOfOrder

  # ensure-local-references-in-allof:
  #   description: Ensures order of items in an allOf for properties
  #   given: '$.paths..*.properties..*'
  #   severity: error
  #   recommended: true
  #   resolved: false
  #   message: "{{error}}"
  #   then:
  #     function: ensureLocalReferencesInAllOf

  ensure-array-properties-have-items-with-type:
    description: Ensures all array properties have an items attribute with a type
    given: '$..*.properties[*]'
    severity: error
    recommended: true
    resolved: false
    message: "{{error}}"
    then:
      function: ensureAllArraysHaveItemTypes

  ensure-array-params-have-items-with-type:
    description: Ensures all array parameters have an items attribute with a type
    given: '$..*.parameters[*]'
    severity: error
    recommended: true
    resolved: false
    message: "{{error}}"
    then:
      function: ensureAllArraysHaveItemTypes

  ensure-every-endpoint-has-a-reference-group:
    description: Ensures every endpoint belongs to a reference category
    given: $.paths[*][*]
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      field: 'x-box-tag'
      function: truthy

  ensure-every-resource-has-title:
    description: Ensures every resource has a title
    given: '$.components.schemas[*]'
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      field: 'title'
      function: truthy

  ensure-correct-verb-title:
    description: Titles must have the right verbs
    given: $.paths[*][*]
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      function: ensureCorrectVerbsInTitles

  ensure-no-articles-in-titles:
    description: Titles should not have "a" or "an" or "the"
    given: $.paths[*][*]
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      function: ensureNoArticlesInTitles

  ensure-tag-exists:
    description: Ensure an x-box-tag value exists
    given: $..*[x-box-tag]
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      function: ensureTagExists

  ensure-schema-has-type:
    description: Schemas must have a type
    given: $..schema
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      function: ensureSchemaHasType

  ensure-no-circular-references:
    description: Should not contain any cicular references
    given: $
    severity: error
    recommended: true
    message: "{{error}}"
    then:
      function: ensureNoCircularReferences