.spectral.yml

extends: spectral:oas
functions:
  [objectRequiredProperties, operationOrdering, requiredPropertyExample]
rules:
  example-value-or-externalValue: false
  oas3-unused-components-schema: false # needed by inter-file references e.g. Voice API
  oas3-valid-content-schema-example: false
  oas3-valid-oas-content-example: false
  oas3-valid-oas-parameter-example: false
  oas3-valid-parameter-schema-example: false
  oas3-valid-schema-example: false
  openapi-tags: false
  operation-description: false
  operation-tags: false

  # OperationId related linting
  operation-operationId: "error"
  operation-operationId-unique: "error"

  # Check field names meet api standards
  property-names:
    severity: warn
    message: "Invalid property name: {{value}} (expected: lowercase with underscores)"
    recommended: true
    given: "$.paths.*.*.parameters.*.name"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z_]+$"

  # Check response field names meet api standards
  response-property-names:
    severity: warn
    message: "Invalid response property name: {{property}} (expected: lowercase with underscores)"
    recommended: true
    given: "$..components.schemas.*.properties[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z_]+$"

  # Require 3-part Semantic Versions as the spec versions
  semver:
    severity: error
    recommended: true
    message: Specs should follow semantic versioning. {{value}} is not a valid version.
    given: $.info.version
    then:
      function: pattern
      functionOptions:
        match: "^([0-9]+.[0-9]+.[0-9]+)$"

  # We always require a summary
  operation-required-fields:
    severity: error
    message: Missing {{property}}at {{path}}
    given: $.paths.*[get,post,patch,put,delete]
    then:
      - field: "summary"
        function: truthy

  # Any required objects must also have a required child parameter
  required-object-params:
    severity: error
    given: $.paths.*.[post].requestBody.content.*.[?(@.required)]
    then:
      function: objectRequiredProperties

  # Order for endpoints should bet GET, POST, PATCH, PUT, DELETE
  endpoint-verb-order:
    severity: error
    given: $.paths[?(@.get || @.post || @.patch || @.put || @.delete)]
    then:
      function: operationOrdering

  # Array objects should not have an example, but delegate to the object properties
  array-object-example:
    severity: error
    message: Did not expect {{property}}at {{path}}. Define 'example' data on each property in the object instead
    given: $.paths.*.*.requestBody..[?(@.items)][?(@.type == 'object')]
    then:
      - field: "example"
        function: falsy

  # All required properties must have an example
  required-property-example:
    severity: error
    given: $..[?(@.type == 'object' && @.required)]
    then:
      - function: requiredPropertyExample

# VBC
except:
  # VGIS Exceptions - We don't know what the example should look like
  "definitions/vonage-business-cloud/vgis.yml#/components/schemas/Event":
    - required-property-example
  "definitions/vonage-business-cloud/vgis.yml#/components/schemas/Call":
    - required-property-example
  "definitions/vonage-business-cloud/vgis.yml#/components/schemas/CallCreate":
    - required-property-example
  "definitions/vonage-business-cloud/vgis.yml#/components/schemas/CallTransfer":
    - required-property-example