.spectral.yml

extends: ["spectral:oas"]

functions:
  - definedNotExample
rules:
  path-params: off
  operation-operationId: off
  oas3-examples-value-or-externalValue: off
  oas3-unused-component: off
  info-contact: off
  write-email-not-e-mail:
    description: Should use email instead of e-mail in descriptions
    severity: error
    given: "$..*[?(@property === 'description')]"	
    then:
      function: pattern
      functionOptions:
        notMatch: "\\be-mail\\b"

  must-include-operation-summary:
    description: Operation summary should be included
    severity: error
    given: "$.paths.*[?( @property === 'get' || @property === 'put' || @property === 'post' || @property === 'delete' || @property === 'options' || @property === 'head' || @property === 'patch' || @property === 'trace' )]"
    then:
      - field: "summary"
        function: defined        

  must-include-response-examples:
    description: At least one example should be included for each API response
    severity: error
    given: "$.paths..responses.*.content.*"
    then:
      - field: "example"
        function: defined

  must-include-response-schemas:
    description: Each API response must contain a schema
    severity: error
    given: "$.paths..responses.*.content.*"
    then:
      - field: "schema"
        function: defined

  no-empty-titles:
    description: There can be no empty titles in schemas. Removing this title field from the property will solve this issue. If this title is inside an example, please fill it with a valid value.
    severity: error
    given: "$..[?(@ && @.title=='')]~"
    then:
      function: pattern
      functionOptions:
        match: "example"

  summaries-should-be-in-sentence-case:
    description: All endpoint summaries should use sentence case (capitalize only the first letter) and never contain periods (`.`). Exceptions include product names and some specific terms (e.g., SKU, ID).
    severity: warn
    given: "$.paths.*.*[?( @property === 'summary')]"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z](?:[a-z0-9 ]*(?:VTEX|TEX|DO|ID|JSON|)|(|OAuth|Customer Credit|CMS|appKey|appToken|-|,|API|DKIM|SKU|SLA|Change order|'))*[a-z0-9 ]*$"

  no-empty-descriptions:
    description: No empty descriptions allowed. Make sure that this description is a valid string that does not start with a line break (\n or \r). If this description is inside an example, please fill it with a valid value.
    severity: error
    given: "$..*[?(@property === 'description')]"
    then:
      function: pattern
      functionOptions:
        match: "^(?!\\s*$).+"

  parameters-description:
    description: Each parameter must contain a description.
    severity: error
    given: "$.paths.*.*.parameters[*]"
    then:
      field: "description"
      function: defined

  properties-description:
    description: Each request or response body property must contain a description.
    severity: error
    given: "$..*[?(@ && @property != 'schema' && (@.type=='object' || @.type=='array' || @.type=='integer' || @.type=='boolean' || @.type=='string' || @.type=='number'))]"
    then:
      field: "description"
      function: definedNotExample

  array-items:
    description: Each array field must contain an "items" property.
    severity: error
    given: "$..[?(@ && @.type == 'array')]"
    then:
      field: "items"
      function: defined

  request-body-items-type:
    description: Each request body array "items" property must contain a type.
    severity: warn
    given: "$.paths.*.*.requestBody.content.*.schema..items"
    then:
      field: "type"
      function: defined

  response-body-items-type:
    description: Each array "items property" in the response body schema must contain a type. 
    severity: warn
    given: "$.paths.*.*.responses.*.content.*.schema..items"
    then:
      field: "type"
      function: defined

  request-body-properties-example:
    description: Each request body property should have an example. In case the schema is also used as a response and there is already an example elsewhere, feel free to ignore this alert. If you have chosen to include a complete example of the schema to better represent arrays, feel free to ignore this alert.
    severity: warn
    given: "$..requestBody..*[?(@ && (@.type=='string' || @.type=='integer' || @.type=='boolean'))]"
    then:
      field: "example"
      function: defined

  response-body-objects-arrays-example:
    description: Response body fields should not contain the "example" field. The response example corresponds to the whole schema.
    severity: warn
    given: "$..responses..*[?(@ && (@.type=='object' || @.type=='array' || @.type=='integer' || @.type=='boolean' || @.type=='string'))]"
    then:
      field: "example"
      function: undefined

  endpoint-permissions:
    description: Endpoint descriptions must include a "Permissions" section, with information about License Manager resources and roles.
    severity: warn
    given: "$.paths.*.*.description"
    then:
      function: pattern
      functionOptions:
        match: "## Permissions"

  must-end-descriptions-with-period:
    description: All field descriptions must end with a period (`.`) or with an unordered list, even if its items don't end in periods. 
    severity: error
    given: "$..properties.*[?(@property === 'description')]"
    then:
      function: pattern
      functionOptions:
        match: ".*(?:\\.$|\\n- |\\r- )"